View a markdown version of this page

Migre os recursos existentes e AWS CloudFormation modelos para o AWS CDK - AWS Kit de desenvolvimento em nuvem (AWS CDK) v2

Este é o AWS Guia do desenvolvedor do 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á.

Migre os recursos existentes e AWS CloudFormation modelos para o AWS CDK

O recurso CDK Migrate está em versão prévia para AWS CDK e está sujeito a alterações.

Use o AWS Kit de desenvolvimento em nuvem (AWS CDK) Interface de linha de comando (AWS CDK (CLI) para migrar, implantado AWS recursos, implantados AWS CloudFormation pilhas e locais AWS CloudFormation modelos para AWS CDK.

Como funciona a migração

Use o AWS CDK CLI cdk migrate comando para migrar das seguintes fontes:

  • Implantado AWS recursos.

  • Implantado AWS CloudFormation pilhas.

  • Local AWS CloudFormation modelos.

Implantado AWS recursos

Você pode migrar implantado AWS recursos de um ambiente específico (AWS conta e AWS Região) que não estão associadas a um AWS CloudFormation pilha.

O AWS O CDK CLI utiliza o Gerador IAc serviço para procurar recursos em seu AWS ambiente para reunir detalhes dos recursos. Para saber mais sobre o gerador IaC, consulte Geração de modelos para recursos existentes na AWS CloudFormation Guia do usuário.

Depois de reunir os detalhes do recurso, o AWS O CDK CLI cria um novo aplicativo CDK que inclui uma única pilha contendo seus recursos migrados.

Implantado AWS CloudFormation pilhas

Você pode migrar um único AWS CloudFormation empilhe em um novo AWS Aplicativo CDK. O AWS O CDK CLI recuperará o AWS CloudFormation modelo de sua pilha e crie um novo aplicativo CDK. O aplicativo CDK consistirá em uma única pilha que contém seu arquivo migrado AWS CloudFormation pilha.

Local AWS CloudFormation modelos

Você pode migrar de um local AWS CloudFormation modelo. Os modelos locais podem ou não conter recursos implantados. O AWS O CDK CLI criará um novo aplicativo CDK que contém uma única pilha com seus recursos.

Após a migração, você pode gerenciar, modificar e implantar seu aplicativo CDK no AWS CloudFormation para provisionar ou atualizar seus recursos.

Benefícios do CDK Migrate

Migração de recursos para AWS Historicamente, o CDK tem sido um processo manual que exige tempo e experiência com AWS CloudFormation e AWS CDK para começar. Com o CDK Migrate, o AWS O CDK CLI facilita a maior parte do esforço de migração para você em uma fração do tempo. O CDK Migrate ajudará você a começar rapidamente a usar o AWS CDK para desenvolver e gerenciar aplicativos novos e existentes no AWS.

Considerações

Considerações gerais

CDK Migrate versus CDK Import

O comando cdk import pode importar recursos implantados em uma aplicação do CDK novo ou existente. Ao importar, cada recurso precisará ser definido manualmente como um constructo L1 em sua aplicação. Recomendamos usar cdk import para importar um ou mais recursos por vez em uma aplicação o CDK novo ou existente. Para saber mais, consulte Importação de recursos existentes para uma pilha.

O cdk migrate o comando migra dos recursos implantados, implantados AWS CloudFormation pilhas ou locais AWS CloudFormation modelos em um novo aplicativo CDK. Durante a migração, o AWS Usos do CDK CLI cdk import para importar seus recursos para o novo aplicativo CDK. O AWS O CDK CLI também gera construções L1 para cada recurso para você. Recomendamos usar cdk migrate ao importar de uma fonte de migração compatível para uma nova AWS Aplicativo CDK.

O CDK Migrate cria somente construções L1

A aplicação do CDK recém-criado incluirá somente constructos L1. É possível adicionar constructos de alto nível à sua aplicação após a migração.

O CDK Migrate cria aplicativos CDK que contêm uma única pilha

A aplicação do CDK recém-criado conterá uma única pilha.

Ao migrar os recursos implantados, todos os recursos migrados estarão contidos em uma única pilha na nova aplicação do CDK.

Ao migrar AWS CloudFormation pilhas, você só pode migrar uma única AWS CloudFormation empilhe em uma única pilha no novo aplicativo CDK.

Migração de ativos

Ativos do projeto, como AWS O código Lambda não migrará diretamente para o novo aplicativo CDK. Após a migração, você pode especificar os valores dos ativos para incluí-los na aplicação do CDK.

Migração de recursos com estado

Ao migrar recursos com estado, como bancos de dados e buckets do Amazon Simple Storage Service (Amazon S3), você geralmente deseja migrar o recurso existente em vez de criar um novo recurso.

Para migrar e preservar recursos com estado, faça o seguinte:

  • Verifique se seu recurso com estado é compatível com importação. Para obter mais informações, consulte Suporte ao tipo de recurso na AWS CloudFormation Guia do usuário.

  • Após a migração, verifique se o ID lógico do recurso migrado na nova aplicação do CDK corresponde ao ID lógico do recurso implantado.

  • Se estiver migrando de um AWS CloudFormation pilha, verifique se o nome da pilha no novo aplicativo CDK corresponde ao AWS CloudFormation pilha.

  • Implante o aplicativo CDK usando o mesmo AWS conta e AWS Região do recurso migrado.

Considerações ao migrar de um AWS CloudFormation modelo

O CDK Migrate oferece suporte à migração de modelo único

Ao migrar AWS CloudFormation modelos, você pode selecionar um único modelo para migrar. Não há suporte para modelos aninhados.

Migração de modelos com funções intrínsecas

Ao migrar de um AWS CloudFormation modelo que usa funções intrínsecas, o AWS O CDK CLI tentará migrar sua lógica para o aplicativo CDK com o Fn classe. Para saber mais, consulte classe Fn na AWS Kit de desenvolvimento em nuvem (AWS Referência da API CDK).

Considerações ao migrar dos recursos implantados

Limitações de verificação

Ao verificar seu ambiente em busca de recursos, o gerador de IaC tem limitações específicas nos dados que ele pode recuperar e limitações de cota durante a digitalização. Para saber mais, consulte Considerações na AWS CloudFormation Guia do usuário.

Pré-requisitos

Antes de usar o cdk migrate comando, conclua todas as etapas de configuração em Começando com o AWS CDK.

Começar a usar o CDK Migrate

Para começar, execute o AWS CDK CLI cdk migrate comando de um diretório de sua escolha. Forneça as opções necessárias e opcionais, dependendo do tipo de migração que você está realizando.

Para obter uma lista completa e uma descrição das opções que podem ser usados com cdk migrate, consulte cdk migrate.

A seguir estão algumas opções importantes que você pode oferecer.

Nome da stack

A única opção necessária é --stack-name. Use essa opção para especificar um nome para a pilha que será criada dentro do AWS Aplicativo CDK após a migração. O nome da pilha também será usado como o nome do seu AWS CloudFormation pilha na implantação.

Linguagem

Use --language para especificar a linguagem de programação da nova aplicação do CDK.

AWS conta e AWS Região

O AWS O CDK CLI recupera AWS conta e AWS Informações da região de fontes padrão. Para obter mais informações, consulte Ambientes para o AWS CDK. É possível usar as opções --account e --region com cdk migrate para fornecer outros valores.

Diretório de saída do seu novo projeto CDK

Por padrão, o AWS O CDK CLI criará um novo projeto de CDK em seu diretório de trabalho e usará o valor que você fornece --stack-name para nomear a pasta do projeto. Se uma pasta com o mesmo nome existir atualmente, a AWS O CDK CLI substituirá essa pasta.

É possível especificar um caminho de saída diferente para a nova pasta do projeto do CDK com a opção --output-path.

Fonte de migração

Forneça uma opção para especificar a origem da qual você está migrando.

  • --from-path — Migrar de um local AWS CloudFormation modelo.

  • --from-scan — Migre dos recursos implantados em um AWS conta e AWS Região.

  • --from-stack — Migrar de um AWS CloudFormation pilha.

Dependendo da fonte de migração, você pode fornecer opções adicionais para personalizar o comando cdk migrate.

Migrar de um AWS CloudFormation pilha

Para migrar de um implantado AWS CloudFormation empilhe, forneça o --from-stack opção. Forneça o nome do seu implantado AWS CloudFormation empilhar com --stack-name. Este é um exemplo:

$ cdk migrate --from-stack --stack-name "myCloudFormationStack"

O AWS O CDK CLI fará o seguinte:

  1. Recupere o AWS CloudFormation modelo de sua pilha implantada.

  2. Executar o cdk init para inicializar um nova aplicação do CDK.

  3. Crie uma pilha dentro do aplicativo CDK que contém seu arquivo migrado AWS CloudFormation pilha.

Quando você migra de um implantado AWS CloudFormation pilha, a AWS O CDK CLI tenta combinar os IDs lógicos dos recursos implantados e os implantados AWS CloudFormation nome da pilha para os recursos migrados e a pilha no novo aplicativo CDK.

Após a migração, você pode gerenciar e modificar sua aplicação do CDK normalmente. Quando você implanta, AWS CloudFormation identificará a implantação como uma AWS CloudFormation atualização da pilha devido à correspondência AWS CloudFormation nome da pilha. Os recursos com IDs lógicos correspondentes serão atualizados. Para obter mais informações sobre implantação, consulte Gerenciamento e implantação da sua aplicação do CDK.

Migrar de um AWS CloudFormation modelo

O CDK Migrate suporta a migração de AWS CloudFormation modelos formatados em JSON ou YAML.

Para migrar de um local AWS CloudFormation modelo, use o --from-path opção e forneça um caminho para o modelo local. Também é necessário fornecer a opção --stack-name obrigatória. Este é um exemplo:

$ cdk migrate --from-path "./template.json" --stack-name "myCloudFormationStack"

O AWS O CDK CLI fará o seguinte:

  1. Recupere seu local AWS CloudFormation modelo.

  2. Executar o cdk init para inicializar um nova aplicação do CDK.

  3. Crie uma pilha dentro do aplicativo CDK que contém seu arquivo migrado AWS CloudFormation modelo.

Após a migração, você pode gerenciar e modificar sua aplicação do CDK normalmente. Na implantação, você tem as seguintes opções:

  • Atualizar um AWS CloudFormation pilha — Se o local AWS CloudFormation o modelo foi implantado anteriormente, você pode atualizar o implantado AWS CloudFormation pilha.

  • Implante um novo AWS CloudFormation pilha — Se o local AWS CloudFormation o modelo nunca foi implantado, ou se você quiser criar uma nova pilha a partir de um modelo implantado anteriormente, você pode implantar um novo AWS CloudFormation pilha.

Migrar de um AWS Modelo do SAM

Para migrar de um AWS Modelo de aplicativo sem servidor (AWS Modelo SAM), você deve primeiro convertê-lo em um AWS CloudFormation modelo ou implantação para criar um AWS CloudFormation pilha.

Para converter um AWS Modelo SAM para AWS CloudFormation, você pode usar o AWS MESMO CLIPE sam validate --debug comando. Talvez seja necessário definir lint como false em seu arquivo samconfig.toml antes de executar esse comando.

Para converter em um AWS CloudFormation empilhe, implante o AWS Modelo de SAM usando o AWS MESMO CLIPE. Em seguida, migre da pilha implantada.

Migrar dos recursos implantados

Para migrar do implantado AWS recursos, forneça o --from-scan opção. Também é necessário fornecer a opção --stack-name obrigatória. Este é um exemplo:

$ cdk migrate --from-scan --stack-name "myCloudFormationStack"

O AWS O CDK CLI fará o seguinte:

  1. Examine sua conta para obter detalhes de recursos e propriedades — O AWS O CDK CLI utiliza o gerador IaC para escanear sua conta e coletar detalhes.

  2. Gere um AWS CloudFormation modelo — Após a digitalização, o AWS O CDK CLI utiliza o gerador IaC para criar um AWS CloudFormation modelo.

  3. Inicialize um novo aplicativo CDK e migre seu modelo — O AWS O CDK CLI é executado cdk init para inicializar um novo AWS Aplicativo CDK e migra seu AWS CloudFormation modelo no aplicativo CDK como uma única pilha.

Usar filtros

Por padrão, o AWS O CDK CLI digitalizará todo o AWS ambiente e migre recursos até o limite máximo de cota do gerador IaC. Você pode fornecer filtros com o AWS CDK CLI para especificar um critério para o qual os recursos são migrados da sua conta para o novo aplicativo CDK. Para saber mais, consulte --filter .

Verificar recursos com o gerador de IaC

Dependendo do número de recursos na sua conta, a verificação pode demorar alguns minutos. Uma barra de andamento será exibida durante o processo de verificação.

Tipos de recursos compatíveis

O AWS O CDK CLI migrará os recursos suportados pelo gerador IaC. Para obter uma lista completa, consulte Suporte ao tipo de recurso na AWS CloudFormation Guia do usuário.

Resolver propriedades somente gravação

Alguns recursos compatíveis contêm propriedades somente gravação. Essas propriedades podem ser gravadas para configurar a propriedade, mas não podem ser lidas pelo gerador IaC ou AWS CloudFormation para obter o valor. Por exemplo, uma propriedade usada para especificar uma senha de banco de dados pode ser somente gravação por motivos de segurança.

Ao verificar recursos durante a migração, o gerador de IaC detectará recursos que possam conter propriedades somente gravação e os categorizará em qualquer um dos seguintes tipos:

  • MUTUALLY_EXCLUSIVE_PROPERTIES: essas são propriedades somente gravação para um recurso específico que são intercambiáveis e têm uma finalidade semelhante. Uma das propriedades mutuamente exclusivas é necessária para configurar seu recurso. Por exemplo, as propriedades S3Bucket, ImageUri e ZipFile de um recurso AWS::Lambda::Function são propriedades mutuamente exclusivas somente gravação. Qualquer uma delas pode ser usada para especificar seus ativos de função, mas você deve usar uma.

  • MUTUALLY_EXCLUSIVE_TYPES: essas são propriedades obrigatórias somente gravação que aceitam vários tipos de configuração. Por exemplo, a propriedade Body de um recurso AWS::ApiGateway::RestApi aceita um tipo de objeto ou string.

  • UNSUPPORTED_PROPERTIES: essas são propriedades somente gravação que não se enquadram nas outras duas categorias. Elas são propriedades opcionais ou obrigatórias que aceitam uma matriz de objetos.

Para obter mais informações sobre propriedades somente de gravação e como o gerador IaC as gerencia ao escanear recursos implantados e criar AWS CloudFormation modelos, consulte Gerador IAc e propriedades somente de gravação na AWS CloudFormation Guia do usuário.

Após a migração, você deve especificar valores de propriedade somente gravação na nova aplicação do CDK. O AWS O CDK CLI anexará um Advertências seção do projeto CDK ReadMe arquivo para documentar quaisquer propriedades somente de gravação que foram identificadas pelo gerador IaC. Este é um exemplo:

# Welcome to your CDK TypeScript project ... ## Warnings ### Write-only properties Write-only properties are resource property values that can be written to but can't be read by AWS CloudFormation or CDK Migrate. For more information, see [IaC generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html). Write-only properties discovered during migration are organized here by resource ID and categorized by write-only property type. Resolve write-only properties by providing property values in your CDK app. For guidance, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly). ### MyLambdaFunction - **UNSUPPORTED_PROPERTIES**: - SnapStart/ApplyOn: Applying SnapStart setting on function resource type.Possible values: [PublishedVersions, None] This property can be replaced with other types - Code/S3ObjectVersion: For versioned objects, the version of the deployment package object to use. This property can be replaced with other exclusive properties - **MUTUALLY_EXCLUSIVE_PROPERTIES**: - Code/S3Bucket: An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account. This property can be replaced with other exclusive properties - Code/S3Key: The Amazon S3 key of the deployment package. This property can be replaced with other exclusive properties
  • Os avisos são organizados em títulos que identificam o ID lógico do recurso ao qual estão associados.

  • Os avisos são categorizados por tipo. Esses tipos vêm diretamente do gerador de IaC.

Para resolver propriedades somente de gravação
  1. Identifique propriedades somente gravação a serem resolvidas na seção Avisos do arquivo ReadMe do seu projeto do CDK. Aqui, você pode anotar os recursos em sua aplicação do CDK que podem conter propriedades somente gravação e identificar os tipos de propriedades somente gravação que foram descobertos.

    1. Para MUTUALLY_EXCLUSIVE_PROPERTIES, determine qual propriedade mutuamente exclusiva configurar em seu AWS Aplicativo CDK.

    2. Em MUTUALLY_EXCLUSIVE_TYPES, determine qual tipo aceito você usará para configurar a propriedade.

    3. Em UNSUPPORTED_PROPERTIES, determine se a propriedade é opcional ou obrigatória. Em seguida, configure conforme for necessário.

  2. Use a orientação em gerador de IaC e propriedades somente gravação para ter uma referência sobre o que significam os tipos de aviso.

  3. Na sua aplicação do CDK, os valores das propriedades somente gravação a serem resolvidos também serão especificados na seção Props da sua aplicação. Forneça os valores corretos aqui. Para descrições e orientações sobre propriedades, é possível consultar a Referência de API do AWS CDK.

    Veja a seguir um exemplo da seção Props em uma aplicação do CDK migrado com duas propriedades somente gravação a serem resolvidas:

    export interface MyTestAppStackProps extends cdk.StackProps { /** * The Amazon S3 key of the deployment package. */ readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Keym8P82: string; /** * An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account. */ readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Bucketzidw8: string; }

    Depois de resolver todos os valores de propriedade somente gravação, você estará pronto para se preparar para a implantação.

O arquivo migrate.json

O AWS O CDK CLI cria um migrate.json arquivo em seu AWS Projeto CDK durante a migração. Esse arquivo contém informações de referência sobre seus recursos implantados. Quando você implanta seu aplicativo CDK pela primeira vez, o AWS O CDK CLI usa esse arquivo para referenciar seus recursos implantados e associa seus recursos ao novo AWS CloudFormation empilha e exclui o arquivo.

Gerenciar e implantar sua aplicação do CDK

Ao migrar para AWS CDK, o novo aplicativo CDK, pode não estar pronto para implantação imediatamente. Este tópico descreve itens de ação a serem considerados ao gerenciar e implantar sua nova aplicação do CDK.

Preparar-se para implantação

Antes da implantação, você deve preparar sua aplicação do CDK.

Sintetize seu aplicativo

Use o cdk synth comando para sintetizar a pilha em seu aplicativo CDK em um AWS CloudFormation modelo.

Se você migrou de um implantado AWS CloudFormation pilha ou modelo, você pode comparar o modelo sintetizado com o modelo migrado para verificar os valores dos recursos e das propriedades.

Para saber mais sobre cdk synth, consulte Sintetização de pilhas.

Faça uma comparação

Se você migrou de um implantado AWS CloudFormation stack, você pode usar o comando cdk diff para comparar com a pilha em seu novo aplicativo CDK.

Para saber mais sobre o cdk diff, consulte Comparação de pilhas.

Inicialize seu ambiente

Se você estiver implantando a partir de um AWS ambiente pela primeira vez, use cdk bootstrap para preparar seu ambiente. Para saber mais, consulte Bootstrapping do AWS CDK.

Implantar sua aplicação do CDK

Quando você implanta um aplicativo CDK, o AWS O CDK CLI utiliza o AWS CloudFormation serviço para provisionar seus recursos. Os recursos são agrupados em uma única pilha no aplicativo CDK e implantados como uma única AWS CloudFormation pilha.

Dependendo de onde você migrou, você pode implantar para criar um novo AWS CloudFormation empilhar ou atualizar um existente AWS CloudFormation pilha.

Implante para criar um novo AWS CloudFormation pilha

Se você migrou dos recursos implantados, o AWS O CDK CLI criará automaticamente um novo AWS CloudFormation pilha na implantação. Seus recursos implantados serão incluídos no novo AWS CloudFormation pilha.

Se você migrou de um local AWS CloudFormation modelo que nunca foi implantado, o AWS O CDK CLI criará automaticamente um novo AWS CloudFormation pilha na implantação.

Se você migrou de um implantado AWS CloudFormation pilha ou local AWS CloudFormation modelo que foi implantado anteriormente, você pode implantar para criar um novo AWS CloudFormation pilha. Para criar uma nova pilha, faça o seguinte:

  • Implante em um novo AWS meio ambiente. Isso consiste em usar um diferente AWS conta ou implantação em uma conta diferente AWS Região.

  • Se você quiser implantar uma nova pilha na mesma AWS ambiente da pilha ou modelo migrado, você deve modificar o nome da pilha em seu aplicativo CDK para um novo valor. Você também deve modificar todos os IDs lógicos dos recursos em sua aplicação do CDK. Em seguida, você pode implantar no mesmo ambiente para criar uma nova pilha e novos recursos.

Implante para atualizar um existente AWS CloudFormation pilha

Se você migrou de um implantado AWS CloudFormation pilha ou local AWS CloudFormation modelo que foi implantado anteriormente, você pode implantar para atualizar o existente AWS CloudFormation pilha.

Verifique se o nome da pilha em seu aplicativo CDK corresponde ao nome da pilha implantada AWS CloudFormation empilhe e implante no mesmo AWS meio ambiente.