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.

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á.

AWS Controle de versão do CDK

Este tópico fornece informações de referência sobre como o AWS Cloud Development Kit (AWS CDK) lida com o controle de versão.

Os números das versões consistem em três partes numéricas da versão: principal.secundária.patch, e segue amplamente os princípios de versionamento semântico com algumas ressalvas descritas nos Esclarecimentos sobre o versionamento semântico da Biblioteca de Constructos da AWS. Isso significa que as mudanças significativas que APIs consideramos estáveis estão limitadas aos principais lançamentos.

As versões minor e patch são compatíveis com versões anteriores. O código escrito em uma versão anterior com a mesma versão major pode ser atualizado para uma versão mais recente dentro da mesma versão major. Ele continuará a ser construído e executado, produzindo um resultado funcionalmente equivalente. Para alguns casos de uso avançados, pequenas alterações em seu código serão necessárias, conforme observado no próximo tópico.

AWS Compatibilidade com o CDK Toolkit

Cada versão da AWS Construct Library (aws-cdk-lib) principal é compatível com a versão CLI () e a Toolkit Library (aws-cdk-cli) do AWS CDK Toolkit Library (@aws-cdk/toolkit-lib) que estava em vigor na época do lançamento da AWS Construct Library. Também é compatível com qualquer versão mais recente do AWS CDK Toolkit. Cada versão da AWS Construct Library mantém essa compatibilidade até a data de fim da vida útil da biblioteca. Portanto, desde que você esteja usando uma versão compatível do AWS Construct Library, é sempre seguro atualizar sua versão do AWS CDK Toolkit.

Cada versão da AWS Construct Library também pode funcionar com versões do AWS CDK Toolkit anteriores à versão atual na época do lançamento da AWS Construct Library. No entanto, isso não é garantido. A compatibilidade depende da versão do esquema de montagem em nuvem da AWS Construct Library. O AWS CDK gera uma montagem em nuvem durante a síntese e o AWS CDK Toolkit a consome para implantação. O esquema que define o formato do conjunto de nuvem é estritamente especificado e versionado. Portanto, uma versão mais antiga do AWS CDK Toolkit precisaria oferecer suporte à versão do esquema de montagem em nuvem da AWS Construct Library para que elas fossem compatíveis.

Quando a versão de montagem em nuvem exigida pela AWS Construct Library não é compatível com a versão suportada pelo AWS CDK Toolkit, você recebe uma mensagem de erro como a seguinte:

Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0.
    Please upgrade your CLI in order to interact with this app.

Para resolver esse erro, atualize o AWS CDK Toolkit para uma versão compatível com a versão de montagem em nuvem necessária ou para a versão mais recente disponível. A alternativa (fazer o downgrade dos módulos da AWS Construct Library que seu aplicativo usa) geralmente não é recomendada.

AWS Controle de versão da Construct Library

Os módulos na AWS Construct Library passam por vários estágios à medida que são desenvolvidos, do conceito à API madura. Estágios diferentes oferecem vários graus de estabilidade da API nas versões subsequentes do AWS CDK.

Exceto nos cenários em que as advertências documentadas no próximo tópico se aplicam, APIs na AWS Construct Library (aws-cdk-lib) principal são estáveis e a biblioteca segue amplamente os princípios de versionamento semântico. A biblioteca inclui construções AWS CloudFormation (L1) para todos os AWS serviços, que são geradas automaticamente a partir de esquemas de provedores de CloudFormation recursos e, às vezes, podem incluir atualizações incompatíveis com versões anteriores. Ele também inclui construções de nível superior (L2 e L3) e as classes principais do CDK, como App eStack, que são todas estáveis. APIs não serão removidos desse pacote (embora possam estar obsoletos) até a próxima versão principal do CDK. Quando uma alteração significativa for necessária em uma API estável, uma API totalmente nova será adicionada.

Os novos APIs em desenvolvimento para um serviço já incorporado aws-cdk-lib são identificados usando um Beta<N> sufixo, que N começa em 1 e é incrementado a cada alteração significativa na nova API. Beta<N> APIs nunca são removidos, apenas obsoletos, portanto, seu aplicativo existente continua funcionando com versões mais recentes do. aws-cdk-lib Quando a API é considerada estável, uma nova API sem o sufixo Beta<N> é adicionada.

Quando os níveis superiores (L2 ou L3) APIs começam a ser desenvolvidos para um AWS serviço que antes tinha apenas L1 APIs, eles APIs são inicialmente distribuídos em um pacote separado. O nome desse pacote tem um sufixo “Alpha” e sua versão corresponde à primeira versão de aws-cdk-lib com a qual é compatível, com uma subversão alpha. Quando o módulo oferece suporte aos casos de uso pretendidos, APIs eles são adicionadosaws-cdk-lib.

AWS Esclarecimentos sobre o versionamento semântico da Construct Library

Embora a AWS Construct Library siga amplamente os princípios de versionamento semântico, há algumas ressalvas importantes específicas para nossa implementação. Em geral, a AWS Construct Library mantém a estabilidade para os consumidores de API, mas às vezes adiciona encargos adicionais aos autores da construção para permitir a evolução necessária da estrutura.

Estabilidade de vinculação de linguagem

Com o tempo, poderemos adicionar suporte ao AWS CDK para linguagens de programação adicionais. Embora a API descrita em todas as linguagens seja a mesma, a forma como a API é expressa varia de acordo com a linguagem e pode mudar à medida que o suporte à linguagem evolui. Por esse motivo, as vinculações de linguagem são consideradas experimentais por um tempo até serem consideradas prontas para uso em produção.