home / skills / itsmostafa / aws-agent-skills / cloudformation

cloudformation skill

safe

This skill helps you author, deploy, and troubleshoot AWS CloudFormation templates and stacks with best practices and drift detection.

npx playbooks add skill itsmostafa/aws-agent-skills --skill cloudformation

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

9.6 KB

---
name: cloudformation
description: AWS CloudFormation infrastructure as code for stack management. Use when writing templates, deploying stacks, managing drift, troubleshooting deployments, or organizing infrastructure with nested stacks.
last_updated: "2026-01-07"
doc_source: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/
---

# AWS CloudFormation

AWS CloudFormation provisions and manages AWS resources using templates. Define infrastructure as code, version control it, and deploy consistently across environments.

## Table of Contents

- [Core Concepts](#core-concepts)
- [Common Patterns](#common-patterns)
- [CLI Reference](#cli-reference)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)
- [References](#references)

## Core Concepts

### Templates

JSON or YAML files defining AWS resources. Key sections:
- **Parameters**: Input values
- **Mappings**: Static lookup tables
- **Conditions**: Conditional resource creation
- **Resources**: AWS resources (required)
- **Outputs**: Return values

### Stacks

Collection of resources managed as a single unit. Created from templates.

### Change Sets

Preview changes before executing updates.

### Stack Sets

Deploy stacks across multiple accounts and regions.

## Common Patterns

### Basic Template Structure

```yaml
AWSTemplateFormatVersion: '2010-09-09'
Description: My infrastructure template

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, prod]
    Default: dev

Mappings:
  EnvironmentConfig:
    dev:
      InstanceType: t3.micro
    prod:
      InstanceType: t3.large

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

Resources:
  MyBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub 'my-app-${Environment}-${AWS::AccountId}'
      VersioningConfiguration:
        Status: !If [IsProd, Enabled, Suspended]

Outputs:
  BucketName:
    Description: S3 bucket name
    Value: !Ref MyBucket
    Export:
      Name: !Sub '${AWS::StackName}-BucketName'
```

### Deploy a Stack

**AWS CLI:**

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

# Wait for completion
aws cloudformation wait stack-create-complete --stack-name my-stack

# Update stack
aws cloudformation update-stack \
  --stack-name my-stack \
  --template-body file://template.yaml \
  --parameters ParameterKey=Environment,ParameterValue=prod

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

### Use Change Sets

```bash
# Create change set
aws cloudformation create-change-set \
  --stack-name my-stack \
  --change-set-name my-changes \
  --template-body file://template.yaml \
  --parameters ParameterKey=Environment,ParameterValue=prod

# Describe changes
aws cloudformation describe-change-set \
  --stack-name my-stack \
  --change-set-name my-changes

# Execute change set
aws cloudformation execute-change-set \
  --stack-name my-stack \
  --change-set-name my-changes
```

### Lambda Function

```yaml
Resources:
  LambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: !Sub '${AWS::StackName}-function'
      Runtime: python3.12
      Handler: index.handler
      Role: !GetAtt LambdaRole.Arn
      Code:
        ZipFile: |
          def handler(event, context):
              return {'statusCode': 200, 'body': 'Hello'}
      Environment:
        Variables:
          ENVIRONMENT: !Ref Environment

  LambdaRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```

### VPC with Subnets

```yaml
Resources:
  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/16
      EnableDnsHostnames: true
      Tags:
        - Key: Name
          Value: !Sub '${AWS::StackName}-vpc'

  PublicSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      AvailabilityZone: !Select [0, !GetAZs '']
      CidrBlock: 10.0.1.0/24
      MapPublicIpOnLaunch: true

  PrivateSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      AvailabilityZone: !Select [0, !GetAZs '']
      CidrBlock: 10.0.10.0/24

  InternetGateway:
    Type: AWS::EC2::InternetGateway

  AttachGateway:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      VpcId: !Ref VPC
      InternetGatewayId: !Ref InternetGateway

  PublicRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref VPC

  PublicRoute:
    Type: AWS::EC2::Route
    DependsOn: AttachGateway
    Properties:
      RouteTableId: !Ref PublicRouteTable
      DestinationCidrBlock: 0.0.0.0/0
      GatewayId: !Ref InternetGateway

  PublicSubnet1RouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref PublicSubnet1
      RouteTableId: !Ref PublicRouteTable
```

### DynamoDB Table

```yaml
Resources:
  OrdersTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: !Sub '${AWS::StackName}-orders'
      AttributeDefinitions:
        - AttributeName: PK
          AttributeType: S
        - AttributeName: SK
          AttributeType: S
        - AttributeName: GSI1PK
          AttributeType: S
        - AttributeName: GSI1SK
          AttributeType: S
      KeySchema:
        - AttributeName: PK
          KeyType: HASH
        - AttributeName: SK
          KeyType: RANGE
      GlobalSecondaryIndexes:
        - IndexName: GSI1
          KeySchema:
            - AttributeName: GSI1PK
              KeyType: HASH
            - AttributeName: GSI1SK
              KeyType: RANGE
          Projection:
            ProjectionType: ALL
      BillingMode: PAY_PER_REQUEST
      PointInTimeRecoverySpecification:
        PointInTimeRecoveryEnabled: true
```

## CLI Reference

### Stack Operations

| Command | Description |
|---------|-------------|
| `aws cloudformation create-stack` | Create stack |
| `aws cloudformation update-stack` | Update stack |
| `aws cloudformation delete-stack` | Delete stack |
| `aws cloudformation describe-stacks` | Get stack info |
| `aws cloudformation list-stacks` | List stacks |
| `aws cloudformation describe-stack-events` | Get events |
| `aws cloudformation describe-stack-resources` | Get resources |

### Change Sets

| Command | Description |
|---------|-------------|
| `aws cloudformation create-change-set` | Create change set |
| `aws cloudformation describe-change-set` | View changes |
| `aws cloudformation execute-change-set` | Apply changes |
| `aws cloudformation delete-change-set` | Delete change set |

### Template

| Command | Description |
|---------|-------------|
| `aws cloudformation validate-template` | Validate template |
| `aws cloudformation get-template` | Get stack template |
| `aws cloudformation get-template-summary` | Get template info |

## Best Practices

### Template Design

- **Use parameters** for environment-specific values
- **Use mappings** for static lookup tables
- **Use conditions** for optional resources
- **Export outputs** for cross-stack references
- **Add descriptions** to parameters and outputs

### Security

- **Use IAM roles** instead of access keys
- **Enable termination protection** for production
- **Use stack policies** to protect resources
- **Never hardcode secrets** — use Secrets Manager

```bash
# Enable termination protection
aws cloudformation update-termination-protection \
  --stack-name my-stack \
  --enable-termination-protection
```

### Organization

- **Use nested stacks** for complex infrastructure
- **Create reusable modules**
- **Version control templates**
- **Use consistent naming conventions**

### Reliability

- **Use DependsOn** for explicit dependencies
- **Configure creation policies** for instances
- **Use update policies** for Auto Scaling groups
- **Implement rollback triggers**

## Troubleshooting

### Stack Creation Failed

```bash
# Get failure reason
aws cloudformation describe-stack-events \
  --stack-name my-stack \
  --query 'StackEvents[?ResourceStatus==`CREATE_FAILED`]'

# Common causes:
# - IAM permissions
# - Resource limits
# - Invalid property values
# - Dependency failures
```

### Stack Stuck in DELETE_FAILED

```bash
# Identify resources that couldn't be deleted
aws cloudformation describe-stack-resources \
  --stack-name my-stack \
  --query 'StackResources[?ResourceStatus==`DELETE_FAILED`]'

# Retry with resources to skip
aws cloudformation delete-stack \
  --stack-name my-stack \
  --retain-resources ResourceLogicalId1 ResourceLogicalId2
```

### Drift Detection

```bash
# Detect drift
aws cloudformation detect-stack-drift --stack-name my-stack

# Check drift status
aws cloudformation describe-stack-drift-detection-status \
  --stack-drift-detection-id abc123

# View drifted resources
aws cloudformation describe-stack-resource-drifts \
  --stack-name my-stack
```

### Rollback Failed

```bash
# Continue update rollback
aws cloudformation continue-update-rollback \
  --stack-name my-stack \
  --resources-to-skip ResourceLogicalId1
```

## References

- [CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/)
- [CloudFormation API Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/)
- [CloudFormation CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/)
- [Resource and Property Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)

Overview

This skill provides practical guidance and commands for managing AWS CloudFormation stacks and templates. It focuses on infrastructure as code workflows: writing templates, deploying and updating stacks, managing drift, and troubleshooting deployment failures. The content is organized for quick reference with examples, CLI commands, and patterns for common resources.

How this skill works

It explains core CloudFormation concepts (templates, stacks, change sets, stack sets) and shows YAML examples for common resources like VPCs, Lambda, DynamoDB, and S3. The skill includes CLI snippets for create/update/delete, change set workflows, drift detection, and rollback handling. It also provides best practices for template design, security, organization, and reliability to make deployments predictable and auditable.

When to use it

Writing or revising CloudFormation templates for repeatable infra provisioning
Deploying or updating stacks across dev, staging, and prod environments
Previewing changes safely using change sets before applying updates
Troubleshooting failed stack operations, rollbacks, or delete failures
Detecting and reconciling drift between deployed resources and templates

Best practices

Use parameters, mappings, and conditions to make templates reusable and environment-aware
Export outputs and use nested stacks or reusable modules for complex architectures
Prefer IAM roles over access keys and never hardcode secrets; use Secrets Manager
Enable termination protection and stack policies for production stacks
Validate templates with aws cloudformation validate-template and use change sets to preview updates

Example use cases

Create a CI/CD pipeline step that validates and deploys CloudFormation templates to multiple environments
Define a VPC with public and private subnets and attach an Internet Gateway in a single template
Deploy a Lambda function and its IAM role, with inline code for small utilities or proofs of concept
Provision a DynamoDB table with GSIs and point-in-time recovery configured
Use drift detection to identify manual changes and bring stacks back to the desired state

FAQ

How do I preview changes before updating a stack?

Create a change set with aws cloudformation create-change-set, then inspect it with aws cloudformation describe-change-set before executing.

What should I do when a stack is stuck in DELETE_FAILED?

Describe stack resources to find failures, then retry delete with --retain-resources for problematic resources or delete them manually and retry the stack deletion.