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á.
# 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](configure-synth.md). Um conjunto de nuvem contém os artefatos de implantação a seguir da sua aplicação do CDK:
+ Modelos do AWS CloudFormation que definem sua infraestrutura.
+ Ativos como código de função do Lambda ou imagens do Docker.
+ Metadados e configuração de implantação.
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;
```
**dica**
Usar um conjunto de nuvem pode otimizar a performance quando você precisa realizar várias operações, já que a síntese só acontece uma vez. Para obter mais informações sobre o gerenciamento de conjuntos de nuvem, incluindo armazenamento em cache e descarte, consulte [Criação e gerenciamento de conjuntos de nuvem](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache).
## 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](deploy.md). É 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
**Importante**
A ação refactor é uma versão de pré-visualização, e está sujeita a alterações.
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"
}
}
]
}
});
```
**Importante**
As operações de refatoração devem ser realizadas separadamente de outras ações, como adicionar, excluir ou modificar propriedades de recursos. Se precisar fazer essas alterações, é necessário primeiro implantá-las separadamente e, em seguida, usar a refatoração para reorganizar seus recursos.
**dica**
Para obter mais informações sobre a refatoração do CDK, incluindo como ela funciona e quando usá-la, consulte [Preservação de recursos implantados ao refatorar o código do CDK](refactor.md).
## 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.
**Atenção**
As implantações do Hotswap atualizam os recursos diretamente sem passar pelo CloudFormation quando possível, tornando as atualizações mais rápidas durante o desenvolvimento. Isso é habilitado por padrão para o comando `watch`. Embora isso acelere o ciclo de desenvolvimento, também introduz uma variação entre seus modelos do CloudFormation e os recursos implantados. Por isso, recomendamos não usar hotswaps em ambientes de produção.
```
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.
**Importante**
A ação destroy remove recursos permanentemente sem solicitar confirmação, ao contrário da versão da CLI desse comando. Certifique-se de ter backups de todos os dados importantes antes de destruir as pilhas.
```
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
}
});
```