Skip to main content

CDK Operations

Amazon CDK is the source of truth for Scottsdale Hub infrastructure topology.

What CDK Owns​

  • Network and subnet design
  • KMS, IAM, and Secrets Manager primitives
  • Aurora, RDS Proxy, Redis, SQS, EventBridge
  • ECS services and ALB integration
  • CloudFront, WAF, DNS, alarms, and dashboards

CDK does not deploy Laravel application code.

Stage Resolution​

Configuration sources:

  • config/dev.ts
  • config/staging.ts
  • config/production.ts

Resolution priority:

  1. -c stage=<name>
  2. STAGE environment variable
  3. default dev

Manual AWS Prerequisites​

Before running CDK deploy commands, manually create the following AWS resources. These cannot be created by CDK but are required by the infrastructure.

1. ALB_CERTIFICATE_ARN (for ALB in us-west-2)​

  1. Go to AWS Certificate Manager → Certificates in the us-west-2 region
  2. Click Request a certificate
    • Domain: *.scottsdalemint.com or hub.scottsdalemint.com
    • Validation method: DNS or Email
  3. Complete validation (wait for certificate to reach "Issued" status)
  4. Copy the ARN from the certificate details page
  5. Paste the ARN into .env.production: 
    ALB_CERTIFICATE_ARN=arn:aws:acm:us-west-2:ACCOUNT_ID:certificate/CERT_ID

2. CLOUDFRONT_CERTIFICATE_ARN (must be in us-east-1)​

CloudFront requires SSL certificates to be in the us-east-1 region only.

  1. Switch to the us-east-1 region in AWS Console
  2. Go to AWS Certificate Manager → Certificates
  3. Click Request a certificate
    • Domain: *.scottsdalemint.com or hub.scottsdalemint.com
    • Validation method: DNS (recommended for automation)
  4. Complete validation (wait for certificate to reach "Issued" status)
  5. Copy the ARN from the certificate details page
  6. Paste the ARN into .env.production: 
    CLOUDFRONT_CERTIFICATE_ARN=arn:aws:acm:us-east-1:ACCOUNT_ID:certificate/CERT_ID

3. ALB_OPERATIONAL_DOMAIN_NAME (Route53 DNS record)​

After the ALB has been created by CDK, wire it to DNS.

  1. Go to Route53 → Hosted zones → select scottsdalemint.com
  2. Click Create record
    • Name: alb-hub (full domain will be alb-hub.scottsdalemint.com)
    • Type: A
    • Alias: Yes
    • Route traffic to: Application Load Balancer
    • Region: us-west-2
    • ALB: Select your ALB from the dropdown
    • Click Create records
  3. Paste the ALB domain name into .env.production: 
    ALB_OPERATIONAL_DOMAIN_NAME=alb-hub.scottsdalemint.com

Quick Verification Checklist​

Before running CDK deploy, verify:

  • ✓ ALB certificate created in us-west-2 with status "Issued"
  • ✓ CloudFront certificate created in us-east-1 with status "Issued"
  • ✓ .env.production contains all three ARNs and domain name
  • ✓ Route53 A record pointing to ALB (may need to wait for ALB to exist first)

Command Reference​

All commands run from the infrastructure directory.

Setup​

cd infrastructure
npm install

Build and Lint​

  • TypeScript compile: npm run build
  • TypeScript watch mode: npm run watch
  • ESLint check: npm run lint

Synthesize CloudFormation​

  • Default (dev): npm run synth
  • Dev: npm run synth:dev
  • Staging: npm run synth:staging
  • Production: npm run synth:production

Diff Changes Before Deploy​

  • Default (dev): npm run diff
  • Dev: npm run diff:dev
  • Staging: npm run diff:staging
  • Production: npm run diff:production

Deploy Stacks​

  • Default (dev): npm run deploy
  • Dev: npm run deploy:dev
  • Staging: npm run deploy:staging
  • Production: npm run deploy:production

All deploy commands verify required IAM service-linked roles before deploying.

Destroy Stacks​

  • Default (dev): npm run destroy
  • Dev: npm run destroy:dev
  • Staging: npm run destroy:staging
  • Production: npm run destroy:production

Direct CDK Commands​

If needed, run CDK directly:

npx cdk ls -c stage=dev
npx cdk synth -c stage=dev
npx cdk diff -c stage=dev
npx cdk deploy --all -c stage=dev
npx cdk destroy --all -c stage=dev

Stack Ordering​

Core deployment sequence:

  1. network
  2. kms
  3. secrets
  4. iam
  5. storage and messaging
  6. data and cache
  7. logging and ecs
  8. edge, dns, alarms, dashboard

Deploying in dependency-aware order reduces failure blast radius and simplifies rollback.

Operational Caveats​

  • CloudFront certificate must be in us-east-1.
  • CloudFront-scoped WAF resources are created only when stage region is us-east-1.
  • ALB certificates should be in workload region.
  • RDS Proxy is the supported DB ingress path for ECS tasks.
  • For dev/staging, ECS desired count can be 0 until first app image deployment.

Infra vs App Deployment Split​

Infrastructure lifecycle:

  • Managed by CDK repo deployment (synth, diff, deploy)

Application lifecycle:

  • Managed by Scottsdale Hub app repo scripts and Bitbucket manual pipelines
  • Builds image, pushes ECR, forces ECS deployment

Use both flows together for complete releases, but do not collapse responsibilities into one pipeline.

Validation Checklist​

  1. Run synth and diff for the target stage.
  2. Confirm expected stack changes only.
  3. Deploy infrastructure changes.
  4. Run app image deployment pipeline.
  5. Validate ALB health, Horizon status, scheduler health, and queue behavior.