AWS Cloud Platform Infrastructure

What you'll learn

Before any Lambda or container runs, something has to create the base infrastructure it sits on — the network, storage, the event bus, the identities. This part maps that base layer and answers the question every team gets wrong at first: which pieces do you build with Terraform, and which with CloudFormation / SAM?

Two layers: the platform vs the services

Everything downstream (Parts 4–6) plugs into a base that already exists. Keep the two layers — and their tools — cleanly separated:

┌─ PLATFORM  (Terraform — shared, stateful, long-lived) ─────────────┐
│  VPC · subnets · security groups · S3 · RDS · EventBridge bus       │
│  ECR · IAM baseline + OIDC · Route53 / ACM · /platform/* SSM params  │
└───────────────────────────────┬────────────────────────────────────┘
                                 │  reads ids/ARNs via {{resolve:ssm:/platform/*}}
┌───────────────────────────────▼────────────────────────────────────┐
│  SERVICES  (SAM / CloudFormation — per-service, deployed often)      │
│  Lambda · API Gateway · EventBridge RULES · scoped IAM · task defs   │
└─────────────────────────────────────────────────────────────────────┘

The base infrastructure

Terraform vs CloudFormation / SAM — who owns what

The dividing line is simple once you see it: state and sharing. If a resource holds data or is used by more than one service, it belongs to the platform (Terraform). If it's compute that one service owns and redeploys, it belongs to that service's stack (SAM / CloudFormation).

Networking: VPC, subnets, security groups

The network is the definition of "shared and long-lived" — build it once in Terraform and publish its ids for services to consume:

# infra/network.tf — the VPC everything runs in (Terraform)
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
}
resource "aws_subnet" "private" {
  count      = 2
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.0.${count.index}.0/24"
}
resource "aws_security_group" "app" {
  vpc_id = aws_vpc.main.id
  # ingress/egress rules…
}
# publish ids so service stacks can read them — the contract
resource "aws_ssm_parameter" "vpc_id" {
  name = "/platform/vpc_id"
  type = "String"
  value = aws_vpc.main.id
}

Shared data & messaging: S3, RDS, EventBridge

Stateful and cross-service resources live in the platform too. If a service stack owned them, tearing that stack down would take the data with it:

# infra/platform.tf — shared, stateful, long-lived (Terraform)
resource "aws_s3_bucket" "documents"      { bucket = "acme-documents-${var.stage}" }
resource "aws_cloudwatch_event_bus" "main" { name  = "acme-events-${var.stage}" }
resource "aws_db_instance" "postgres"     { /* … RDS … */ }

# the contract: publish names/ARNs to SSM for services to read
resource "aws_ssm_parameter" "bucket"    { name="/platform/documents_bucket" type="String" value=aws_s3_bucket.documents.id }
resource "aws_ssm_parameter" "event_bus" { name="/platform/event_bus_name"   type="String" value=aws_cloudwatch_event_bus.main.name }

Per-service compute: Lambda, API Gateway, rules

The service stack owns only its compute, and reads the platform by reference — never hardcoding an id:

# services/documents/template.yaml — per-service compute (SAM)
Resources:
  DocumentsFn:
    Type: AWS::Serverless::Function
    Properties:
      Handler: app.handler
      Runtime: python3.13
      Environment:
        Variables:
          # read what Terraform published — the contract, resolved at deploy
          EVENT_BUS: '{{resolve:ssm:/platform/event_bus_name}}'
          BUCKET:    '{{resolve:ssm:/platform/documents_bucket}}'
      VpcConfig:
        SecurityGroupIds: [ '{{resolve:ssm:/platform/app_sg_id}}' ]
        SubnetIds:        [ '{{resolve:ssm:/platform/private_subnet_ids}}' ]
      Policies:                                    # least-privilege, scoped to shared resources
        - S3CrudPolicy: { BucketName: '{{resolve:ssm:/platform/documents_bucket}}' }
        - EventBridgePutEventsPolicy: { EventBusName: '{{resolve:ssm:/platform/event_bus_name}}' }

How they connect: SSM Parameter Store is the contract

Terraform and SAM never touch each other's state. They meet at SSM Parameter Store: Terraform writes the shared ids under /platform/*; every service template reads them with {{resolve:ssm:…}} at deploy. Change the VPC and nothing in the services needs editing.

Terraform  (platform repo)                    SAM  (service repos)
  writes  /platform/vpc_id            ─────▶    {{resolve:ssm:/platform/vpc_id}}
          /platform/private_subnet_ids          {{resolve:ssm:/platform/private_subnet_ids}}
          /platform/app_sg_id                   {{resolve:ssm:/platform/app_sg_id}}
          /platform/documents_bucket            {{resolve:ssm:/platform/documents_bucket}}
          /platform/event_bus_name              {{resolve:ssm:/platform/event_bus_name}}
          /platform/lambda_role_arn             {{resolve:ssm:/platform/lambda_role_arn}}

IAM & least privilege

• OIDC deploy roles (Terraform) — one role per CI repo, trust scoped to that repo. No long-lived AWS keys anywhere (Part 9).
• Baseline execution role (Terraform) — the shared Lambda role gets only /platform/* SSM read + logs; published as /platform/lambda_role_arn.
• Scoped policies (SAM) — each function adds least-privilege access to the specific bucket/bus it uses via SAM policy templates — never "Action": "*".

Reading the logs when a deploy fails

When a provision or deploy step goes red, work from the outside in: the CI run tells you which step failed, then the cloud tells you why. Three places, in order:

1. CloudFormation stack events — the "why" of a failed SAM / CFN deploy

A SAM / CloudFormation deploy fails as a stack event. The first event that failed carries the real reason — the rest are the rollback cascade:

# find the root-cause failures on a stack
aws cloudformation describe-stack-events --stack-name notes-api-dev \
  --query "StackEvents[?contains(ResourceStatus,'FAILED')].[LogicalResourceId,ResourceStatusReason]" \
  --output table

2. CloudWatch Logs — the application's own errors

# Lambda (SAM): tail a function's logs
sam logs -n DocumentsFn --stack-name notes-api-dev --tail
aws logs tail /aws/lambda/notes-api-dev-DocumentsFn --follow --since 10m

# ECS / Fargate: tail the service's log group
aws logs tail /ecs/notes-api --follow --since 10m

3. The pipeline + Terraform output

The GitHub Actions run shows the failing job and step; the infra job's terraform plan / apply output shows resource-level errors inline. Open the failed run, expand the red step — the AWS error is usually right there before you ever touch the CLI.

Unsticking CloudFormation & a stuck pipeline

A stack's status decides what you can do next. When the pipeline seems to "hang" on a deploy, it's almost always because the stack is in a state that can't be updated — SAM errors "stack … is in ROLLBACK_COMPLETE state and can not be updated". Match the state to the fix:

# ROLLBACK_COMPLETE → delete, then let the pipeline redeploy fresh
aws cloudformation delete-stack --stack-name notes-api-dev
aws cloudformation wait stack-delete-complete --stack-name notes-api-dev

# UPDATE_ROLLBACK_FAILED → continue the rollback, skipping what won't revert
aws cloudformation continue-update-rollback --stack-name notes-api-dev \
  --resources-to-skip StuckLogicalId

A CLAUDE.md for the platform repo

# CLAUDE.md — Platform Infrastructure

## What this is
Shared AWS platform for all services. Terraform owns long-lived/shared/stateful infra;
per-service SAM/CloudFormation stacks own compute and reference the platform via SSM.

## Ownership
- Terraform (this repo): VPC, subnets, security groups, S3, RDS, EventBridge bus,
  ECR, IAM baseline + OIDC, Route53/ACM, and the /platform/* SSM parameters.
- SAM/CFN (service repos): Lambda, API Gateway, per-service EventBridge rules,
  scoped IAM. They READ /platform/* via {{resolve:ssm:...}} — never hardcode ids.

## Rules
- Stateful or shared → Terraform. A service stack must NEVER create a bucket/DB/bus.
- Publish every shared id/ARN/name to /platform/* so services stay decoupled.
- Least privilege: OIDC deploy roles per repo; scoped execution roles per function.
- Deletion protection on stateful resources (RDS, prod buckets).

## Commands
- terraform plan (review!) → terraform apply, per stage.

## Verify
- terraform plan is clean; /platform/* params resolve; a service that reads them deploys.

Let Claude Code stand up the platform

Brief it like an engineer — name the pieces, the tool boundary, and the contract, and insist on a plan before apply:

> Stand up the base AWS platform for the dev stage in Terraform:
  a VPC (2 private + 2 public subnets, 1 NAT), a shared app security
  group, an S3 documents bucket, an EventBridge bus, an ECR repo, and
  a GitHub OIDC deploy role. Publish vpc id, subnet ids, sg id, bucket
  name, bus name, and role ARN to /platform/* SSM parameters.
  Keep IAM least-privilege and put deletion protection on the bucket.
  Do NOT create any Lambda or API Gateway — those live in the service
  SAM templates and read these params. Show me `terraform plan` first.