Claude Code × AWS CloudFormation/CDK Guia Completo | Gere Infraestrutura como Código Automaticamente

“Odeio ter que ficar clicando no Console da AWS toda vez que preciso configurar infraestrutura” — se você já se sentiu assim, não está sozinho. CloudFormation e CDK tornam a infraestrutura reproduzível por meio de código, mas escrever esses templates leva tempo.

Eu gerencio a infraestrutura deste site (Cloudflare Pages + Workers + D1) com Claude Code, e para infraestrutura AWS em produção também deixo o Claude Code gerar templates CloudFormation/CDK. Templates que antes levavam horas agora ficam prontos em 1/5 do tempo.

---

CloudFormation vs CDK: Qual Escolher?

CloudFormation: Serviço nativo AWS que descreve infraestrutura em JSON/YAML
CDK (Cloud Development Kit): Framework que descreve infraestrutura em TypeScript/Python
                              e sintetiza para CloudFormation

Comparação	CloudFormation	CDK
Linguagem	JSON / YAML	TypeScript, Python, Java, etc.
Type Safety	Nenhuma	Excelente (totalmente type-safe com TypeScript)
Reusabilidade	Baixa (copiar-colar)	Alta (abstraída com classes e funções)
Curva de Aprendizado	Baixa	Média
Compatibilidade Claude Code	Excelente	Excepcional

Para novos projetos, CDK TypeScript é fortemente recomendado. Sua compatibilidade com Claude Code é excepcional e, combinada com o autocompletar de tipos, produz código de alta qualidade.

---

Passo 1: Converter Recursos AWS Existentes para CloudFormation

Um padrão útil quando você quer codificar um ambiente AWS existente retroativamente.

claude -p "
Converta a seguinte configuração AWS em um template CloudFormation (YAML).

[Configuração atual]
- VPC: 10.0.0.0/16, 2 sub-redes públicas, 2 sub-redes privadas
- EC2: t3.medium, Amazon Linux 2023, na sub-rede pública
- RDS: MySQL 8.0, db.t3.micro, na sub-rede privada
- ALB: HTTPS (certificado ACM), encaminhando para EC2
- Security Groups: permitir 443 do ALB, permitir 3306 do EC2 para RDS

[Requisitos]
- Ambiente (dev/staging/prod) alternável via parâmetro
- Prefixar nomes de recursos com o nome do ambiente
- Exibir nome DNS do ALB nos Outputs do CloudFormation
"

Template CloudFormation gerado (trecho):

AWSTemplateFormatVersion: "2010-09-09"
Description: "Web Application Infrastructure"

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, prod]
    Default: dev
  DBPassword:
    Type: String
    NoEcho: true  # Mascarar a senha

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

  PublicSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: 10.0.1.0/24
      AvailabilityZone: !Select [0, !GetAZs ""]
      MapPublicIpOnLaunch: true
      Tags:
        - Key: Name
          Value: !Sub "${Environment}-public-1"

  # Security Group do ALB
  ALBSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: ALB Security Group
      VpcId: !Ref VPC
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 443
          ToPort: 443
          CidrIp: 0.0.0.0/0

Outputs:
  ALBDnsName:
    Value: !GetAtt ApplicationLoadBalancer.DNSName
    Export:
      Name: !Sub "${Environment}-alb-dns"

---

Passo 2: Construir um Stack Serverless com CDK

Com CDK, escreve-se em TypeScript, facilitando a reutilização de lógica.

# Inicializar projeto CDK
mkdir my-infra && cd my-infra
npx cdk init app --language typescript

claude -p "
Implemente a seguinte configuração serverless em CDK TypeScript em lib/my-infra-stack.ts.

[Configuração]
- API Gateway (REST API) + Lambda (Node.js 20)
- Tabela DynamoDB (PAY_PER_REQUEST)
- Bucket S3 (privado, versionamento habilitado)
- CloudFront (origem S3, suporte a domínio personalizado)
- Passar nome da tabela DynamoDB e nome do bucket S3 como variáveis de ambiente do Lambda
- Anexar automaticamente role IAM de mínimo privilégio ao Lambda

Taguear todos os recursos adequadamente,
e habilitar proteção contra exclusão em produção (NODE_ENV=production).
"

Código CDK gerado:

// lib/my-infra-stack.ts
import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigateway from "aws-cdk-lib/aws-apigateway";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as cloudfront from "aws-cdk-lib/aws-cloudfront";
import * as origins from "aws-cdk-lib/aws-cloudfront-origins";

export class MyInfraStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const isProd = process.env.NODE_ENV === "production";

    // Tabela DynamoDB
    const table = new dynamodb.Table(this, "AppTable", {
      partitionKey: { name: "PK", type: dynamodb.AttributeType.STRING },
      sortKey: { name: "SK", type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      pointInTimeRecovery: true,
      deletionProtection: isProd,
      removalPolicy: isProd ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
    });

    // Bucket S3
    const bucket = new s3.Bucket(this, "AssetsBucket", {
      versioned: true,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      encryption: s3.BucketEncryption.S3_MANAGED,
      deletionProtection: isProd,
      removalPolicy: isProd ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
    });

    // Função Lambda
    const apiLambda = new lambda.Function(this, "ApiLambda", {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: "index.handler",
      code: lambda.Code.fromAsset("src/lambda"),
      environment: {
        TABLE_NAME: table.tableName,
        BUCKET_NAME: bucket.bucketName,
        NODE_ENV: process.env.NODE_ENV ?? "development",
      },
      timeout: cdk.Duration.seconds(30),
      memorySize: 512,
    });

    // Conceder permissões mínimas ao Lambda
    table.grantReadWriteData(apiLambda);
    bucket.grantReadWrite(apiLambda);

    // API Gateway
    const api = new apigateway.RestApi(this, "AppApi", {
      restApiName: "MyApp API",
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
      },
    });

    api.root.addProxy({
      defaultIntegration: new apigateway.LambdaIntegration(apiLambda),
    });

    // CloudFront
    const distribution = new cloudfront.Distribution(this, "Distribution", {
      defaultBehavior: {
        origin: new origins.S3Origin(bucket),
        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
      },
    });

    // Saída
    new cdk.CfnOutput(this, "ApiUrl", { value: api.url });
    new cdk.CfnOutput(this, "CloudFrontUrl", { value: distribution.distributionDomainName });
  }
}

---

Passo 3: Atualizar Stacks Existentes e Revisar Diferenças

# Revisar diferenças antes do deploy
npx cdk diff

# Pedir ao Claude Code que explique as diferenças
claude -p "
Leia a saída do cdk diff e explique em português o que mudou.
Preste atenção especial às mudanças em security groups e políticas IAM.

$(npx cdk diff 2>&1)
"

---

Passo 4: Projetar uma Arquitetura Multi-Stack

Infraestrutura em escala de produção é gerenciada dividindo-a em múltiplos stacks.

claude -p "
Projete a seguinte configuração multi-stack em CDK TypeScript.

[Estratégia de divisão de stacks]
- NetworkStack: VPC, sub-redes, security groups
- DatabaseStack: RDS, ElastiCache (depende de NetworkStack)
- ApplicationStack: ECS, ALB, AutoScaling (depende de NetworkStack, DatabaseStack)
- MonitoringStack: Dashboards CloudWatch, alarmes, notificações SNS

Incluir dependências entre stacks e como usar CfnOutput / Fn.importValue.
"

// bin/app.ts
import * as cdk from "aws-cdk-lib";
import { NetworkStack } from "../lib/network-stack";
import { DatabaseStack } from "../lib/database-stack";
import { ApplicationStack } from "../lib/application-stack";
import { MonitoringStack } from "../lib/monitoring-stack";

const app = new cdk.App();
const env = { account: process.env.CDK_ACCOUNT, region: "sa-east-1" };

const network = new NetworkStack(app, "NetworkStack", { env });
const database = new DatabaseStack(app, "DatabaseStack", { env, vpc: network.vpc });
const application = new ApplicationStack(app, "ApplicationStack", {
  env,
  vpc: network.vpc,
  database: database.cluster,
});
new MonitoringStack(app, "MonitoringStack", {
  env,
  alb: application.alb,
  database: database.cluster,
});

---

Passo 5: Deixar o Claude Code Resolver Debugging de CloudFormation/CDK

O Claude Code também pode ajudar a resolver falhas de deploy.

claude -p "
O CDK deploy está falhando com o seguinte erro.
Explique a causa e como corrigir:

$(npx cdk deploy 2>&1 | tail -30)
"

Padrões de falha comuns:

• ROLLBACK_COMPLETE: Deploy anterior falhou, deixando o stack quebrado → executar cdk destroy e fazer novo deploy
• UPDATE_ROLLBACK_FAILED: Conflito com mudanças manuais → resolver manualmente no Console AWS
• Resource already exists: Colisão de nomes com um recurso existente → renomear o recurso ou importá-lo

---

4 Armadilhas Comuns

1. Contornar a proteção contra exclusão com cdk destroy

Em ambientes de desenvolvimento, recursos permanecerão após cdk destroy se não configurar removalPolicy: DESTROY. Em produção, use RETAIN para evitar exclusões acidentais.

2. Ignorar a detecção de drift do CloudFormation

Quando você altera recursos manualmente no Console AWS, o CloudFormation fica fora de sincronia com a realidade (drift). Execute a detecção de drift no Console do CloudFormation uma vez por mês.

3. Escrever segredos diretamente nos templates

# Ruim: senha fica no template
DBPassword: "mysecretpassword"

# Bom: obter do Secrets Manager ou Parameter Store
DBPassword: !Sub "{{resolve:secretsmanager:prod/db-password}}"

4. Negligenciar o versionamento fixo do CDK

Se as versões do CDK não estiverem alinhadas no time no package.json, diferenças aparecerão. Comite o package-lock.json para garantir que todos usem a mesma versão.

---

Resumo

Tarefa	Contribuição do Claude Code
Geração de CloudFormation	YAML completo apenas descrevendo os requisitos
Implementação CDK	Código de infraestrutura type-safe em TypeScript
Design de stacks	Arquitetura de dependências multi-stack
Explicação de diffs	Saída do cdk diff explicada em português
Debugging	Causa e solução a partir dos logs de erro

Infrastructure as Code é algo que todos sabemos que deveríamos fazer, mas ficamos adiando. Com Claude Code, basta descrever “a configuração AWS que eu preciso” e o template está pronto — reduzindo dramaticamente a barreira para adotar IaC.

Artigos Relacionados

• Claude Code × AWS Lambda Guia Completo
• Claude Code × AWS IAM Guia Completo
• Claude Code × AWS DynamoDB Guia Completo

Referências

• Documentação Oficial AWS CDK
• Boas Práticas do CloudFormation
• CDK API Reference