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](https://www.npmjs.com/package/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](constructs.md#constructs-lib-levels), 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](constructs.md#constructs-lib-levels) 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](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0192-remove-constructs-compat.md#release-notes). + 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](https://github.com/aws/aws-cdk/blob/master/DEPRECATED_APIs.md) 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](#migrating-v2-v1-upgrade-cdk-json). + 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](bootstrapping-customizing.md) 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. **Example** `npm install` ou `yarn install` `npm install` ou `yarn install` ``` python -m pip install -r requirements.txt ``` ``` mvn package ``` ``` dotnet restore ``` ``` 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](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cx-api/FEATURE_FLAGS.md) 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](featureflags.md#featureflags-disabling) 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. ``` alias cdk1="npx aws-cdk@1.x" alias cdk="npx aws-cdk@2.x" ``` ``` 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. **Example** **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" } } ``` É 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](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0079-cdk-2.0.md#aws-cdk-maintenance-policy). **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 ``` 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 ``` 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", # ... ], ``` 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(...) ``` 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. ``` software.amazon.awscdk aws-cdk-lib 2.0.0 software.amazon.awscdk code-star-alpha 2.0.0-alpha.1 software.constructs constructs 10.0.0 ``` 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; ``` A maneira mais simples de atualizar as dependências de uma aplicação CDK em C\$1 é 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. ``` ``` 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 ``` 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 1. Remova sinalizadores de atributos 1. Revise seu código conforme necessário 1. Implantar 1. 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.](https://github.com/aws/aws-cdk/issues/new/choose) 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](bootstrapping.md). ## 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](https://github.com/cdklabs/awscdk-v1-stack-finder/blob/main/README.md) no awscdk-v1-stack-finder.