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

Preserve os recursos implantados ao refatorar o código 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 boas práticas recomendadas de engenharia de software sem resultar em substituições não intencionais de recursos.

O que é refatoração de 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 da seguinte forma:

Você pode realizar a refatoração do CDK usando o cdk refactor comando CDK CLI ou a ação da CDK Toolkit Library. refactor 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 Executar ações programáticas usando a biblioteca do kit de ferramentas CDK.

Benefícios da refatoração de CDK

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

Como o comando cdk refactor 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 CDK, como renomear construções ou mover recursos entre pilhas, use o cdk refactor comando para iniciar o processo de refatoração dos recursos implantados.

Quando você executa o comando refactor, a CLI do CDK detecta suas alterações locais comparando seu código atual com o estado implantado. Ele verifica se seu aplicativo CDK contém exatamente o mesmo conjunto de recursos do estado implantado, diferindo apenas em suas localizações na árvore de construção. Em seguida, a CLI do CDK gera um plano de refatoração que mapeia os locais antigos dos recursos para os novos locais. 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 construção. 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 CDK

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

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 construção é estruturada da seguinte forma:

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

Veja a seguir um exemplo do código do nosso aplicativo:

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 construção ficaria assim:

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ê executacdk 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 inserindoy, a CLI do CDK mostra o progresso 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 cdk diff comando, 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)
...

Comece a usar a refatoração do CDK

Para começar com a refatoração, preencha estes pré-requisitos:

Use arquivos de substituição para resolver ambigüidades 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 ambigüidades 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 aplicativos, 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 seu aplicativo 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.

Manipulando 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, as Version construções do API Gateway Deployment e do Lambda são projetadas 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 e limitações gerais

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 cdk refactor CLI, consulte. cdk refactor

Para começar com a refactor ação da CDK Toolkit Library, consulte Executar ações programáticas usando a CDK Toolkit Library.