Solução de problemas comuns do AWS CDK

Este tópico descreve como solucionar os problemas a seguir com AWS CDK.

Depois de atualizar o AWS CDK, o Kit de Ferramentas CDK da AWS (CLI) relata uma incompatibilidade com a Biblioteca de Constructos da AWS

A versão do Kit de Ferramentas CDK da AWS (que fornece o comando cdk) deve ser pelo menos igual à versão do módulo principal da Biblioteca de Constructos da AWS, aws-cdk-lib. O Kit de Ferramentas foi projetado para ser compatível com versões anteriores. A versão 2.x mais recente do Kit de Ferramentas pode ser usada com qualquer versão 1.x ou 2.x da biblioteca. Por esse motivo, recomendamos que você instale esse componente globalmente e o mantenha atualizado.

npm update -g aws-cdk

Se você precisar trabalhar com várias versões do Kit de Ferramentas CDK da AWS, instale uma versão específica do kit de ferramentas localmente na pasta do seu projeto.

Se você estiver usando TypeScript ou JavaScript, o diretório do seu projeto já contém uma cópia local versionada do Kit de Ferramentas CDK.

Se você estiver usando outra linguagem, use npm para instalar o Kit de Ferramentas CDK da AWS, omitindo o sinalizador -g e especificando a versão desejada. Por exemplo:

npm install aws-cdk@2.0

Para executar um Kit de Ferramentas CDK da AWS instalado localmente, use o comando npx aws-cdk em vez de somente cdk. Por exemplo:

npx aws-cdk deploy MyStack

npx aws-cdk executa a versão local do Kit de Ferramentas CDK da AWS, se houver. Ele retorna à versão global quando um projeto não tem uma instalação local. Talvez seja conveniente configurar um alias de shell para garantir que cdk seja sempre invocado dessa forma.

Ao implantar minha pilha do AWS CDK, recebo um erro NoSuchBucket

Seu ambiente da AWS não sofreu bootstrapping e, portanto, não apresenta um bucket Amazon S3 para armazenar recursos durante a implantação. É possível criar o bucket de teste e outros recursos necessários com o seguinte comando:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

Para evitar a geração de cobranças da AWS inesperadas, o AWS CDK não faz o bootstrapping automaticamente em nenhum ambiente. É necessário inicializar explicitamente cada ambiente no qual será implantado.

Por padrão, os recursos de bootstrapping são criados na região ou regiões que são usadas por pilhas na aplicação do AWS CDK atual. Como alternativa, eles são criados na região especificada em seu perfil local da AWS (definida por aws configure), usando a conta desse perfil. É possível especificar uma conta e uma região diferentes na linha de comando da seguinte maneira. (Será necessário especificar a conta e a região se não estiver no diretório de uma aplicação.)

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

Para obter mais informações, consulte Ações de bootstrapping do AWS CDK.

Ao implantar minha pilha do AWS CDK, recebo uma mensagem forbidden: null

Você está implantando uma pilha que requer recursos de bootstrapping, mas está usando um perfil do IAM ou conta do IAM que não tem permissão para gravar nesses recursos. (O bucket de teste é usado ao implantar pilhas que contenham ativos ou que sintetizem um modelo do AWS CloudFormation maior que 50K.) Use uma conta ou perfil que tenha permissão para realizar a ação s3:* no bucket mencionado na mensagem de erro.

Ao sintetizar uma pilha do AWS CDK, recebo a mensagem --app is required either in command-line, in cdk.json or in ~/.cdk.json

Essa mensagem geralmente significa que você não está no diretório principal do seu projeto do AWS CDK quando você emite cdk synth. O arquivo cdk.json nesse diretório, criado pelo comando cdk init, contém a linha de comando necessária para executar (e, assim, sintetizar) sua aplicação do AWS CDK. Para uma aplicação TypeScript, por exemplo, o padrão cdk.json é mais ou menos assim:

{
  "app": "npx ts-node bin/my-cdk-app.ts"
}

Recomendamos emitir comandos do cdk somente no diretório principal do seu projeto, para que o Kit de Ferramentas CDK da AWS possa encontrar o cdk.json lá e executar sua aplicação com sucesso.

Se isso não for prático por algum motivo, o Kit de Ferramentas CDK da AWS procurará a linha de comando da aplicação em dois outros locais:

Por exemplo, você pode sintetizar uma pilha de uma aplicação TypeScript da seguinte maneira.

cdk synth --app "npx ts-node my-cdk-app.ts" MyStack

Ao sintetizar uma pilha do AWS CDK, recebo um erro porque o modelo do AWS CloudFormation contém muitos recursos

O AWS CDK gera e implanta modelos do AWS CloudFormation. AWS O CloudFormation tem um limite rígido para o número de recursos que uma pilha pode conter. Com o AWS CDK, esse limite pode ser atingido mais rapidamente do que imagina.

Os constructos de alto nível baseados em intenção da Biblioteca de Constructos da AWS provisionam automaticamente quaisquer recursos auxiliares necessários para registro, gerenciamento de chaves, autorização e outros fins. Por exemplo, conceder acesso a um recurso a outro gera todos os objetos do IAM necessários para que os serviços relevantes se comuniquem.

Em nossa experiência, o uso real de constructos baseados em intenção resulta em 1 a 5 recursos do AWS CloudFormation por constructo, embora isso possa variar. Para aplicações sem servidor, é normal ter de 5 a 8 recursos AWS por endpoint de API.

Os padrões, que representam um nível mais alto de abstração, permitem definir ainda mais recursos AWS com ainda menos código. O código do AWS CDK em Examplo: criação de um serviço do AWS Fargate usando o AWS CDK, por exemplo, gera mais de 50 recursos do AWS CloudFormation enquanto define apenas três constructos!

Exceder o limite de recursos do AWS CloudFormation é um erro durante a síntese do AWS CloudFormation. O AWS CDK emiterá um aviso se sua pilha exceder a 80% do limite. É possível usar um limite diferente definindo a propriedade maxResources em sua pilha ou desabilitar a validação definindo maxResources como 0.

// rescount.js - count the resources defined in a stack
// invoke with: node rescount.js <path-to-stack-json>
// e.g. node rescount.js cdk.out/MyStack.template.json

import * as fs from 'fs';
const path = process.argv[2];

if (path) fs.readFile(path, 'utf8', function(err, contents) {
  console.log(err ? `${err}` :
  `${Object.keys(JSON.parse(contents).Resources).length} resources defined in ${path}`);
}); else console.log("Please specify the path to the stack's output .json file");

À medida que a contagem de recursos da sua pilha se aproxima do limite, considere a rearquitetura para reduzir o número de recursos que sua pilha contém: por exemplo, combinando algumas funções do Lambda ou dividindo sua pilha em várias pilhas. O CDK oferece suporte a referências entre pilhas, para que você possa separar a funcionalidade da sua aplicação em pilhas diferentes da maneira que fizer mais sentido para você.

Eu especifiquei três (ou mais) zonas de disponibilidade para meu grupo do Auto Scaling ou VPC, mas a implantação só foi feita em duas

Para obter o número de zonas de disponibilidade que você solicita, especifique a conta e a região na propriedade env da pilha. Se você não especificar ambas, o AWS CDK, por padrão, sintetizará a pilha como independente do ambiente. Em seguida, será possível implantar a pilha em uma região específica usando o AWS CloudFormation. Como algumas regiões têm apenas duas zonas de disponibilidade, um modelo independente do ambiente não usa mais do que duas.

É possível alterar esse comportamento ignorando a propriedade availabilityZones (Python: availability_zones) da sua pilha para especificar explicitamente as zonas que deseja usar.

Para obter mais informações sobre como especificar a conta e a região de uma pilha no momento da síntese, mantendo a flexibilidade de implantação em qualquer região, consulte Ambientes para o CDK da AWS.

Meu bucket do S3, tabela do DynamoDB ou outro recurso não é excluído quando eu emito cdk destroy

Por padrão, os recursos que podem conter dados do usuário têm uma propriedade removalPolicy (Python: removal_policy) deRETAIN, e o recurso não é excluído quando a pilha é destruída. Em vez disso, o recurso fica órfão da pilha. Em seguida, você deve excluir o recurso manualmente depois que a pilha for destruída. Até que você faça isso, a reimplantação da pilha falhará. Isso ocorre porque o nome do novo recurso que está sendo criado durante a implantação está em conflito com o nome do recurso órfão.

Se você definir a política de remoção de um recurso como DESTROY, esse recurso será excluído quando a pilha for destruída.