Este é o Guia do Desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.

Práticas recomendadas para desenvolver e implantar infraestrutura de nuvem com o AWS CDK

Com o AWS CDK, desenvolvedores ou administradores podem definir sua infraestrutura de nuvem usando uma linguagem de programação compatível. Os aplicativos do CDK devem ser organizados em unidades lógicas, como API, banco de dados e recursos de monitoramento, e, opcionalmente, ter um pipeline para implantações automatizadas. As unidades lógicas devem ser implementadas como constructos, incluindo as seguintes:

As pilhas definem o modelo de implantação dessas unidades lógicas. Para uma introdução mais detalhada aos conceitos por trás do CDK, consulte Conceitos básicos da AWS CDK.

O AWS CDK reflete uma análise cuidadosa das necessidades de nossos clientes e equipes internas e dos padrões de falha que geralmente surgem durante a implantação e a manutenção contínua de aplicativos complexos na nuvem. Descobrimos que as falhas geralmente estão relacionadas a alterações “fora de banda” em um aplicativo que não foram totalmente testadas, como alterações de configuração. Portanto, desenvolvemos o AWS CDK em torno de um modelo no qual todo o seu aplicativo é definido em código, não apenas na lógica de negócios, mas também na infraestrutura e na configuração. Dessa forma, as mudanças propostas podem ser cuidadosamente analisadas, testadas de forma abrangente em ambientes semelhantes aos de produção em vários graus e totalmente revertidas se algo der errado.

No momento da implantação, o AWS CDK sintetiza um conjunto de nuvem que contém o seguinte:

Com o CDK, cada confirmação na ramificação principal de controle de versão do seu aplicativo pode representar uma versão completa, consistente e implantável do seu aplicativo. Seu aplicativo pode então ser implantado automaticamente sempre que uma alteração for feita.

A filosofia por trás do AWS CDK leva às nossas práticas recomendadas, que dividimos em quatro grandes categorias.

Práticas recomendadas para organizações

Nos estágios iniciais da adoção do AWS CDK, é importante considerar como preparar sua organização para o sucesso. É uma ótima prática ter uma equipe de especialistas responsável por treinar e orientar o resto da empresa à medida que eles adotam o CDK. O tamanho dessa equipe pode variar, desde uma ou duas pessoas em uma pequena empresa até um Centro de Excelência da Nuvem (CCoE) completo em uma empresa maior. Essa equipe é responsável por definir padrões e políticas para a infraestrutura de nuvem em sua empresa e também por treinar e orientar desenvolvedores.

O CCoE pode fornecer orientação sobre quais linguagens de programação devem ser usadas para a infraestrutura de nuvem. Os detalhes variam de uma organização para outra, mas uma boa política ajuda a garantir que os desenvolvedores possam entender e manter a infraestrutura de nuvem da empresa.

O CCoE também cria uma “zona de pouso” que define suas unidades organizacionais dentro da AWS. Uma zona de pouso é um ambiente da AWS pré-configurado, seguro, escalável e com várias contas baseado em esquemas de práticas recomendadas. Para unir os serviços que compõem sua zona de pouso, você pode usar a AWS Control Tower, que configura e gerencia todo o seu sistema de várias contas a partir de uma única interface de usuário.

As equipes de desenvolvimento devem poder usar suas próprias contas para testar e implantar novos recursos nessas contas, conforme necessário. Desenvolvedores individuais podem tratar esses recursos como extensões de sua própria estação de trabalho de desenvolvimento. Usando o CDK Pipelines, os aplicativos do AWS CDK podem então ser implantados por meio de uma conta de CI/CD em ambientes de teste, integração e produção (cada um isolado em sua própria região ou conta da AWS). Isso é feito mesclando o código dos desenvolvedores no repositório canônico da sua organização.

Práticas recomendadas de codificação

Esta seção apresenta as práticas recomendadas para organizar seu código do AWS CDK. O diagrama a seguir mostra a relação entre uma equipe e os repositórios de código, os pacotes, os aplicativos e as bibliotecas de constructos dessa equipe.

Começar de forma simples e acrescentar complexidade somente quando necessário

O princípio orientador da maioria das nossas práticas recomendadas é manter as coisas o mais simples possível, mas não mais simples. Adicione complexidade somente quando seus requisitos exigirem uma solução mais complicada. Com o AWS CDK, você pode refatorar seu código conforme necessário para dar suporte a novos requisitos. Você não precisa arquitetar todos os cenários possíveis com antecedência.

Alinhar-se com o AWS Well-Architected Framework

O AWS Well-Architected Framework define um componente como o código, a configuração e recursos da AWS que, juntos, atendem a um requisito. Um componente geralmente é a unidade de propriedade técnica e é dissociada de outros componentes. O termo workload é usado para identificar um conjunto de componentes que entrega o valor empresarial. Uma workload é normalmente o nível de detalhes sobre o qual os líderes de negócios e tecnologia se comunicam.

Um aplicativo do AWS CDK mapeia para um componente conforme definido pelo AWS Well-Architected Framework. Os aplicativos do AWS CDK são um mecanismo para codificar e fornecer as práticas recomendadas de aplicativos em nuvem do Well-Architected. Você também pode criar e compartilhar componentes como bibliotecas de código reutilizáveis por meio de repositórios de artefatos, como o AWS CodeArtifact.

Cada aplicativo começa com um único pacote em um único repositório

Um único pacote é o ponto de entrada do seu aplicativo do AWS CDK. Aqui, você define como e onde implantar as diferentes unidades lógicas do seu aplicativo. Você também define o pipeline de CI/CD para implantar o aplicativo. Os constructos do aplicativo definem as unidades lógicas da sua solução.

Use pacotes adicionais para constructos que você usa em mais de um aplicativo. (Os constructos compartilhados também devem ter seu próprio ciclo de vida e estratégia de teste.) As dependências entre pacotes no mesmo repositório são gerenciadas pelas ferramentas de compilação do seu repositório.

Embora seja possível, não recomendamos colocar vários aplicativos no mesmo repositório, especialmente ao usar pipelines de implantação automatizados. Isso aumenta o “raio de alcance” das mudanças durante a implantação. Quando há vários aplicativos em um repositório, as alterações em um aplicativo acionam a implantação dos outros (mesmo que os outros não tenham sido alterados). Além disso, uma interrupção em um aplicativo impede que os outros aplicativos sejam implantados.

Mover o código para repositórios com base no ciclo de vida do código ou na propriedade da equipe

Quando os pacotes começarem a ser usados em vários aplicativos, mova-os para seu próprio repositório. Dessa forma, os pacotes podem ser referenciados pelos sistemas de criação de aplicativos que os usam e também podem ser atualizados em cadências independentes dos ciclos de vida do aplicativo. No entanto, a princípio, pode fazer sentido colocar todos os constructos compartilhados em um repositório.

Além disso, mova os pacotes para seu próprio repositório quando equipes diferentes estiverem trabalhando neles. Isso ajuda na aplicação do controle de acesso.

Para consumir pacotes além dos limites do repositório, é necessário ter um repositório de pacotes privado, semelhante a NPM, PyPI ou Maven Central, mas interno à sua organização. Também é necessário ter um processo de lançamento que compile, teste e publique o pacote no repositório de pacotes privado. O CodeArtifact pode hospedar pacotes para as linguagens de programação mais populares.

As dependências dos pacotes no repositório de pacotes são gerenciadas pelo gerenciador de pacotes da sua linguagem, como NPM para aplicações TypeScript ou JavaScript. Seu gerenciador de pacotes ajuda a garantir que as compilações sejam repetíveis. Isso é feito gravando as versões específicas de cada pacote do qual seu aplicativo depende. Também permite que você atualize essas dependências de forma controlada.

Pacotes compartilhados precisam de uma estratégia de teste diferente. Para um único aplicativo, pode ser suficiente implantá-lo em um ambiente de teste e confirmar se ele ainda funciona. Mas pacotes compartilhados devem ser testados independentemente da aplicação consumidora, como se estivessem sendo lançados para o público. (Sua organização pode optar por lançar alguns pacotes compartilhados para o público.)

Lembre-se de que um constructo pode ser arbitrariamente simples ou complexo. O Bucket é um constructo, mas CameraShopWebsite também pode ser um constructo.

A infraestrutura e o código de runtime residem no mesmo pacote

Além de gerar modelos do AWS CloudFormation para implantação de infraestrutura, o AWS CDK também agrupa ativos do runtime, como funções do Lambda e imagens do Docker, e os implanta junto com sua infraestrutura. Isso possibilita a combinação do código que define sua infraestrutura e do código que implementa sua lógica de runtime em um único constructo. Essa é uma prática recomendada. Esses dois tipos de código não precisam estar em repositórios separados ou mesmo em pacotes separados.

Para desenvolver os dois tipos de código juntos, você pode usar um constructo independente que descreva completamente uma parte da funcionalidade, incluindo sua infraestrutura e lógica. Com um constructo independente, você pode testar os dois tipos de código isoladamente, compartilhar e reutilizar o código entre projetos e criar versões de todo o código em sincronia.

Práticas recomendadas de constructos

Esta seção contém práticas recomendadas para o desenvolvimento de constructos. Os constructos são módulos reutilizáveis e combináveis que encapsulam recursos. Eles são os componentes básicos dos aplicativos do AWS CDK.

Modelar com constructos, implantar com pilhas

As pilhas são a unidade de implantação: tudo em uma pilha é implantado em conjunto. Portanto, ao criar as unidades lógicas de nível superior do seu aplicativo a partir de vários recursos da AWS, represente cada unidade lógica como um Construct, não como uma Stack. Use pilhas somente para descrever como seus constructos devem ser compostos e conectados para seus vários cenários de implantação.

Por exemplo, se uma de suas unidades lógicas for um site, os constructos que a compõem (como um bucket do Amazon S3, API Gateway, funções do Lambda ou tabelas do Amazon RDS) devem ser compostas em um único constructo de alto nível. Em seguida, esse constructo deve ser instanciado em uma ou mais pilhas para implantação.

Ao usar constructos para criação e pilhas para implantação, você melhora o potencial de reutilização de sua infraestrutura e oferece mais flexibilidade na forma como ela é implantada.

Configurar com propriedades e métodos, não com variáveis de ambiente

Pesquisas de variáveis de ambiente dentro de constructos e pilhas são um antipadrão comum. Tanto os constructos quanto as pilhas devem aceitar um objeto de propriedades para permitir a configuração total inteiramente em código. Fazer o contrário introduz uma dependência na máquina na qual o código será executado, o que cria ainda mais informações de configuração que você precisa rastrear e gerenciar.

Em geral, as pesquisas de variáveis de ambiente devem ser limitadas ao nível superior de um aplicativo do AWS CDK. Elas também devem ser usadas para transmitir informações necessárias para execução em um ambiente de desenvolvimento. Para ter mais informações, consulte Ambientes para o AWS CDK.

Teste de unidade em sua infraestrutura

Para executar consistentemente um conjunto completo de testes de unidade no momento da criação em todos os ambientes, evite consultas na rede durante a síntese e modele todos os estágios de produção no código. (Essas práticas recomendadas serão abordadas posteriormente.) Se qualquer confirmação individual sempre resultar no mesmo modelo gerado, você pode confiar nos testes de unidade que você escreve para confirmar se os modelos gerados têm a aparência esperada. Para ter mais informações, consulte Testar as aplicações AWS CDK.

Não alterar o ID lógico dos recursos com estado

Alterar o ID lógico de um recurso resulta na substituição do recurso por um novo na próxima implantação. Para recursos com estado, como bancos de dados e buckets do S3, ou infraestrutura persistente, como uma Amazon VPC, isso raramente é desejado. Tenha cuidado com qualquer refatoração do seu código do AWS CDK que possa fazer com que o ID seja alterado. Escreva testes de unidade que afirmem que os IDs lógicos de seus recursos com estado permanecem estáticos. O ID lógico é derivado do id que você especifica ao instanciar o constructo e da posição dele na árvore de constructos. Para ter mais informações, consulte IDs lógicos.

Os constructos não são suficientes para a conformidade

Muitos clientes corporativos escrevem seus próprios wrappers para constructos L2 (os constructos “selecionados” que representam recursos individuais da AWS com padrões razoáveis integrados e práticas recomendadas). Esses wrappers aplicam as práticas recomendadas de segurança, como criptografia estática e políticas do IAM específicas. Por exemplo, você pode criar um MyCompanyBucket para usar em seus aplicativos no lugar do constructo do Bucket do Amazon S3 usual. Esse padrão é útil para apresentar diretrizes de segurança no início do ciclo de vida do desenvolvimento de software, mas não confie nelas como o único meio de imposição.

Em vez disso, use atributos da AWS como políticas de controle de serviço e limites de permissões para reforçar suas barreiras de proteção no nível da organização. Use Aspectos e o AWS CDK ou ferramentas como o CloudFormation Guard para fazer afirmações sobre as propriedades de segurança dos elementos da infraestrutura antes da implantação. Use o AWS CDK para o que ele faz de melhor.

Por fim, lembre-se de que escrever seus próprios constructos “L2+” pode impedir que seus desenvolvedores tirem proveito de pacotes do AWS CDK como constructos das soluções da AWS ou constructos de terceiros do Construct Hub. Esses pacotes geralmente são criados em constructos do AWS CDK padrão e não poderão usar seus constructos de wrapper.

Práticas recomendadas de aplicativos

Nesta seção, discutiremos como escrever seus aplicativos do AWS CDK, combinando constructos para definir como seus recursos da AWS estão conectados.

Tomar decisões na hora da síntese

Embora o AWS CloudFormation permita que você tome decisões no momento da implantação (usando Conditions, { Fn::If } e Parameters) e o AWS CDK ofereça algum acesso a esses mecanismos, não recomendamos usá-los. Os tipos de valores que você pode usar e os tipos de operações que você pode realizar neles são limitados em comparação com o que está disponível em uma linguagem de programação de uso geral.

Em vez disso, tente tomar todas as decisões, como qual constructo instanciar, em seu aplicativo do AWS CDK usando as instruções if da sua linguagem de programação e outros atributos. Por exemplo, um linguagem comum do CDK, iterando em uma lista e instanciando um constructo com valores de cada item na lista, simplesmente não é possível usando expressões do AWS CloudFormation.

Trate o AWS CloudFormation como um detalhe de implementação que o AWS CDK usa para implantações robustas em nuvem, não como um destino de linguagem. Você não está escrevendo modelos do AWS CloudFormation em TypeScript ou Python, você está escrevendo um código do CDK que, por acaso, usa o CloudFormation para implantação.

Usar nomes de recursos gerados, não nomes físicos

Os nomes são um recurso precioso. Cada nome só pode ser usado uma vez. Portanto, se você codificar um nome de tabela ou um nome de bucket em sua infraestrutura e em seu aplicativo, não poderá implantar essa parte da infraestrutura duas vezes na mesma conta. (O nome do qual estamos falando aqui é o nome especificado, por exemplo, pela propriedade bucketName em um constructo de bucket do Amazon S3.)

Pior ainda, você não poderá fazer alterações no recurso que exijam sua substituição. Se uma propriedade só puder ser definida na criação do recurso, como o KeySchema de uma tabela do Amazon DynamoDB, essa propriedade será imutável. A alteração dessa propriedade requer um novo recurso. No entanto, o novo recurso deve ter o mesmo nome para ser um verdadeiro substituto. Mas ele não pode ter o mesmo nome enquanto o recurso existente ainda estiver usando esse nome.

Uma abordagem melhor é especificar o mínimo possível de nomes. Se você omitir os nomes dos recursos, o AWS CDK os gerará para você de uma forma que não cause problemas. Suponha que você tenha uma tabela como recurso. Em seguida, você pode passar o nome da tabela gerada como uma variável de ambiente para sua função do AWS Lambda. Em seu aplicativo do AWS CDK, você pode referenciar o nome da tabela como table.tableName. Como alternativa, você pode gerar um arquivo de configuração na sua instância do Amazon EC2 na inicialização ou gravar o nome real da tabela na AWS Systems Manager Parameter Store para que seu aplicativo possa lê-lo a partir daí.

Se o lugar de que você precisa for outra pilha do AWS CDK, é ainda mais simples. Supondo que uma pilha defina o recurso e outra pilha precise usá-lo, o seguinte se aplica:

Definir políticas de remoção e retenção de logs

O AWS CDK tenta evitar que você perca dados adotando políticas que retêm tudo o que você cria. Por exemplo, a política de remoção padrão em recursos que contêm dados (como buckets do Amazon S3 e tabelas de banco de dados) é não excluir o recurso quando ele é removido da pilha. Em vez disso, o recurso fica órfão da pilha. Da mesma forma, o padrão do CDK é reter todos os logs para sempre. Em ambientes de produção, esses padrões podem resultar rapidamente no armazenamento de grandes quantidades de dados que você realmente não precisa e na fatura da AWS correspondente.

Considere cuidadosamente o que você deseja que essas políticas sejam para cada recurso de produção e especifique-as adequadamente. Use Aspectos e o AWS CDK para validar as políticas de remoção e registro em log em sua pilha.

Separe seu aplicativo em várias pilhas, conforme determinado pelos requisitos de implantação

Não há uma regra rígida e rápida de quantas pilhas seu aplicativo precisa. Normalmente, você acabará baseando a decisão em seus padrões de implantação. Lembre-se das seguintes orientações:

Confirmar cdk.context.json para evitar comportamentos não determinísticos

O determinismo é fundamental para implantações do AWS CDK bem-sucedidas. Um aplicativo do AWS CDK deve ter essencialmente o mesmo resultado sempre que for implantado em um determinado ambiente.

Como seu aplicativo do AWS CDK é escrito em uma linguagem de programação de uso geral, ele pode executar código arbitrário, usar bibliotecas arbitrárias e fazer chamadas de rede arbitrárias. Por exemplo, você pode usar um SDK da AWS para recuperar algumas informações da sua conta da AWS enquanto sintetiza seu aplicativo. Reconheça que isso resultará em requisitos adicionais de configuração de credenciais, maior latência e uma chance, ainda que pequena, de falha toda vez que você executar cdk synth.

Nunca modifique sua conta ou seus recursos da AWS durante a síntese. Sintetizar um aplicativo não deve ter efeitos colaterais. As alterações em sua infraestrutura devem ocorrer somente na fase de implantação, após a geração do modelo do AWS CloudFormation. Dessa forma, se houver algum problema, o AWS CloudFormation pode reverter automaticamente a alteração. Para fazer alterações que não podem ser feitas facilmente na estrutura do AWS CDK, use recursos personalizados para executar código arbitrário no momento da implantação.

Mesmo chamadas que são estritamente somente para leitura não são necessariamente seguras. Considere o que acontece se o valor retornado por uma chamada de rede for alterado. Que parte da sua infraestrutura isso afetará? O que acontecerá com os recursos já implantados? A seguir estão dois exemplos de situações em que uma mudança repentina nos valores pode causar um problema.

Essas situações podem ser prejudiciais porque a mudança do lado da AWS pode ocorrer após meses ou anos de implantações bem-sucedidas. De repente, suas implantações estão falhando “sem motivo” e você esqueceu há muito tempo o que fez e por quê.

Felizmente, o AWS CDK inclui um mecanismo chamado provedores de contexto para registrar um snapshot de valores não determinísticos. Isso permite que futuras operações de síntese produzam exatamente o mesmo modelo que produziam quando foram implantadas pela primeira vez. As únicas alterações no novo modelo são as alterações que você fez no seu código. Quando você usa o método .fromLookup() de um constructo, o resultado da chamada é armazenado em cache em cdk.context.json. Você deve submeter isso ao controle de versão junto com o resto do seu código para garantir que futuras execuções do seu aplicativo do CDK usem o mesmo valor. O CDK Toolkit inclui comandos para gerenciar o cache de contexto, para que você possa atualizar entradas específicas quando precisar. Para ter mais informações, consulte Valores de contexto e o AWS CDK.

Se você precisar de algum valor (da AWS ou de outro lugar) para o qual não haja um provedor de contexto do CDK nativo, recomendamos escrever um script separado. O script deve recuperar o valor e gravá-lo em um arquivo e, em seguida, ler esse arquivo no seu aplicativo do CDK. Execute o script somente quando quiser atualizar o valor armazenado, não como parte do seu processo de criação normal.

Deixar que o AWS CDK gerencie perfis e grupos de segurança

Com os métodos convenientes grant() da Biblioteca de Constructos do AWS CDK, você pode criar perfis do AWS Identity and Access Management que concedem acesso a um recurso por outro usando permissões com escopo mínimo. Por exemplo, considere uma linha como a seguinte:

amzn-s3-demo-bucket.grantRead(myLambda)

Essa única linha adiciona uma política à função do Lambda (que também é criada para você). Essa função e suas políticas são mais de uma dúzia de linhas do CloudFormation que você não precisa escrever. O AWS CDK concede somente as permissões mínimas necessárias para que a função seja lida do bucket.

Se você exigir que os desenvolvedores sempre usem funções predefinidas criadas por uma equipe de segurança, a codificação do AWS CDK se torna muito mais complicada. Suas equipes podem perder muita flexibilidade na forma como projetam seus aplicativos. Uma alternativa melhor é usar políticas de controle de serviços e limites de permissões para garantir que os desenvolvedores permaneçam dentro das barreiras de proteção.

Modelar todas as etapas de produção em código

Em cenários do AWS CloudFormation tradicionais, sua meta é produzir um único artefato parametrizado para que possa ser implantado em vários ambientes de destino após a aplicação de valores de configuração específicos a esses ambientes. No CDK, você pode e deve criar essa configuração em seu código-fonte. Crie uma pilha para seu ambiente de produção e crie uma pilha separada para cada um dos outros estágios. Em seguida, coloque os valores de configuração de cada pilha no código. Use serviços como Secrets Manager e Systems Manager Parameter Store para valores confidenciais que você não deseja verificar no controle de origem, usando os nomes ou ARNs desses recursos.

Quando você sintetiza seu aplicativo, o conjunto de nuvem criado na pasta cdk.out contém um modelo separado para cada ambiente. Toda a sua criação é determinística. Não há alterações fora de banda em seu aplicativo, e qualquer confirmação sempre gera exatamente o mesmo modelo do AWS CloudFormation e os ativos que o acompanham. Isso torna o teste de unidade muito mais confiável.

Medir tudo

Atingir a meta de implantação contínua completa, sem intervenção humana, requer um alto nível de automação. Essa automação só é possível com um monitoramento extensivo. Para medir todos os aspectos de seus recursos implantados, crie métricas, alarmes e painéis. Não pare de medir coisas como uso da CPU e espaço em disco. Além disso, registre suas métricas de negócios e use essas medidas para automatizar decisões de implantação, como reversões. A maioria dos constructos L2 no AWS CDK tem métodos convenientes para ajudar você a criar métricas, como o método metricUserErrors() na classe dynamodb.Table.