Af Environment Infrastructure

Usage pattern:

doppler run --project gi --config prd -- bash -c '
  AWS_ACCESS_KEY_ID=$DOMAIN_ADMIN_AWS_ACCESS_KEY_ID \
  AWS_SECRET_ACCESS_KEY=$DOMAIN_ADMIN_AWS_SECRET_ACCESS_KEY \
  AWS_DEFAULT_REGION=eu-west-2 \
  aws route53 <command>'

Project Registry

project-registry juncan aws        # Show AWS accounts
project-registry list              # All project keys
project-registry find-by-team JKN  # Find project by Linear team key

Doppler Config Mapping

Rules

Credential Rules (MUST)

1. MUST use Doppler for all secrets. No .env files, no hardcoded credentials.

2. MUST use domain admin credentials for Route53 changes. Project-level IAM users typically lack Route53 permissions.

3. MUST assume OrganizationAccountAccessRole for cross-account admin operations when project IAM user lacks permissions:

   CREDS=$(doppler run --project gi --config prd -- aws sts assume-role \
     --role-arn arn:aws:iam::{account-id}:role/OrganizationAccountAccessRole \
     --role-session-name admin-operation --output json)
   

4. MUST store new credentials in Doppler immediately after creation. Never leave credentials in terminal history or temp files.

DNS Rules (MUST)

5. MUST create subdomain hosted zones for new projects, not records in parent zone.

6. MUST add NS delegation records from parent zone to subdomain zone after creation.

7. MUST use ACM certificates in us-east-1 for CloudFront custom domains (CloudFront requirement).

Infrastructure Rules (SHOULD)

8. SHOULD check project registry before creating new resources - the account/config mapping may already exist.

9. SHOULD use CloudFront for public S3 content with custom domains (not S3 website URLs).

10. SHOULD prefer S3 website endpoint as custom origin over OAC when bucket is already public (simpler, no policy changes needed).

Workflows

Workflow: Add Custom Subdomain with CloudFront

When: You need something.project.gaininsight.global pointing to an S3 bucket or other origin.

Steps:

1. Request ACM certificate in us-east-1:

   doppler run --project {project} --config stg -- aws acm request-certificate \
     --domain-name {subdomain}.{project}.gaininsight.global \
     --validation-method DNS \
     --region us-east-1
   

2. Get validation CNAME from certificate:

   doppler run --project {project} --config stg -- aws acm describe-certificate \
     --certificate-arn {arn} --region us-east-1 \
     --query "Certificate.DomainValidationOptions[0].ResourceRecord"
   

3. Add validation record using domain admin credentials:

   doppler run --project gi --config prd -- bash -c '
     AWS_ACCESS_KEY_ID=$DOMAIN_ADMIN_AWS_ACCESS_KEY_ID \
     AWS_SECRET_ACCESS_KEY=$DOMAIN_ADMIN_AWS_SECRET_ACCESS_KEY \
     aws route53 change-resource-record-sets \
       --hosted-zone-id {project-zone-id} \
       --change-batch '"'"'{"Changes":[{"Action":"CREATE","ResourceRecordSet":{...}}]}'"'"''
   

4. Wait for certificate validation (2-5 minutes)

5. Create CloudFront distribution with certificate and custom domain alias

6. Add CNAME record pointing subdomain to CloudFront domain

Workflow: Create New Project Subdomain Zone

When: Setting up a new project that needs *.project.gaininsight.global

Steps:

1. Create hosted zone:

   doppler run --project gi --config prd -- bash -c '
     AWS_ACCESS_KEY_ID=$DOMAIN_ADMIN_AWS_ACCESS_KEY_ID \
     AWS_SECRET_ACCESS_KEY=$DOMAIN_ADMIN_AWS_SECRET_ACCESS_KEY \
     aws route53 create-hosted-zone \
       --name {project}.gaininsight.global \
       --caller-reference "{project}-$(date +%s)"'
   

2. Note the 4 nameservers from the response

3. Add NS delegation to parent zone (Z08261483JJZ016GFVDDQ):

   # Add NS record with the 4 nameservers
   

4. Store zone ID in project documentation (CLAUDE.md)

Workflow: Access Another Account's Resources

When: You need admin access that the project IAM user doesn't have.

Steps:

1. Assume OrganizationAccountAccessRole:

   CREDS=$(doppler run --project gi --config prd -- aws sts assume-role \
     --role-arn arn:aws:iam::{account-id}:role/OrganizationAccountAccessRole \
     --role-session-name {operation-name} --output json)
   
   export AWS_ACCESS_KEY_ID=$(echo $CREDS | jq -r '.Credentials.AccessKeyId')
   export AWS_SECRET_ACCESS_KEY=$(echo $CREDS | jq -r '.Credentials.SecretAccessKey')
   export AWS_SESSION_TOKEN=$(echo $CREDS | jq -r '.Credentials.SessionToken')
   

2. Run commands with elevated permissions

3. Unset credentials when done:

   unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
   

Common Pitfalls

Essential Reading

Procedural Guides

Key Files

Remember:

1. Domain admin creds are in gi/prd Doppler
2. ACM certs for CloudFront must be in us-east-1
3. Check project registry before creating resources
4. Use OrganizationAccountAccessRole for admin operations