Cloudformation

---
name: cloudformation
description: "Covers AWS CloudFormation: templates (JSON/YAML), stacks, change sets, nested stacks, StackSets, intrinsic functions, custom resources, drift detection, and CDK integration. WHEN: \"CloudFormation\", \"CFN\", \"CloudFormation template\", \"CFN stack\", \"StackSet\", \"change set\", \"CloudFormation drift\", \"cfn-lint\", \"AWS CDK\", \"SAM template\"."
license: MIT
---

# AWS CloudFormation Expert

This skill covers AWS CloudFormation, Amazon's native infrastructure as code service. CloudFormation uses declarative JSON or YAML templates to provision and manage AWS resources as stacks. It is a managed service with no versioning — AWS continuously ships updates.

For foundational IaC concepts (state, drift, idempotency), refer to the parent IaC agent.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md` for stack failures, rollback issues, and resource errors
   - **Architecture** -- Load `references/architecture.md` for stack lifecycle, change set mechanics, and StackSets
   - **Best practices** -- Load `references/best-practices.md` for template design, security, and organizational patterns

2. **Load context** -- Read the relevant reference file.

3. **Recommend** -- Provide CloudFormation YAML templates with explanations.

## Core Concepts

### Template Structure

```yaml
AWSTemplateFormatVersion: '2010-09-09'
Description: 'Production web application infrastructure'

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, production]
    Default: dev
  InstanceType:
    Type: String
    Default: t3.micro

Conditions:
  IsProd: !Equals [!Ref Environment, production]

Mappings:
  RegionAMI:
    us-east-1:
      HVM64: ami-0c55b159cbfafe1f0
    us-west-2:
      HVM64: ami-0a54c984b9f908c81

Resources:
  WebServer:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: !Ref InstanceType
      ImageId: !FindInMap [RegionAMI, !Ref 'AWS::Region', HVM64]
      SecurityGroupIds:
        - !Ref WebSecurityGroup
      Tags:
        - Key: Name
          Value: !Sub '${Environment}-web-server'

  WebSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: Web server security group
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 443
          ToPort: 443
          CidrIp: 0.0.0.0/0

Outputs:
  InstanceId:
    Value: !Ref WebServer
    Export:
      Name: !Sub '${Environment}-WebServerInstanceId'
  PublicIP:
    Value: !GetAtt WebServer.PublicIp
    Condition: IsProd
```

### Intrinsic Functions

| Function | Purpose | Example |
|---|---|---|
| `!Ref` | Reference parameter or resource | `!Ref MyBucket` → bucket name |
| `!GetAtt` | Get resource attribute | `!GetAtt MyBucket.Arn` |
| `!Sub` | String substitution | `!Sub '${AWS::StackName}-bucket'` |
| `!Join` | Join strings | `!Join ['-', [!Ref Env, web]]` |
| `!Select` | Select from list | `!Select [0, !GetAZs '']` |
| `!Split` | Split string | `!Split [',', !Ref SubnetList]` |
| `!If` | Conditional value | `!If [IsProd, t3.large, t3.micro]` |
| `!Equals` | Equality test | `!Equals [!Ref Env, prod]` |
| `!FindInMap` | Lookup from mappings | `!FindInMap [RegionAMI, !Ref 'AWS::Region', HVM64]` |
| `!ImportValue` | Cross-stack reference | `!ImportValue prod-VpcId` |
| `!GetAZs` | Get availability zones | `!GetAZs ''` |
| `!Cidr` | Generate CIDR ranges | `!Cidr [!Ref VpcCidr, 4, 8]` |

### Stack Operations

```bash
# Create stack
aws cloudformation create-stack \
  --stack-name my-app \
  --template-body file://template.yaml \
  --parameters ParameterKey=Environment,ParameterValue=production \
  --capabilities CAPABILITY_IAM

# Update via change set (safe preview)
aws cloudformation create-change-set \
  --stack-name my-app \
  --change-set-name update-v2 \
  --template-body file://template.yaml

aws cloudformation describe-change-set \
  --stack-name my-app \
  --change-set-name update-v2

aws cloudformation execute-change-set \
  --stack-name my-app \
  --change-set-name update-v2

# Delete stack
aws cloudformation delete-stack --stack-name my-app

# Drift detection
aws cloudformation detect-stack-drift --stack-name my-app
aws cloudformation describe-stack-drift-detection-status --stack-drift-detection-id <id>
```

### Nested Stacks

```yaml
Resources:
  NetworkStack:
    Type: AWS::CloudFormation::Stack
    Properties:
      TemplateURL: https://s3.amazonaws.com/mybucket/network.yaml
      Parameters:
        VpcCidr: 10.0.0.0/16

  AppStack:
    Type: AWS::CloudFormation::Stack
    DependsOn: NetworkStack
    Properties:
      TemplateURL: https://s3.amazonaws.com/mybucket/app.yaml
      Parameters:
        VpcId: !GetAtt NetworkStack.Outputs.VpcId
```

### StackSets (Multi-Account/Region)

```bash
# Deploy to multiple accounts and regions
aws cloudformation create-stack-set \
  --stack-set-name security-baseline \
  --template-body file://baseline.yaml \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true

aws cloudformation create-stack-instances \
  --stack-set-name security-baseline \
  --deployment-targets OrganizationalUnitIds=ou-xxxx \
  --regions us-east-1 us-west-2 eu-west-1
```

### Custom Resources

For resources CloudFormation doesn't natively support:

```yaml
Resources:
  CustomDNSRecord:
    Type: Custom::DNSRecord
    Properties:
      ServiceToken: !GetAtt DNSLambda.Arn
      Domain: example.com
      RecordType: A
      Value: 1.2.3.4

  DNSLambda:
    Type: AWS::Lambda::Function
    Properties:
      Runtime: python3.12
      Handler: index.handler
      Code:
        ZipFile: |
          import cfnresponse
          def handler(event, context):
              # Handle Create, Update, Delete
              cfnresponse.send(event, context, cfnresponse.SUCCESS, {})
```

## Resource Policies

```yaml
Resources:
  ProductionDB:
    Type: AWS::RDS::DBInstance
    DeletionPolicy: Retain          # Don't delete on stack delete
    UpdateReplacePolicy: Snapshot   # Snapshot before replacement
    Properties:
      DBInstanceClass: db.r6g.xlarge
      Engine: postgres
```

| Policy | Effect |
|---|---|
| `DeletionPolicy: Retain` | Keep resource when stack is deleted |
| `DeletionPolicy: Snapshot` | Create snapshot before deletion (RDS, EBS) |
| `DeletionPolicy: Delete` | Delete resource (default) |
| `UpdateReplacePolicy: Retain` | Keep old resource during replacement |

## Reference Files

- `references/architecture.md` — Stack lifecycle, change set mechanics, StackSets, CloudFormation Registry, resource providers, macros and transforms
- `references/best-practices.md` — Template design, parameter constraints, cross-stack references, CI/CD integration, cost estimation, CDK vs raw templates
- `references/diagnostics.md` — Stack failures, rollback debugging, resource creation errors, drift detection, circular dependency resolution