Crie sua primeira pilha AWS CDK: Um tutorial para iniciantes

Trabalhando com construções de CDK

Os aplicativos AWS CDK dependem de construções como seus elementos estruturais essenciais. O código da sua infraestrutura se tornará mais modular, passível de manutenção e legível quando você dominar as construções, quer você use construções de serviço incorporadas ou crie padrões reutilizáveis.

Esta seção ensina você a usar construções L2 (alto nível) e a desenvolver construções personalizadas que reduzem padrões repetitivos.

Uso de construções L2

As construções L2 são abstrações nativas do CDK que são mais fáceis de usar do que o CloudFormation bruto (L1). Eles têm padrões sensatos e segurança de tipo, geralmente exigindo menos linhas de código para configurar um recurso do AWS.

Por que usar construções L2?

• Menos boilerplate - menos campos obrigatórios em comparação com L1
• Código Python mais legível e idiomático
• Inclui métodos utilitários como .add_to_role_policy() ou .add_event_notification()
• Gerencia automaticamente as dependências entre os recursos

Exemplo: Criando um bucket S3 usando L2

from aws_cdk import aws_s3 as s3
# Create a versioned and encrypted S3 bucket
bucket = s3.Bucket(
    self,
    "MyBucket",
    versioned=True,
    encryption=s3.BucketEncryption.S3_MANAGED
)

A construção equivalente em L1, s3.CfnBucket, precisaria que todas as propriedades fossem definidas manualmente e que a configuração fosse definida como ditados brutos, o que é muito menos intuitivo.

Outros construtos comuns de L2 incluem:

• lambda_.Function() para o AWS Lambda
• dynamodb.Table() for DynamoDB
• sqs.Queue() para SQS
• sns.Topic() para SNS

Criando construções personalizadas

Sua infraestrutura se expandirá com padrões recorrentes, como a criação de funções Lambda com permissões específicas e buckets S3. Os construtores personalizados são a solução ideal para esse cenário específico.

As construções personalizadas permitem que você combine recursos relacionados em uma única unidade lógica, que pode ser reutilizada em pilhas ou projetos.

Quando você deve criar uma construção personalizada:

• Quando você tem mais de 3 recursos que são sempre provisionados juntos
• Quando você quiser encapsular a lógica reutilizável
• Quando você quiser reduzir a duplicação de código entre pilhas

Exemplo: Um padrão reutilizável de S3 + Lambda

from constructs import Construct
from aws_cdk import aws_s3 as s3, aws_lambda as lambda_
class StorageWithLambda(Construct):
    def __init__(self, scope: Construct, id: str) -> None:
        super().__init__(scope, id)
        # S3 bucket
        self.bucket = s3.Bucket(self, "MyBucket")

        # Lambda function
        self.function = lambda_.Function(
            self,
            "MyFunction",
            runtime=lambda_.Runtime.PYTHON_3_9,
            handler="index.handler",
            code=lambda_.Code.from_asset("lambda")
        )
        # Grant Lambda access to the S3 bucket
        self.bucket.grant_read_write(self.function)

Agora você pode usar essa construção dentro de qualquer pilha como esta:

from my_project.storage_with_lambda import StorageWithLambda
storage = StorageWithLambda(self, "ReusableComponent")

Antes de executar o procedimento acima, crie uma pasta chamada lambda na raiz do projeto e crie um arquivo index.py com o seguinte conteúdo:

def handler(event, context):
    return {
        "statusCode": 200,
        "body": "Hello from Lambda!"
    }

Dicas de reutilização

• Prefixe os arquivos com construct_ ou coloque-os em uma pasta constructs/
• Exponha saídas como self.bucket ou self.function para maior flexibilidade
• Mantenha cada construção focada em uma responsabilidade

Teste e síntese de aplicativos CDK

Depois de escrever o código da infraestrutura, é essencial verificar o que o CDK implantará e, de preferência, testar se as pilhas se comportam conforme o esperado. O AWS CDK fornece ferramentas para sintetizar modelos do CloudFormation e escrever testes automatizados para detectar configurações incorretas antes da implementação.

Sintetizando modelos

O comando cdk synth gera o modelo do CloudFormation a partir do seu código CDK.

cdk synth

Quando você executa isso, o CDK:

• Carrega seu aplicativo (via app.py)
• Resolve todas as construções e pilhas
• Emite modelos YAML/JSON brutos do CloudFormation

Modelo de CloudFormation sintetizado 

Por padrão, a saída vai para o terminal, mas você também pode enviar a saída para um arquivo, se necessário:

cdk synth > template.yaml

Isso é útil quando você:

• Você deseja inspecionar o modelo real antes da implantação
• Você está depurando a estrutura de uma pilha
• Você está compartilhando o modelo com equipes que não estão usando o CDK

Infraestrutura de testes

Embora testar a infraestrutura como código possa parecer incomum, é vantajoso, especialmente quando suas pilhas ficam grandes ou incluem lógica condicional, loops ou construções reutilizáveis.

O AWS CDK oferece o módulo de asserções para testar pilhas sintetizadas.

Escrevendo um teste simples com pytest

Aqui está um exemplo de teste que verifica se um recurso específico (como um bucket S3) está incluído na pilha:

# test/test_cdk_datacamp_stack.py
import aws_cdk as cdk
from aws_cdk.assertions import Template
from cdk_datacamp.cdk_datacamp_stack import CdkDatacampStack
def test_s3_bucket_created():
    app = cdk.App()
    stack = CdkDatacampStack(app, "TestStack")
    template = Template.from_stack(stack)
    # Assert that an S3 bucket exists
    template.resource_count_is("AWS::S3::Bucket", 1)

Para executar os testes, verifique se o site pytest está instalado:

pip install -U pytest

Então, corra:

pytest

Se tudo for aprovado, você verá uma marca de verificação verde. Caso contrário, o resultado do teste informará a você o que está faltando.

Saída do Pytest mostrando a execução bem-sucedida de todos os casos de teste para a pilha do AWS CDK

Você também pode incluir a validação em sua pilha CDK. Os testes de validação são verificações de tempo de execução dentro do código de construção ou de pilha que validam as entradas antes da implantação. Eles ajudam a detectar configurações incorretas ou a impor restrições no início do ciclo de vida do desenvolvimento.

Digamos que você queira passar o bucket_name como uma variável de contexto, mas queremos validar isso:

• O nome do intervalo não está vazio
• Ele atende às regras de nomenclatura do S3 (por exemplo, somente letras minúsculas)

Crie um arquivo chamado test/test_storage_with_lambda.py e adicione o seguinte:

import pytest
from aws_cdk import App, Stack
from cdk_datacamp.storage_with_lambda import StorageWithLambda

def test_missing_bucket_name():
    app = App()
    stack = Stack(app, "TestStack")

    with pytest.raises(ValueError, match="bucket_name is required"):
        StorageWithLambda(stack, "FailingConstruct", bucket_name=None)

def test_bucket_name_uppercase():
    app = App()
    stack = Stack(app, "TestStack")

    with pytest.raises(ValueError, match="must be lowercase"):
        StorageWithLambda(stack, "FailingConstruct", bucket_name="InvalidName")

 Para testar a validação, execute o comando abaixo:

test/test_storage_with_lambda.py

Saída do Pytest mostrando a execução bem-sucedida de todos os casos de teste para a pilha do AWS CDK

Quando você deve usar o teste:

• Você está criando construções ou padrões reutilizáveis.
• A implementação de testes serve para estabelecer requisitos técnicos padrão entre os membros da equipe.
• Você deseja detectar regressões ou alterações não intencionais durante a CI/CD.

Você quer reforçar seus conhecimentos sobre o CDK em uma entrevista? As principais perguntas da entrevista de DevOps da AWS podem ajudar você a se preparar.

Práticas recomendadas e dicas para trabalhar com o AWS CDK

Depois de dominar a criação e a implantação da pilha CDK, você deve seguir as práticas recomendadas para manter o código da infraestrutura limpo, seguro e dimensionável. Esta seção discutirá como estruturar grandes projetos, lidar corretamente com a segurança e integrar o CDK aos pipelines de CI/CD.

Organização de grandes projetos

À medida que seu aplicativo CDK cresce, organizar o código em unidades gerenciáveis torna-se essencial.

Use várias pilhas

Divida sua infraestrutura por área de interesse. Por exemplo:

• NetworkingStack: VPCs, sub-redes, grupos de segurança
• ComputeStack: EC2, Lambda
• StorageStack: S3, DynamoDB

Isso permite que você implemente, teste ou destrua partes da sua infraestrutura de forma independente. Veja como ele pode ser incluído em app.py:

network_stack = NetworkingStack(app, "NetworkingStack")
compute_stack = ComputeStack(app, "ComputeStack")

Você também pode passar recursos entre pilhas usando saídas ou referências.

Criar construções aninhadas reutilizáveis

Encapsule recursos relacionados (como um Lambda e suas permissões) em uma construção personalizada, como você fez com StorageWithLambda. Isso melhora a legibilidade e a reutilização em pilhas ou aplicativos.

Use a configuração específica do ambiente

Ofereça suporte a vários ambientes (desenvolvimento, preparação, produção) usando:

• cdk.json com valores de contexto
• Substituições da CLI: cdk deploy -c env=prod
• Lógica condicional em suas pilhas

env = app.node.try_get_context("env")
if env == "prod":
    bucket_name = "mycompany-prod-logs"

Segurança e permissões

Qualquer projeto de infraestrutura deve priorizar a segurança durante os processos de implementação automatizada do AWS CDK. A seção a seguir demonstra o gerenciamento seguro de recursos do IAM por meio de princípios de privilégio mínimo.

Definir funções de IAM em vez de usar os padrões

Os construtores CDK, que incluem tarefas Lambda ou ECS, criarão automaticamente funções de IAM. Embora seja conveniente, isso pode limitar o seu controle sobre permissões e nomes.

Em vez disso, defina as funções explicitamente:

from aws_cdk import aws_iam as iam

execution_role = iam.Role(
    self,
    "LambdaExecutionRole",
    assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
    description="Custom role for Lambda with least privilege",
    managed_policies=[
        iam.ManagedPolicy.from_aws_managed_policy_name("service-role/AWSLambdaBasicExecutionRole")
    ]
)

Por padrão, essa função permite apenas o registro em log e nada mais.

Aplicar o princípio do menor privilégio

Evite usar "*" em actions ou resources, a menos que seja absolutamente necessário.

Exemplo:

lambda_fn.add_to_role_policy(
    iam.PolicyStatement(
        actions=["*"],
        resources=["*"]
    )
)

Você também pode usar subsídios específicos para recursos, quando disponíveis:

bucket.grant_read(lambda_fn)

Isso gera automaticamente a política necessária com acesso com escopo ao bucket do S3.

Use políticas gerenciadas quando possível

As políticas gerenciadas pelo AWS simplificam a manutenção e reduzem a chance de erros.

iam.ManagedPolicy.from_aws_managed_policy_name("AmazonSQSReadOnlyAccess")

Você pode anexá-las a funções personalizadas para serviços como ECS, Batch ou Step Functions.

Integração de CI/CD

O AWS CDK oferece um poder excepcional por meio de sua capacidade de integração com pipelines de CI/CD contemporâneos. O CDK oferece suporte à entrega de infraestrutura automatizada por meio da implantação de código com controle de versão, que funciona com o GitHub, o GitLab e os serviços nativos da AWS, incluindo o CodePipeline. O sistema reduz os erros humanos, encurta os ciclos de feedback e permite a implementação em vários ambientes.

Ações do GitHub: Automatizando implantações de CDK

Você pode usar o GitHub Actions para sintetizar, diferenciar, testar e implantar pilhas de CDK em cada push ou pull request.

Dê uma olhada no site .github/workflows/deploy.yml:

name: Deploy CDK App

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-python@v4
        with:
          python-version: 3.11

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          npm install -g aws-cdk

      - name: Run unit tests
        run: pytest

      - name: CDK Synth
        run: cdk synth -c environment=prod

      - name: Deploy to AWS
        run: cdk deploy --require-approval never
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Use cdk diff em PRs para visualizar as alterações infra antes de mesclá-las.

CDK pipelines: CI/CD de CDK nativo com o CodePipeline

Para implantações totalmente gerenciadas no AWS, o CDK fornece um módulo chamado aws_cdk.pipelines, que permite que você defina todo o seu pipeline de CI/CD como código, assim como a infraestrutura.

Aqui está um exemplo simplificado:

from aws_cdk import pipelines, SecretValue, Stack
from constructs import Construct
from my_app_stage import MyAppStage  # replace with your actual stage import

class PipelineStack(Stack):
    def __init__(
        self,
        scope: Construct,
        construct_id: str,
        **kwargs
    ) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define the source of the pipeline from a GitHub repository
        source = pipelines.CodePipelineSource.git_hub(
            repo_string="your-org/your-repo",  # GitHub org/repo
            branch="main",
            authentication=SecretValue.secrets_manager("GITHUB_TOKEN")
        )

        # Define the CodePipeline and its synthesis step
        pipeline = pipelines.CodePipeline(
            self,
            "MyAppPipeline",
            synth=pipelines.ShellStep(
                "Synth",
                input=source,
                commands=[
                    "pip install -r requirements.txt",
                    "npm install -g aws-cdk",
                    "cdk synth"
                ]
            )
        )

        # Add an application stage (e.g., production deployment)
        pipeline.add_stage(
            MyAppStage(self, "ProdStage")
        )

No código acima:

• SecretValue.secrets_manager("GITHUB_TOKEN") extrai com segurança seu token do GitHub do Secrets Manager.
• MyAppStage deve ser uma classe que estenda Stage e envolva suas pilhas CDK reais.

Se você estiver implantando sistemas de machine learning, a integração do CDK com práticas de implantação contínua é abordada em nosso curso CI/CD para machine learning.

Conclusão

Este tutorial mostrou a você como construir e implantar a infraestrutura de nuvem em Python por meio das operações do AWS Cloud Development Kit (CDK). Você aprendeu como fazer:

• Crie sua primeira pilha CDK.
• Defina e valide os buckets S3 e as funções Lambda como recursos.
• Organize um projeto por meio de construções personalizadas e padrões de várias pilhas.
• Aplique as práticas recomendadas de segurança por meio do princípio do menor privilégio.
• Automatize as implementações combinando o GitHub Actions com o CDK Pipelines.
• Escreva testes para validar a lógica de sua infraestrutura.

Agora que você implantou seu primeiro aplicativo CDK, aqui estão algumas maneiras de subir de nível:

• Use ambientes parametrizados para desenvolvimento/estágio/produção
• Adicionar alarmes do CloudWatch, API Gateway ou Step Functions
• Explore as construções de CDK como aws_s3_deployment, aws_ecs_patterns e cdk.pipelines
• Converta suas construções em uma biblioteca interna do Python para reutilização

Para que você continue aprendendo e construindo, confira o curso Introdução ao AWS Boto em Python.você pode conferir o curso Introdução ao AWS Boto em Python!