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

Preservação de recursos implantados ao refatorar código do CDK

Com a refatoração do AWS Cloud Development Kit (AWS CDK), você pode refatorar seu código do CDK, como renomear construções, mover recursos entre pilhas e reorganizar seu aplicativo, preservando os recursos implantados em vez de substituí-los. Esse recurso ajuda você a manter as boas práticas recomendadas de engenharia de software sem resultar em substituições não intencionais de recursos.

O que é a refatoração do CDK com preservação de recursos?

Quando você implanta um aplicativo CDK, AWS CloudFormation identifica os recursos por sua lógica. IDs O AWS CDK gera essas lógicas IDs com base no ID da construção e em seu caminho na árvore de construção. Se você alterar o ID de uma construção ou movê-la para um local diferente em seu código, AWS CloudFormation normalmente interpreta isso como uma solicitação para criar um novo recurso e excluir o antigo. Para recursos com estado, como bancos de dados, buckets de armazenamento ou filas, essa substituição pode causar interrupções no serviço ou perda de dados.

A refatoração do CDK aborda esse desafio:

É possível realizar a refatoração do CDK usando o comando cdk refactor da CLI do CDK ou a ação refactor da Biblioteca do Kit de Ferramentas CDK. Este guia aborda principalmente a abordagem da CLI, mas os princípios subjacentes se aplicam aos dois métodos. Para obter informações sobre como usar a Biblioteca do Kit de Ferramentas, consulte Execução de ações programáticas usando a Biblioteca do Kit de Ferramentas CDK.

Benefícios da refatoração do CDK

A refatoração de CDK oferece os seguintes benefícios para desenvolvedores de CDK: AWS

Como o comando cdk refactor da CLI do CDK funciona

Primeiro, você implanta seu aplicativo CDK inicial para estabelecer recursos básicos em sua AWS conta. Depois de refatorar seu código do CDK, como renomear constructos ou mover recursos entre pilhas, use o comando cdk refactor para iniciar o processo de refatoração dos recursos implantados.

Quando você executa o comando para refatorar, a CLI do CDK detecta suas alterações locais comparando seu código atual com o estado implantado. Ela verifica se sua aplicação do CDK contém exatamente o mesmo conjunto de recursos do estado implantado, diferindo apenas em suas localizações na árvore de constructos. Em seguida, a CLI do CDK gera um plano de refatoração que mapeia as antigas localizações dos recursos para suas novas localizações. A CLI do CDK mostra as alterações propostas e, após sua confirmação, AWS CloudFormation usa a API de refatoração do CDK para atualizar a IDs lógica dos recursos sem substituí-los.

Nos bastidores, a CLI do CDK determina quais recursos foram movidos comparando suas propriedades e dependências, identificando recursos que são funcionalmente equivalentes, mas têm caminhos diferentes na árvore de constructos. Se detectar quaisquer adições, exclusões ou modificações de recursos, a operação de refatoração será rejeitada com uma mensagem de erro.

Exemplo de preservação de recursos ao refatorar o código do CDK

Neste exemplo, preservamos os recursos implantados enquanto refatoramos nosso código do CDK usando o comando cdk refactor da CLI do CDK.

Nosso exemplo de aplicativo CDK consiste em uma única pilha contendo um bucket S3, uma CloudFront distribuição e uma função Lambda. A árvore de constructos é estruturada da forma a seguir:

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

Este é um exemplo de nosso código de aplicação:

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Agora, imagine que você queira refatorar esse código para:

Depois da refatoração, a árvore de constructos deve ser semelhante a esta:

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

E o código refatorado seria:

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Sem a refatoração do CDK, essas mudanças causariam AWS CloudFormation a criação de novos recursos e a exclusão dos antigos, porque a lógica mudaria: IDs

Com a refatoração do CDK, a CLI do CDK detecta essas mudanças de caminho e usa os recursos de refatoração AWS CloudFormation do CDK para preservar os recursos subjacentes. Quando você executa cdk refactor, a CLI mostra as alterações que serão feitas:

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

Quando você confirma inserindo y, a CLI do CDK mostra o andamento da operação de refatoração:

Refactoring...
✅  Stack refactor complete

Após a confirmação, a CLI do CDK executa a operação de refatoração, preservando os dois recursos e atualizando sua lógica para corresponder à sua nova estrutura de código. IDs

O mesmo mapeamento também é mostrado na saída do comando cdk diff, organizado por pilha:

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

Conceitos básicos da refatoração do CDK

Para começar a usar a refatoração, atenda a estes pré-requisitos:

Use arquivos de substituição para resolver ambiguidades na refatoração

A CLI do CDK calcula automaticamente todos os mapeamentos de recursos com base na comparação do seu código com os recursos implantados. Na maioria dos casos, essa detecção automática funciona bem, mas há situações em que a CLI pode encontrar ambiguidades que não consegue resolver sozinha. Para fornecer orientação para a CLI do CDK, use um arquivo de substituição.

Refatoração de pilhas em vários ambientes

Um aplicativo CDK pode conter várias pilhas que são implantadas em diferentes ambientes (AWS contas e regiões). Ao preservar recursos durante a refatoração em tais aplicações, a CLI do CDK lida com ambientes de uma maneira específica:

Esse comportamento garante que os recursos permaneçam dentro da AWS conta e da região originais, o que é necessário porque CloudFormation os recursos não podem ser movidos fisicamente entre os limites da conta ou da região.

Por exemplo, se sua aplicação do CDK definir pilhas para ambientes de desenvolvimento e produção, a operação de refatoração será executada de forma independente em cada ambiente. Os recursos podem ser movidos entre pilhas dentro do ambiente de desenvolvimento ou dentro do ambiente de produção, mas não do desenvolvimento para a produção ou vice-versa.

Manipulação de recursos projetados para serem substituídos

Algumas construções de CDK dependem CloudFormation do comportamento de substituição de recursos do CDK como parte de seu design. Por exemplo, os constructos Deployment da API Gateway e Version do Lambda são projetados para criar novos recursos quando suas propriedades mudam.

Ao refatorar, não inclua nenhuma alteração que deva resultar em substituições de recursos. Caso contrário, a CLI do CDK poderá detectar e preservar esses recursos. Isso significa que os recursos projetados para serem substituídos devem ser tratados separadamente das operações de refatoração.

Para gerenciar adequadamente os recursos projetados para serem substituídos:

Essa abordagem em duas etapas garante que os recursos projetados para serem substituídos sejam tratados adequadamente, ao mesmo tempo em que permite que você se beneficie da refatoração do CDK para outros recursos.

Considerações gerais e limitações

Ao preservar os recursos durante a refatoração do CDK, tenha em mente estas considerações:

Refatoração com tubulações CI/CD

Para usar o recurso de refatoração em CI/CD pipelines, você precisa ser capaz de executar a CLI do CDK como parte do seu pipeline. A seguir estão algumas considerações importantes para integrar a refatoração em seu fluxo de trabalho. CI/CD

Recursos relacionados

Para obter informações sobre opções e argumentos para o comando cdk refactor da CLI do CDK, consulte cdk refactor .

Para começar com a ação refactor da Biblioteca do Kit de Ferramentas CDK, consulte Execução de ações programáticas usando a Biblioteca do Kit de Ferramentas CDK.