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.

Configuração de ações programáticas do Kit de Ferramentas CDK

A Biblioteca do Kit de Ferramentas CDK da AWS fornece interfaces programáticas para ações do ciclo de vida da aplicação, como síntese, implantação e gerenciamento de pilhas. Este guia explica como usar cada ação no seu código.

Gerando conjuntos de nuvem com sintetização

A ação synth gera um conjunto de nuvem a partir de sua fonte de conjunto de nuvem. Para obter mais informações sobre a síntese, consulte Configuração e realização da síntese de pilhas do CDK. Um conjunto de nuvem contém os artefatos de implantação a seguir da sua aplicação do CDK:

Veja como usar a ação synth para criar um conjunto de nuvem:

// Create a toolkit instance
const toolkit = new Toolkit();

// Create a cloud assembly source from a TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");

// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);

// Use the cloud assembly for operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
await toolkit.diff(cloudAssembly);

// Query information from the cloud assembly
const template = cloudAssembly.getStack("my-stack").template;

Visualização de informações da pilha com list

A ação list recupera informações sobre as pilhas em sua aplicação do CDK, incluindo suas dependências e o status atual. Use essa ação para inspecionar sua infraestrutura antes da implantação ou para gerar relatórios.

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Get information about specific stacks
const stackDetails = await toolkit.list(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"], // Only include stacks matching this pattern
  }
});

// Process the returned stack information
for (const stack of stackDetails) {
  console.log(`Stack: ${stack.id}, Dependencies: ${stack.dependencies}`);
}

Provisionamento de infraestrutura com deploy

A ação deploy provisiona ou atualiza sua infraestrutura da AWS usando o conjunto de nuvem produzido durante a síntese. Para pbter uma introdução à implantação, consulte Implantação de aplicações do AWS CDK. É possível controlar as opções de implantação, como seleção de pilha, valores de parâmetros e comportamento de reversão.

// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

A ação de implantação oferece suporte a diferentes métodos de implantação para acomodar vários fluxos de trabalho. Para a maioria dos cenários, especialmente em ambientes de produção, recomendamos usar o método de implantação padrão, que usa conjuntos de alterações do CloudFormation. Para ambientes de desenvolvimento em que a velocidade de iteração é importante, é possível usar métodos alternativos, como o hotswap.

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Deploy using default deployment method (recommended for production)
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

// For development environments only: Deploy with hotswap for faster iterations
// Note: We recommend using default deployment methods for production environments
await toolkit.deploy(cloudAssemblySource, {
  deploymentMethod: { method: "hotswap", fallback: true }, // Faster but introduces drift
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["dev-stack"]
  }
});

Preservação dos recursos implantados com refactor

A ação refactor preserva os recursos implantados ao refatorar o código do CDK, como renomear constructos ou movê-los entre pilhas. Sem esse recurso, essas mudanças fariam com que o CloudFormation substituísse recursos, potencialmente levando a interrupções do serviço ou a perda de dados.

A ação de refatoração calcula automaticamente os mapeamentos 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. 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.

Depois de computar os mapeamentos, a ação de refatoração usa a API de refatoração do CloudFormation para atualizar os IDs lógicos dos recursos sem substituí-los. Se encontrar mapeamentos ambíguos (onde existam vários mapeamentos possíveis), será possível fornecer substituições explícitas para resolver essas ambiguidades.

// Perform refactoring operation to preserve resources
await toolkit.refactor(cloudAssemblySource);

// With optional overrides to resolve ambiguities
await toolkit.refactor(cloudAssemblySource, {
  overrides: {
    "environments": [
      {
        "account": "123456789012",
        "region": "us-east-2",
        "resources": {
          "StackA.OldName": "StackA.NewName"
        }
      }
    ]
  }
});

Reversão de implantações com falha com rollback

A ação rollback retorna uma pilha ao seu último estado estável quando uma implantação falha e não pode ser revertida automaticamente. Use essa ação para se recuperar de implantações com falha que exijam intervenção manual.

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Roll back stacks to their last stable state
await toolkit.rollback(cloudAssemblySource, {
  orphanFailedResources: false, // When true, removes failed resources from CloudFormation management
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["failed-stack"]
  }
});

Monitoração de alterações com watch

A ação watch monitora continuamente sua aplicação do CDK em busca de alterações de arquivos locais e executa automaticamente implantações ou hotswaps. Isso cria um observador de arquivos que será executado até que seu código saia ou seja encerrado.

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Start watching for changes
const watcher = await toolkit.watch(cloudAssemblySource, {
  include: ["lib/**/*.ts"], // Only watch TypeScript files in the lib directory
  exclude: ["**/*.test.ts"], // Ignore test files
  deploymentMethod: { method: "hotswap" }, // This is the default, shown here for clarity
  stacks: {
    strategy: StackSelectionStrategy.ALL // Watch all stacks
  }
});

// Later in your code, you can explicitly stop watching:
// await watcher.dispose();

A função watch retorna um objeto IWatcher que permite controlar explicitamente quando parar de observar. Chame o método dispose() nesse objeto quando quiser finalizar o processo de observação.

Remoção da infraestrutura com destroy

A ação destroy remove as pilhas do CDK e seus recursos associados do AWS. Use essa ação para limpar os recursos quando eles não forem mais necessários.

import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

// Remove specific stacks and their resources
await toolkit.destroy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["dev-stack"], // Only destroy stacks matching this pattern
  }
});