Migração do CDK da AWS v1 para o CDK da AWS v2 - AWS Kit de desenvolvimento em nuvem (AWS CDK) v2
Novos pré-requisitosAtualização a partir do AWS CDK v2 Developer PreviewMigração do CDK da AWS v1 para o CDK v2Testanda sua aplicação migrado antes da implantaçãoSolução de problemasDescoberta de pilhas v1

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

Migração do CDK da AWS v1 para o CDK da AWS v2

A versão 2 do kit de desenvolvimento em nuvem da AWS (CDK da AWS) foi projetada para facilitar a criação de infraestrutura como código na sua linguagem de programação preferencial. Este tópico descreve as alterações entre a v1 e v2 do CDK da AWS.

dica

Para identificar pilhas implantadas com o AWS CDK v1, use o utilitário awscdk-v1-stack-finder.

As principais mudanças do CDK da AWS v1 para o CDK v2 são as seguintes.

  • O AWS CDK v2 consolida as partes estáveis da Biblioteca de Constructos da AWS, incluindo a biblioteca principal, em um único pacote, aws-cdk-lib. Os desenvolvedores não precisam mais instalar pacotes adicionais para os serviços AWS individuais que usam. Essa abordagem de pacote único também significa que você não precisa sincronizar as versões dos vários pacotes da biblioteca do CDK.

    Os constructos L1 (CfnXXXX), que representam os recursos exatos disponíveis em AWS, são sempre considerados estáveis e, portanto, estão incluídos no aws-cdk-lib CloudFormation.

  • Módulos experimentais, nos quais ainda estamos trabalhando com a comunidade para desenvolver novos constructos L2 ou L3, não estão incluídos em aws-cdk-lib. Em vez disso, eles são distribuídos como pacotes individuais. Os pacotes experimentais são nomeados com um sufixo alpha e um número de versão semântico. O número da versão semântica corresponde à primeira versão da Biblioteca de Constructos da AWS com a qual são compatíveis, também com um sufixo alpha. Os constructos entram em aws-cdk-lib depois de serem designadas como estáveis, permitindo que a Biblioteca de Constructos principal adote um controle de versionamento semântico estrito.

    A estabilidade é especificada no nível de serviço. Por exemplo, se começarmos a criar um ou mais constructos L2 para o Amazon AppFlow, que no momento em que este artigo foi escrito tinha apenas constructos L1, eles aparecerão primeiro em um módulo chamado @aws-cdk/aws-appflow-alpha. Em seguida, passam para aws-cdk-lib, quando sentimos que os novos constructos atendem às necessidades fundamentais dos clientes.

    Depois que um módulo é designado como estável e incorporado em aws-cdk-lib, novas APIs são adicionadas usando a convenção “BetaN” descrita no próximo bullet.

    Uma nova versão de cada módulo experimental é lançada a cada versão do AWS CDK. Na maioria das vezes, no entanto, não precisam ser mantidos em sincronia. É possível atualizar aws-cdk-lib ou o módulo experimental sempre que quiser. A exceção é que, quando dois ou mais módulos experimentais relacionados dependem um do outro, eles devem ser da mesma versão.

  • Para módulos estáveis aos quais novas funcionalidades estão sendo adicionadas, novas APIs (sejam constructos totalmente novas ou novos métodos ou propriedades em um construto existente) recebem um sufixo Beta1 enquanto o trabalho está em andamento. (Seguido por Beta2, Beta3, e assim por diante, quando mudanças significativas são necessárias.) Uma versão da API sem o sufixo é adicionada quando a API é designada estável. Todos os métodos, exceto o mais recente (beta ou final), serão então descontinuados.

    Por exemplo, se adicionarmos um novo método grantPower() a um constructo, ele aparecerá inicialmente como grantPowerBeta1(). Se forem necessárias alterações significativas (por exemplo, um novo parâmetro ou propriedade obrigatória), a próxima versão do método será nomeada grantPowerBeta2(), e assim por diante. Quando o trabalho é concluído e a API é finalizada, o método grantPower() (sem sufixo) é adicionado e os métodos BetaN são descontinuados.

    Todas as APIs beta permanecem na Biblioteca de Constructos até o próximo lançamento da versão principal (3.0), e suas assinaturas não serão alteradas. Você verá avisos de descontinuação se as usar. Portanto, deve migrar para a versão final da API o mais brevemente possível. Contudo, nenhuma versão do AWS CDK 2.x futura prejudicará sua aplicação.

  • A classe Construct foi extraída do AWS CDK para uma biblioteca separada, junto com os tipos relacionados. Isso é feito para apoiar os esforços de aplicar o Modelo de Programação do Constructo a outros domínios. Se você estiver escrevendo seus próprios constructos ou usando APIs relacionadas, deverá declarar o módulo constructs como uma dependência e fazer pequenas alterações nas importações. Se você estiver usando atributos avançados, como conectar-se ao ciclo de vida da aplicação CDK, talvez sejam necessárias mais mudanças. Para obter detalhes completos, consulte o RFC.

  • Propriedades, métodos e tipos obsoletos do CDK da AWS v1.x e em sua Biblioteca de Constructos foram completamente removidos da API CDK v2. Na maioria das linguagens com suporte, essas APIs produzem avisos na versão v1.x, então talvez você já tenha migrado para as APIs substitutas. Uma lista completa de APIs obsoletas no CDK v1.x está disponível no GitHub.

  • O comportamento que foi controlado por sinalizadores de atributos no CDK da AWS v1.x é ativado por padrão no CDK v2. Os sinalizadores de atributos anteriores não são mais necessários e, na maioria dos casos, não há suporte para eles. Alguns ainda estão disponíveis para permitir que você volte ao comportamento do CDK v1 em circunstâncias muito específicas. Para obter mais informações, consulte Atualização dos sinalizadores de atributos.

  • Com o CDK v2, os ambientes nos quais você implanta devem ser inicializados usando a pilha de bootstrapping moderna. A pilha de bootstrapping legada (o padrão na v1) não é mais suportada. Além disso, o CDK v2 requer uma nova versão da pilha moderna. Para atualizar seus ambientes existentes, reinicialize-os. Não é mais necessário definir nenhum sinalizador de atributo ou variável de ambiente para usar a pilha de bootstrapping moderna.

Importante

O modelo de bootstrapping moderno concede efetivamente as permissões implícitas no --cloudformation-execution-policies para qualquer conta AWS na lista --trust. Por padrão, isso estende as permissões de leitura e gravação em qualquer recurso na conta inicializada. Certifique-se de configurar a pilha de bootstrapping com políticas e contas confiáveis com as quais você se sinta confortável.

Novos pré-requisitos

A maioria dos requisitos para o CDK da AWS v2 são os mesmos para o CDK da AWS v1.x. Os requisitos adicionais estão listados aqui.

  • Para desenvolvedores de TypeScript, é necessário o TypeScript 3.8 ou posterior.

  • É necessária uma nova versão do Kit de Ferramentas CDK para uso com o CDK v2. Agora que o CDK v2 está disponível ao público em geral, a v2 é a versão padrão ao instalar o Kit de Ferramentas CDK. Ele é compatível com versões anteriores de projetos do CDK v1, de forma que você não precisa manter a versão anterior instalada, a menos que queira criar projetos do CDK v1. Para atualizar, emita npm install -g aws-cdk.

Atualização a partir do AWS CDK v2 Developer Preview

Se estiver usando o CDK v2 Developer Preview, você tem dependências em seu projeto em uma versão Release Candidate do CDK da AWS, como 2.0.0-rc1. Atualize para 2.0.0 e, em seguida, atualize os módulos instalados em seu projeto.

exemplo
TypeScript

npm install ou yarn install

JavaScript

npm install ou yarn install

Python
python -m pip install -r requirements.txt
Java
mvn package
C#
dotnet restore
Go
go get

Depois de atualizar suas dependências, emita npm update -g aws-cdk para atualizar o Kit de Ferramentas CDK para a versão de lançamento.

Migração do CDK da AWS v1 para o CDK v2

Para migrar sua aplicação para o AWS CDK v2, primeiro atualize os sinalizadores de atributos em cdk.json. Em seguida, atualize as dependências e importações da sua aplicação conforme necessário para a linguagem de programação na qual ele está escrito.

Atualizando para uma v1 recente

Estamos vendo vários clientes atualizando de uma versão antiga do AWS CDK v1 para a versão mais recente de v2 em uma única etapa. Embora certamente seja possível fazer isso, você estaria atualizando ao longo de vários anos de mudanças (que, infelizmente, nem todas tiveram a mesma quantidade de testes de evolução que temos hoje), bem como atualizando várias versões com novos padrões e uma organização de código diferente.

Para uma experiência de atualização mais segura e para diagnosticar com mais facilidade as fontes de quaisquer alterações inesperadas, recomendamos que separe essas duas etapas: primeiro atualize para a versão v1 mais recente e, em seguida, faça a mudança para a v2.

Atualização de sinalizadores de atributos

Remova os seguintes sinalizadores de atributos v1 de cdk.json se eles existirem, pois todos eles estão ativos por padrão no CDK da AWS v2. Se o efeito antigo deles for importante para sua infraestrutura, você precisará fazer alterações no código-fonte. Consulte a lista de sinalizadores no GitHub para obter mais informações.

  • @aws-cdk/core:enableStackNameDuplicates

  • aws-cdk:enableDiffNoFail

  • @aws-cdk/aws-ecr-assets:dockerIgnoreSupport

  • @aws-cdk/aws-secretsmanager:parseOwnedSecretName

  • @aws-cdk/aws-kms:defaultKeyPolicies

  • @aws-cdk/aws-s3:grantWriteWithoutAcl

  • @aws-cdk/aws-efs:defaultEncryptionAtRest

Alguns sinalizadores de atributos da v1 podem ser configurados como false e reverter para comportamentos específicos do CDK da AWS v1; consulte Reversão para o comportamento da v1 ou a lista no GitHub para obter uma referência completa.

Para os dois tipos de sinalizadores, use o comando cdk diff para inspecionar as alterações em seu modelo sintetizado e ver se as alterações em algum desses sinalizadores afetam sua infraestrutura.

Compatibilidade do Kit de Ferramentas CDK

O CDK v2 requer a versão 2 ou posterior do Kit de Ferramentas CDK. Esta versão é compatível com versões anteriores das aplicações CDK v1. Portanto, é possível usar uma única versão instalada globalmente do Kit de Ferramentas CDK com todos os seus projetos do AWS CDK, sejam v1 ou v2. Uma exceção é que o Kit de Ferramentas CDK v2 só cria projetos do CDK v2.

Se você precisar criar projetos do CDK v1 e v2, não instale o Kit de Ferramentas CDK v2 globalmente. (Remova-o se você já o tiver instalado: npm remove -g aws-cdk.) Para invocar o Kit de Ferramentas CDK, use npx para executar a v1 ou v2 do Kit de Ferramentas CDK conforme desejado.

npx aws-cdk@1.x init app --language typescript
npx aws-cdk@2.x init app --language typescript
dica

Configure aliases de linha de comando para que você possa usar os comandos cdk e cdk1 para invocar a versão desejada do Kit de Ferramentas CDK.

macOS/Linux
alias cdk1="npx aws-cdk@1.x"
alias cdk="npx aws-cdk@2.x"
Windows
doskey cdk1=npx aws-cdk@1.x $*
doskey cdk=npx aws-cdk@2.x $*

Atualizando dependências e importações

Atualize as dependências da sua aplicação e, em seguida, instale os novos pacotes. Por fim, atualize as importações em seu código.

exemplo
TypeScript
Aplicações

Para aplicações CDK, atualize package.json da seguinte forma. Remova as dependências dos módulos estáveis individuais no estilo v1 e estabeleça a versão mais baixa de aws-cdk-lib que você precisa para sua aplicação (2.0.0 aqui).

Construtos experimentais são fornecidos em pacotes separados, com versões independentes, com nomes que terminam em alpha e um número de versão alfa. O número da versão alfa corresponde à primeira versão da aws-cdk-lib com a qual são compatíveis. Aqui, fixamos aws-codestar para v2.0.0-alpha.1.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}
Bibliotecas de constructos

Para bibliotecas de constructos, estabeleça a versão mais baixa de aws-cdk-lib que você precisa para sua aplicação (2.0.0 aqui) e atualize package.json da seguinte forma.

Observe que aws-cdk-lib aparece tanto como uma dependência de pares quanto como uma dependência de desenvolvimento.

{
  "peerDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0",
    "typescript": "~3.9.0"
  }
}
nota

É necessário fazer um grande aumento de versão no número da versão da sua biblioteca ao lançar uma biblioteca compatível com a v2, pois essa é uma alteração importante para os consumidores de bibliotecas. Não é possível oferecer suporte ao CDK v1 e v2 com uma única biblioteca. Para continuar oferecendo suporte aos clientes que ainda usam a v1, você pode manter a versão anterior em paralelo ou criar um novo pacote para a v2.

Depende de você por quanto tempo deseja continuar oferecendo suporte aos clientes do AWS CDK v1. É possível seguir o exemplo do ciclo de vida do próprio CDK v1, que entrou em manutenção em 1º de junho de 2022 e atingirá o fim da vida útil em 1º de junho de 2023. Para obter detalhes completos, consulte a Política de manutenção do AWS CDK.

Bibliotecas e aplicações

Instale as novas dependências executando npm install ou yarn install.

Altere suas importações para importar Construct do novo módulo constructs, tipos principais, como App e Stack do nível superior de aws-cdk-lib, e módulos estáveis da Biblioteca de Constructos para os serviços que você usa dos namespaces abaixo. aws-cdk-lib

import { Construct } from 'constructs';
import { App, Stack } from 'aws-cdk-lib';                 // core constructs
import { aws_s3 as s3 } from 'aws-cdk-lib';               // stable module
import * as codestar from '@aws-cdk/aws-codestar-alpha';  // experimental module
JavaScript

Atualize package.json da seguinte forma. Remova as dependências dos módulos estáveis individuais no estilo v1 e estabeleça a versão mais baixa de aws-cdk-lib que você precisa para sua aplicação (2.0.0 aqui).

Construtos experimentais são fornecidos em pacotes separados, com versões independentes, com nomes que terminam em alpha e um número de versão alfa. O número da versão alfa corresponde à primeira versão da aws-cdk-lib com a qual são compatíveis. Aqui, fixamos aws-codestar para v2.0.0-alpha.1.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}

Instale as novas dependências executando npm install ou yarn install.

Altere as importações da sua aplicação para fazer o seguinte:

  • Importe Construct do novo módulo de constructs

  • Importe tipos principais, como App e Stack, do nível superior de aws-cdk-lib

  • Importe módulos da Biblioteca de Constructos da AWS de namespaces em aws-cdk-lib 

const { Construct } = require('constructs');
const { App, Stack } = require('aws-cdk-lib');              // core constructs
const s3 = require('aws-cdk-lib').aws_s3;                   // stable module
const codestar = require('@aws-cdk/aws-codestar-alpha');    // experimental module
Python

Atualize requirements.txt ou a definição de install_requires em setup.py da seguinte forma. Remova as dependências dos módulos estáveis individuais no estilo v1.

Construtos experimentais são fornecidos em pacotes separados, com versões independentes, com nomes que terminam em alpha e um número de versão alfa. O número da versão alfa corresponde à primeira versão da aws-cdk-lib com a qual são compatíveis. Aqui, fixamos aws-codestar para v2.0.0alpha1.

install_requires=[
     "aws-cdk-lib>=2.0.0",
     "constructs>=10.0.0",
     "aws-cdk.aws-codestar-alpha>=2.0.0alpha1",
     # ...
],
dica

Desinstale todas as outras versões dos módulos do AWS CDK já instalados no ambiente virtual da sua aplicação usando pip uninstall. Em seguida, instale as novas dependências com python -m pip install -r requirements.txt.

Altere as importações da sua aplicação para fazer o seguinte:

  • Importe Construct do novo módulo de constructs

  • Importe tipos principais, como App e Stack, do nível superior de aws_cdk

  • Importe módulos da Biblioteca de Constructos da AWS de namespaces em aws_cdk 

from constructs import Construct
from aws_cdk import App, Stack                    # core constructs
from aws_cdk import aws_s3 as s3                  # stable module
import aws_cdk.aws_codestar_alpha as codestar     # experimental module

# ...

class MyConstruct(Construct):
    # ...

class MyStack(Stack):
    # ...

s3.Bucket(...)
Java

Em pom.xml, remova todas as dependências software.amazon.awscdk dos módulos estáveis e substitua-as por dependências em software.constructs (para Construct) e software.amazon.awscdk.

Construtos experimentais são fornecidos em pacotes separados, com versões independentes, com nomes que terminam em alpha e um número de versão alfa. O número da versão alfa corresponde à primeira versão da aws-cdk-lib com a qual são compatíveis. Aqui, fixamos aws-codestar para v2.0.0-alpha.1.

<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>aws-cdk-lib</artifactId>
    <version>2.0.0</version>
</dependency><dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>code-star-alpha</artifactId>
    <version>2.0.0-alpha.1</version>
</dependency>
<dependency>
    <groupId>software.constructs</groupId>
    <artifactId>constructs</artifactId>
    <version>10.0.0</version>
</dependency>

Instale as novas dependências executando mvn package.

Altere seu código para fazer o seguinte:

  • Importe Construct da nova biblioteca de software.constructs

  • Importe classes principais, como Stack e App, de software.amazon.awscdk

  • Importe constructos de serviços de software.amazon.awscdk.services 

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.App;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.codestar.alpha.GitHubRepository;
C#

A maneira mais simples de atualizar as dependências de uma aplicação CDK em C# é editar o arquivo .csproj manualmente. Remova todas as referências de pacotes Amazon.CDK.* estáveis e substitua-as por referências aos pacotes Amazon.CDK.Lib e Constructs.

Construtos experimentais são fornecidos em pacotes separados, com versões independentes, com nomes que terminam em alpha e um número de versão alfa. O número da versão alfa corresponde à primeira versão da aws-cdk-lib com a qual são compatíveis. Aqui, fixamos aws-codestar para v2.0.0-alpha.1.

<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0" />
<PackageReference Include="Amazon.CDK.AWS.Codestar.Alpha" Version="2.0.0-alpha.1" />
<PackageReference Include="Constructs" Version="10.0.0" />

Instale as novas dependências executando dotnet restore.

Altere as importações em seus arquivos de origem da seguinte maneira.

using Constructs;                   // for Construct class
using Amazon.CDK;                   // for core classes like App and Stack
using Amazon.CDK.AWS.S3;            // for stable constructs like Bucket
using Amazon.CDK.Codestar.Alpha;    // for experimental constructs
Go

Emita go get para atualizar suas dependências para a versão mais recente e atualizar o arquivo .mod do seu projeto.

Testanda sua aplicação migrado antes da implantação

Antes de implantar suas pilhas, use cdk diff para verificar se há mudanças inesperadas nos recursos. Não são esperadas alterações nas IDs lógicas (causando a substituição de recursos).

As mudanças esperadas incluem, mas não estão limitadas a:

  • Mudanças no recurso CDKMetadata.

  • Hashes de ativos atualizados.

  • Mudanças relacionadas ao novo estilo de síntese de pilhas. Aplica-se se a sua aplicação usou o sintetizador de pilha legado na v1.

  • A adição de uma regra CheckBootstrapVersion.

Normalmente, mudanças inesperadas não são causadas pela atualização para o AWS CDK v2 em si. Normalmente, são o resultado de um comportamento obsoleto que foi alterado anteriormente por sinalizadores de atributos. Isso é um sintoma da atualização de uma versão do CDK anterior à 1.85.x. Você veria as mesmas mudanças na atualização para a versão v1.x mais recente. É possível corrigir esse erro fazendo o seguinte:

  1. Atualize sua aplicação para a versão v1.x mais recente

  2. Remova sinalizadores de atributos

  3. Revise seu código conforme necessário

  4. Implantar

  5. Atualizar para v2

nota

Se sua aplicação atualizado não puder ser implantado após a atualização em dois estágios, relate o problema.

Quando você estiver pronto para implantar as pilhas em sua aplicação, considere implantar uma cópia primeiro para poder testá-la. A maneira mais fácil de fazer isso é implantar em uma região diferente. No entanto, você também pode alterar os IDs de suas pilhas. Após o teste, certifique-se de destruir a cópia de teste com cdk destroy.

Solução de problemas

Erros 'from' expected ou ';' expected do TypeScript nas importações

Atualize para o TypeScript 3.8 ou posterior.

Execute 'cdk bootstrap'

Se visualizar um erro como a seguir:

❌  MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
    at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)

O AWS CDK v2 requer uma pilha de bootstrapping atualizada e, além disso, todas as implantações da v2 exigem recursos de bootstrapping. (Com a v1, você pode implantar pilhas simples sem inicializar.) Para obter detalhes completos, consulte Bootstrapping do AWS CDK.

Descoberta de pilhas v1

Ao migrar sua aplicação do CDK da v1 para a v2, talvez você queira identificar as pilhas do AWS CloudFormation implantadas que foram criadas usando a v1. Para fazer isso, execute o seguinte comando:

npx awscdk-v1-stack-finder

Para obter detalhes de uso, consulte o README no awscdk-v1-stack-finder.