Migrar de AWS CDK v1 para AWS CDK v2 - AWS Cloud Development Kit (AWS CDK) v2
Novos pré-requisitosAtualização a partir de AWS CDK v2 Developer PreviewMigrar de AWS CDK v1 para CDK v2Testando seu aplicativo migrado antes da implantaçãoSolução de problemasDescoberta de pilhas v1

Este é o Guia do Desenvolvedor AWS CDK v2. A CDK v1 mais antiga 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á.

Migrar de AWS CDK v1 para AWS CDK v2

A versão 2 de AWS Cloud Development Kit (AWS CDK) 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 de AWS CDK.

dica

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

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

  • 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 CDK.

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

  • 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, 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 de AWS CDK. Na maioria das vezes, no entanto, não precisam ser mantidos em sincronia. Você pode 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. No entanto, nenhuma versão AWS CDK 2.x futura prejudicará seu aplicativo.

  • A classe Construct foi extraída de 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 do aplicativo CDK, talvez sejam necessárias mais mudanças. Para obter detalhes completos, consulte o RFC.

  • Propriedades, métodos e tipos obsoletos em AWS CDK v1.x e em sua Biblioteca de Constructos foram completamente removidos da API CDK v2. Na maioria dos idiomas compatíveis, 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 em AWS CDK 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 são suportados. Alguns ainda estão disponíveis para permitir que você volte ao comportamento do CDK v1 em circunstâncias muito específicas. Para ter mais informações, consulte Atualização de sinalizadores de atributos.

  • Com o CDK v2, os ambientes nos quais você implanta devem ser inicializados usando a pilha de bootstrap moderna. A pilha de bootstrap 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 bootstrap moderna.

Importante

O modelo de bootstrap 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 inicialização com políticas e contas confiáveis com as quais você se sinta confortável.

Novos pré-requisitos

A maioria dos requisitos para AWS CDK v2 é a mesma para AWS CDK 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 CDK Toolkit 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 CDK Toolkit. Ele é compatível com versões anteriores de projetos CDK v1, então você não precisa manter a versão anterior instalada, a menos que queira criar projetos CDK v1. Para atualizar, emita npm install -g aws-cdk.

Atualização a partir de 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 AWS CDK, como 2.0.0-rc1. Atualize para 2.0.0 e, em seguida, atualize os módulos instalados em seu projeto.

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 CDK Toolkit para a versão de lançamento.

Migrar de AWS CDK v1 para CDK v2

Para migrar seu aplicativo para AWS CDK v2, primeiro atualize os sinalizadores de atributos em cdk.json. Em seguida, atualize as dependências e importações do seu aplicativo 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 de 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 em AWS CDK 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 para false e reverter para comportamentos específicos de AWS CDK v1; consulte Revertendo para o comportamento 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 CDK Toolkit

O CDK v2 requer a versão 2 ou posterior do CDK Toolkit. Esta versão é compatível com versões anteriores dos aplicativos CDK v1. Portanto, você pode usar uma única versão instalada globalmente do CDK Toolkit com todos os seus AWS CDK projetos, sejam v1 ou v2. Uma exceção é que o CDK Toolkit v2 só cria projetos CDK v2.

Se você precisar criar projetos CDK v1 e v2, não instale o CDK Toolkit v2 globalmente. (Remova-o se você já o tiver instalado: npm remove -g aws-cdk.) Para invocar o CDK Toolkit, use npx para executar a v1 ou v2 do CDK Toolkit 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 CDK Toolkit.

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 do seu aplicativo e, em seguida, instale os novos pacotes. Por fim, atualize as importações em seu código.

TypeScript
Aplicações

Para aplicativos 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 seu aplicativo (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 de 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 seu aplicativo (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

Você deve 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 de AWS CDK v1. Você pode 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 de AWS CDK.

Bibliotecas e aplicativos

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 seu aplicativo (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 de 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 do seu aplicativo 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 de 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 AWS CDK já instalados no ambiente virtual do seu aplicativo usando pip uninstall. Em seguida, instale as novas dependências com python -m pip install -r requirements.txt.

Altere as importações do seu aplicativo 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 de 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 um aplicativo 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 de 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.

Testando seu aplicativo 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 o seu aplicativo usou o sintetizador de pilha legado na v1. (O CDK v2 não é compatível com o sintetizador de pilha legado.)

  • A adição de uma regra CheckBootstrapVersion.

Normalmente, mudanças inesperadas não são causadas pela atualização para a 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. Você pode corrigir esse erro fazendo o seguinte:

  1. Atualize seu aplicativo 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 seu aplicativo 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 seu aplicativo, 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

TypeScript 'from' expected ou erro ';' expected 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)

AWS CDK v2 requer uma pilha de bootstrap atualizada e, além disso, todas as implantações da v2 exigem recursos de bootstrap. (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 seu aplicativo CDK da v1 para a v2, talvez você queira identificar as pilhas 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.