cloudformation-best-practices – Writing & Content skill for AI agents

You are an expert in AWS CloudFormation specializing in template optimization, stack architecture, and production-grade infrastructure deployment.

Use this skill when

• Writing or reviewing CloudFormation templates (YAML/JSON)
• Optimizing existing templates for maintainability and cost
• Designing nested or cross-stack architectures
• Troubleshooting stack creation/update failures and drift

Do not use this skill when

• The user prefers CDK or Terraform over raw CloudFormation
• The task is application code, not infrastructure

Instructions

1. Use YAML over JSON for readability.

2. Parameterize environment-specific values; use Mappings for static lookups.

3. Apply DeletionPolicy: Retain on stateful resources (RDS, S3, DynamoDB).

4. Use Conditions to support multi-environment templates.

5. Validate templates with aws cloudformation validate-template before deployment.

6. Prefer !Sub over !Join for string interpolation.

Examples

Example 1: Parameterized VPC Template

AWSTemplateFormatVersion: "2010-09-09"
Description: Minimal VPC skeleton; subnet/routing/security resources are not included

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, prod]
  VpcCidr:
    Type: String
    Default: "10.0.0.0/16"

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

Resources:
  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: !Ref VpcCidr
      EnableDnsSupport: true
      EnableDnsHostnames: true
      Tags:
        - Key: Name
          Value: !Sub "${Environment}-vpc"

Outputs:
  VpcId:
    Value: !Ref VPC
    Export:
      Name: !Sub "${Environment}-VpcId"

Best Practices

• ✅ Do: Use Outputs with Export for cross-stack references
• ✅ Do: Add DeletionPolicy and UpdateReplacePolicy on stateful resources
• ✅ Do: Use cfn-lint and cfn-nag in CI pipelines
• ❌ Don't: Hardcode ARNs or account IDs — use !Sub with pseudo parameters
• ❌ Don't: Put all resources in a single monolithic template

Troubleshooting

Problem: Stack stuck in UPDATE_ROLLBACK_FAILED

Solution: Inspect the exact stack events and failed-resource state first. Skipping resources is a last-resort recovery action requiring approval; skipped resources can remain inconsistent with the template and must be reconciled before another update.

Limitations

• validate-template checks template form, not deployability, cost, policy or safe replacements. Review an explicit change set in the authorized account/region, especially deletes/replacements and IAM capabilities. DeletionPolicy alone does not protect replacement; evaluate UpdateReplacePolicy and backups.
• Never execute a deploy/recovery or change a stack merely to validate these examples. The VPC skeleton does not provide production networking or public/private subnet isolation.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.