Solução de AWS CDK problemas comuns - AWS Cloud Development Kit (AWS CDK) v2

Este é o Guia do Desenvolvedor 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.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Solução de AWS CDK problemas comuns

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

Depois de atualizar o AWS CDK, o AWS CDK Toolkit (CLI) relata uma incompatibilidade com a Construct Library AWS

A versão do AWS CDK kit de ferramentas (que fornece o cdk comando) deve ser pelo menos igual à versão do módulo principal da AWS Construct Library,aws-cdk-lib. O Toolkit foi projetado para ser compatível com versões anteriores. A versão 2.x mais recente do Toolkit 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 AWS CDK Toolkit, 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 CDK Toolkit.

Se você estiver usando outro idioma, use npm para instalar o AWS CDK Toolkit, omitindo o -g sinalizador e especificando a versão desejada. Por exemplo:

npm install aws-cdk@2.0

Para executar um AWS CDK kit de ferramentas instalado localmente, use o comando npx aws-cdk em vez de somentecdk. Por exemplo:

npx aws-cdk deploy MyStack

npx aws-cdkexecuta a versão local do AWS CDK Toolkit, 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.

macOS/Linux
alias cdk="npx aws-cdk"
Windows
doskey cdk=npx aws-cdk $*

(voltar à lista)

Ao implantar minha AWS CDK pilha, recebo um erro NoSuchBucket

Seu AWS ambiente não foi inicializado e, portanto, não tem um bucket Amazon S3 para armazenar recursos durante a implantação. Você pode 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 AWS cobranças inesperadas, o AWS CDK não inicializa automaticamente nenhum ambiente. Você deve inicializar explicitamente cada ambiente no qual será implantado.

Por padrão, os recursos de bootstrap são criados na região ou regiões que são usadas por pilhas na aplicação AWS CDK atual. Como alternativa, eles são criados na região especificada em seu AWS perfil local (definida poraws configure), usando a conta desse perfil. Você pode especificar uma conta e uma região diferentes na linha de comando da seguinte maneira. (Você deve 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 AWS CDK bootstrapping.

(voltar à lista)

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

Você está implantando uma pilha que requer recursos de bootstrap, 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 contêm ativos ou que sintetizam um modelo AWS CloudFormation maior que 50K.) Use uma conta ou função que tenha permissão para realizar a ação s3:* no bucket mencionado na mensagem de erro.

(voltar à lista)

Ao sintetizar uma AWS CDK pilha, 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 AWS CDK projeto quando você emitecdk synth. O arquivo cdk.json nesse diretório, criado pelo cdk init comando, contém a linha de comando necessária para executar (e, assim, sintetizar) seu AWS CDK aplicativo. Para um TypeScript aplicativo, por exemplo, o padrão cdk.json é mais ou menos assim: 

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

Recomendamos emitir cdk comandos somente no diretório principal do seu projeto, para que o AWS CDK kit de ferramentas possa cdk.json encontrá-lo e executar seu aplicativo com sucesso.

Se isso não for prático por algum motivo, o AWS CDK Toolkit procura a linha de comando do aplicativo em dois outros locais:

  • Em cdk.json no diretório inicial

  • No próprio comando cdk synth usando a opção -a

Por exemplo, você pode sintetizar uma pilha de um TypeScript aplicativo da seguinte maneira.

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

(voltar à lista)

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

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

nota

O limite AWS CloudFormation de recursos é 500 no momento em que este artigo foi escrito. Veja as cotas AWS CloudFormation para o limite atual de recursos.

As AWS construções de alto nível baseadas em intenção da Construct Library 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 construções baseadas em intenção resulta em 1 a 5 AWS CloudFormation recursos por construção, embora isso possa variar. Para aplicativos sem servidor, é normal ter de 5 a 8 AWS recursos por endpoint de API.

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

Exceder o limite AWS CloudFormation de recursos é um erro durante a AWS CloudFormation síntese. Ele AWS CDK emite um aviso se sua pilha exceder 80% do limite. Você pode usar um limite diferente definindo a propriedade maxResources em sua pilha ou desabilitar a validação definindo como maxResources como 0.

dica

Você pode obter uma contagem exata dos recursos em sua saída sintetizada usando o script utilitário a seguir. (Como todo AWS CDK desenvolvedor precisa do Node.js, o script é escrito em JavaScript.)

// 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ê.

nota

AWS CloudFormation especialistas geralmente sugerem o uso de pilhas aninhadas como uma solução para o limite de recursos. O AWS CDK apóia essa abordagem por meio da NestedStackconstrução.

(voltar à lista)

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 ambos, o, por padrão AWS CDK, sintetiza a pilha como independente do ambiente. Em seguida, você pode implantar a pilha em uma região específica usando 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.

nota

No passado, ocasionalmente, as regiões eram lançadas com apenas uma zona de disponibilidade. AWS CDK Pilhas independentes do ambiente não podem ser implantadas nessas regiões. No momento em que este artigo foi escrito, no entanto, todas as AWS regiões tinham pelo menos duas AZs.

Você pode alterar esse comportamento substituindo a propriedade availablilityZones (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 AWS CDK.

(voltar à lista)

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.

TypeScript
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
  
export class CdkTestStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
  
    const bucket = new s3.Bucket(this, 'Bucket', {
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });
  }
}
JavaScript
const cdk = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
  
class CdkTestStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);
  
    const bucket = new s3.Bucket(this, 'Bucket', {
      removalPolicy: cdk.RemovalPolicy.DESTROY
    });
  }
}

module.exports = { CdkTestStack }
Python
import aws_cdk as cdk
from constructs import Construct
import aws_cdk.aws_s3 as s3

class CdkTestStack(cdk.stack):
    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)
        
        bucket = s3.Bucket(self, "Bucket",
            removal_policy=cdk.RemovalPolicy.DESTROY)
Java
software.amazon.awscdk.*;
import software.amazon.awscdk.services.s3.*;
import software.constructs;

public class CdkTestStack extends Stack {
    public CdkTestStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public CdkTestStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        Bucket.Builder.create(this, "Bucket")
                .removalPolicy(RemovalPolicy.DESTROY).build();
    }
}
C#
using Amazon.CDK;
using Amazon.CDK.AWS.S3;

public CdkTestStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
{
    new Bucket(this, "Bucket", new BucketProps {
        RemovalPolicy = RemovalPolicy.DESTROY
    });
}
nota

AWS CloudFormation não é possível excluir um bucket do Amazon S3 que não esteja vazio. Se você definir a política de remoção de um bucket do Amazon S3 como DESTROY, e ele contiver dados, a tentativa de destruir a pilha falhará porque o bucket não pode ser excluído. Você pode fazer com que AWS CDK exclua os objetos no bucket antes de tentar destruí-lo definindo o prop autoDeleteObjects do bucket como true.

(voltar à lista)