DNS Delegation for New Environments

This runbook explains how to set up DNS delegation when creating a new environment (prod, dev, staging).

Background

Orcha uses a subdomain delegation pattern for DNS:

Management Account (333886071599)
└── getorcha.com (root hosted zone)
    ├── Existing records (MX, TXT, www, etc.)
    ├── NS prod.getorcha.com → prod account nameservers
    ├── NS dev.getorcha.com → dev account nameservers
    └── CNAME app.getorcha.com → app.prod.getorcha.com

Workload Accounts
├── orcha-prod (700558745280)
│   └── prod.getorcha.com (hosted zone)
│       └── app.prod.getorcha.com → ALB
│
└── orcha-dev (future)
    └── dev.getorcha.com (hosted zone)
        └── app.dev.getorcha.com → ALB

Each workload account manages its own subdomain. The management account's root hosted zone contains NS delegation records that point to the correct nameservers.

When to Run

After deploying Phase 1 (FoundationStack + DataStack) to a new environment. The FoundationStack creates the subdomain hosted zone, but you must manually add the NS delegation in the management account.

Prerequisites

1. Phase 1 deployed - FoundationStack created the subdomain hosted zone
2. AWS CLI profiles configured:
   • orcha - Management account
   • orcha-prod - Production account
   • orcha-dev - Development account (when available)
3. Hosted zone ID from CDK output or AWS Console

Steps

1. Get the Subdomain Hosted Zone ID

From CDK output:

# Check CloudFormation outputs
AWS_PROFILE=orcha-prod aws cloudformation describe-stacks \
  --stack-name V1OrchaProdFoundation \
  --query "Stacks[0].Outputs[?OutputKey=='HostedZoneId'].OutputValue" \
  --output text

Or from Route53:

AWS_PROFILE=orcha-prod aws route53 list-hosted-zones \
  --query "HostedZones[?Name=='prod.getorcha.com.'].Id" \
  --output text

2. Run the Delegation Script

cd /home/volrath/code/orcha/orcha/infra
./scripts/delegate-subdomain.sh prod <HOSTED_ZONE_ID>

The script will:

1. Fetch NS records from the subdomain hosted zone
2. Check for existing delegation
3. Add/update NS record in management account
4. Wait for propagation

3. Verify Delegation

# Should return workload account nameservers (ns-xxx.awsdns-xx.xxx)
dig NS prod.getorcha.com +short

# Test that queries are routed correctly
dig app.prod.getorcha.com +trace

4. Add app.getorcha.com CNAME (Prod Only)

For production, add a convenience CNAME so users can access the app without the prod subdomain:

AWS_PROFILE=orcha aws route53 change-resource-record-sets \
  --hosted-zone-id Z02414383CQNYTPGX2EIK \
  --change-batch '{
    "Changes": [{
      "Action": "CREATE",
      "ResourceRecordSet": {
        "Name": "app.getorcha.com",
        "Type": "CNAME",
        "TTL": 300,
        "ResourceRecords": [{"Value": "app.prod.getorcha.com"}]
      }
    }]
  }'

Troubleshooting

Script fails with "Could not fetch NS records"

Cause: Wrong hosted zone ID or missing permissions.

Fix:

1. Verify the hosted zone ID exists:

   AWS_PROFILE=orcha-prod aws route53 get-hosted-zone --id <HOSTED_ZONE_ID>
   

2. Check you're using the correct profile for the environment.

dig returns NXDOMAIN after delegation

Cause: DNS propagation not complete.

Fix: Wait 5-10 minutes and try again. Full propagation can take up to 48 hours in rare cases.

ACM certificate validation stuck

Cause: NS delegation not in place before deploying ComputeStack.

Fix:

1. Complete DNS delegation first
2. Wait for propagation (dig NS prod.getorcha.com +short shows correct NS)
3. Delete and recreate the ACM certificate, or wait for ACM to retry validation

Existing delegation has wrong nameservers

Cause: Hosted zone was recreated (different zone = different NS).

Fix: Run the script again. It will detect the existing record and prompt to update.

Reference

Related

• BUILD.md - Infrastructure specification
• PLAN.md - Implementation phases