Versionamento do AWS CDK - Kit de desenvolvimento em nuvem da AWS (CDK da AWS) v2
Compatibilidade do Kit de Ferramentas CDK da AWSVersionamento da Biblioteca de Constructos da AWSEsclarecimentos sobre o versionamento semântico da Biblioteca de Constructos da AWSEstabilidade de vinculação de linguagem

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.

Versionamento do AWS CDK

Este tópico fornece informações de referência sobre como o kit de desenvolvimento em nuvem da AWS (CDK da AWS) lida com o versionamento.

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 alterações significativas nas APIs que consideramos estáveis estão limitadas às versões principais.

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.

Compatibilidade do Kit de Ferramentas CDK da AWS

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

Cada versão da Biblioteca de Constructos da AWS também pode funcionar com versões do Kit de Ferramentas CDK da AWS anteriores à versão atual na época do lançamento da Biblioteca de Constructos da AWS. No entanto, isso não é garantido. A compatibilidade depende da versão do esquema de conjunto de nuvem da Biblioteca de Constructos da AWS. O AWS CDK gera um conjunto de nuvem durante a síntese e o Kit de Ferramentas CDK da AWS o 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 Kit de Ferramentas CDK da AWS precisaria oferecer suporte à versão do esquema de conjunto de nuvem da Biblioteca de Constructos da AWS para que elas fossem compatíveis.

Quando a versão de conjunto de nuvem exigida pela Biblioteca de Constructos da AWS não é compatível com a versão com suporte no Kit de Ferramentas CDK da AWS, 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 Kit de Ferramentas CDK da AWS para uma versão compatível com a versão de conjunto de nuvem necessária ou para a versão mais recente disponível. A alternativa (rebaixar os módulos da Biblioteca de Constructos da AWS que sua aplicação usa) geralmente não é recomendada.

nota

Para obter mais informações sobre as combinações exatas de versões que funcionam juntas, consulte a tabela de compatibilidade no repositório aws-cdk-cli do GitHub.

Versionamento da Biblioteca de Constructos da AWS

Os módulos na Biblioteca de Constructos da AWS 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, as APIs na Biblioteca de Constructos da AWS (aws-cdk-lib) principal são estáveis e a biblioteca segue amplamente os princípios de versionamento semântico. A biblioteca inclui constructos do AWS CloudFormation (L1) para todos os serviços da AWS, que são geradas automaticamente a partir de esquemas do provedor de recursos do CloudFormation e, às vezes, podem incluir atualizações incompatíveis com versões anteriores. Ela também inclui constructos de nível superior (L2 e L3) e as classes principais do CDK, como App e Stack, que são todas estáveis. As APIs não serão removidas desse pacote (embora possam estar obsoletas) 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.

Novas APIs em desenvolvimento para um serviço já incorporado em aws-cdk-lib são identificadas usando um sufixo Beta<N>, que N começa em 1 e é incrementado a cada alteração significativa na nova API. Beta<N> As APIs nunca são removidas, apenas obsoletas. Portanto, sua aplicação existente continua funcionando com versões mais recentes de aws-cdk-lib. Quando a API é considerada estável, uma nova API sem o sufixo Beta<N> é adicionada.

Quando APIs de nível superior (L2 ou L3) começam a ser desenvolvidas para um serviço AWS que antes tinha apenas APIs L1, essas APIs são inicialmente distribuídas 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, suas APIs são adicionadas a aws-cdk-lib.

Esclarecimentos sobre o versionamento semântico da Biblioteca de Constructos da AWS

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

  • Mudanças que afetam a segurança

    Para atender à nossa barreira de segurança, talvez precisemos alterar as APIs de formas incompatíveis com versões anteriores ou removê-las completamente. Isso evita que as APIs afetadas sejam usadas e força a atualização das implementações.

  • As características são descritas por intenção

    Nosso objetivo é minimizar mudanças inesperadas, mas favoreceremos a intenção mais que a estabilidade da implementação. A Biblioteca de Constructos da AWS não garante que os constructos sempre sejam sintetizados exatamente no mesmo modelo do CloudFormation ou usem exatamente o mesmo conjunto de recursos. Isso se aplica especialmente a constructos de nível superior, nas quais o mesmo objetivo geralmente pode ser alcançado de maneiras diferentes.

  • Implementação de interfaces e classes abstratas

    As interfaces e classes abstratas na Biblioteca de Constructos da AWS são estáveis para consumidores, mas não para implementadores. Isso significa que é possível confiar com segurança em interfaces como a s3.IBucket para fornecer pelo menos a mesma funcionalidade da época (versão da Biblioteca de Constructos da AWS) em que você começou a consumir a interface ou a classe abstrata. No entanto, periodicamente, novos membros (abstratos) serão adicionados às interfaces e classes abstratas. Para qualquer pessoa que as implemente, isso cria uma carga adicional de implementação a ser considerada ao atualizar, já que a implementação ainda não implementaria os novos membros. Tratar rigorosamente as adições às interfaces e classes abstratas para implementadores como mudanças significativas limitaria indevidamente a capacidade de evolução da Biblioteca de Constructos da AWS. Na maioria dos casos, os implementadores devem preferir estender classes concretas, como s3.Bucket.

  • Constructos L1, código gerado e outras APIs marcadas como externas

    Partes da Biblioteca de Constructos da AWS são geradas a partir de fontes de dados provenientes diretamente dos serviços da AWS. Para manter essas APIs alinhadas com a realidade, o código gerado pode conter alterações incompatíveis com versões anteriores. Na maioria das vezes, as fontes de dados são atualizadas para refletir corretamente a realidade e corrigir a representação incorreta. O IntelliSense do seu IDE exibirá APIs externas com a anotação @stability — external.

  • Associações específicas da linguagem

    As associações de linguagem podem conter alterações incompatíveis com versões anteriores em um número muito limitado de situações. Elas são causadas por alterações de tipo upstream que são compatíveis com versões anteriores em outras linguagens com suporte. Essas mudanças de tipo são permitidas, pois fazer o contrário limitaria severamente a capacidade de evolução da biblioteca.

    A lista a seguir descreve todas as instâncias conhecidas:

    • Golang - Mudando de uma fatia digitada para qualquer fatia: uma lista de um único tipo está mudando para uma lista de vários tipos (tipos de união em TypeScript). Em Go, eles são digitados como uma fatia de qualquer (*[]any). Devido às regras de atribuição de digitação do Go, mudar de *[]string para não é uma conversão automática. Portanto, esse tipo de ampliação exige que o código do consumidor seja alterado. Consulte Trabalho com qualquer fatia para ver as estratégias.

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.

Linguagem Estabilidade

TypeScript

Stable

JavaScript

Stable

Python

Stable

Java

Stable

C#/.NET

Stable

Go

Stable