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á.
# Execute ações programáticas usando a Biblioteca do Kit de Ferramentas CDK
## Noções básicas da Biblioteca do Kit de Ferramentas CDK
A Biblioteca do Kit de Ferramentas CDK permite que você execute ações do CDK programaticamente, por meio de código, em vez de usar comandos da CLI. É possível usar essa biblioteca para criar ferramentas personalizadas, criar aplicações da CLI especializadas e integrar recursos do CDK em seus fluxos de trabalho de desenvolvimento.
**Gerencie o ciclo de vida da sua infraestrutura com controle programático**
A Biblioteca do Kit de Ferramentas CDK fornece interfaces programáticas para as ações do CDK a seguir:
+ **Síntese**: gera modelos e artefatos de implantação do AWS CloudFormation.
+ **Implantação**: provisiona ou atualiza a infraestrutura usando modelos do CloudFormation.
+ **Refatorar**: preserva os recursos implantados ao refatorar o código CDK, como renomear constructos ou movê-los entre pilhas.
+ **Listar**: visualiza informações sobre pilhas e suas dependências.
+ **Assistir**: monitora as aplicações do CDK em busca de mudanças locais.
+ **Reverter**: retorna as pilhas ao seu último estado estável.
+ **Destruir**: remove pilhas do CDK e recursos associados.
**Melhore e personalize seu gerenciamento de infraestrutura**
+ **Controle por meio de código**: integre o gerenciamento da infraestrutura diretamente em suas aplicações e crie pipelines de implantação responsivos.
+ **Gerenciamento de conjuntos de nuvem**: crie, inspecione e transforme suas definições de infraestrutura antes da implantação.
+ **Personalização de implantações**: configure parâmetros, comportamento de reversão e monitoramento para atender às suas necessidades.
+ **Preservação de recursos durante a refatoração**: detecte e preserve recursos automaticamente ao refatorar o código do CDK.
+ **Tratamento de erros com precisão**: implemente o tratamento estruturado de erros com informações detalhadas de diagnóstico.
+ **Personalize as comunicações**: configure indicadores de andamento e logs personalizados por meio de implementações do `IoHost`.
+ **Conecte-se com a AWS**: configure perfis, regiões e fluxos de autenticação programaticamente.
## Escolha de quando usar a Biblioteca do Kit de Ferramentas CDK
A Biblioteca do Kit de Ferramentas CDK é particularmente valiosa quando você precisa:
+ Automatizar as implantações de infraestrutura como parte dos pipelines de CI/CD.
+ Criar ferramentas de implantação personalizadas de acordo com as necessidades da sua organização.
+ Integrar as ações do CDK em aplicações ou plataformas existentes.
+ Criar fluxos de trabalho de implantação especializados com etapas personalizadas de validação ou aprovação.
+ Implementar padrões avançados de gerenciamento de infraestrutura em vários ambientes.
+ Automatizar as operações de refatoração para preservar recursos ao refatorar o código do CDK.
## Usar a Biblioteca do Kit de Ferramentas CDK
O exemplo a seguir mostra como criar e implantar um bucket do S3 simples usando a Biblioteca do Kit de Ferramentas CDK:
```
// Import required packages
import { Toolkit } from '@aws-cdk/toolkit-lib';
import { App, Stack } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
// Create and configure the CDK Toolkit
const toolkit = new Toolkit();
// Create a cloud assembly source with an inline app
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new App();
const stack = new Stack(app, 'SimpleStorageStack');
// Create an S3 bucket in the stack
new s3.Bucket(stack, 'MyFirstBucket', {
versioned: true
});
return app.synth();
});
// Deploy the stack
await toolkit.deploy(cloudAssemblySource);
```
**O que posso fazer agora?**
+ **Automatizar implantações**: acione implantações programaticamente e adicione etapas pré/pós-implantação.
+ **Integrar a sistemas**: conecte-se com fluxos de trabalho de CI/CD, ferramentas personalizadas e soluções de monitoramento.
+ **Controlar os detalhes da implantação**: configure opções refinadas para seleção de pilhas e implantações em vários ambientes.
+ **Aumentar a confiabilidade**: implemente o tratamento de erros pronto para a produção e o acompanhamento do andamento da implantação.
+ **Automatizar a refatoração**: detecte e preserve recursos ao refatorar o código do CDK.
## Próximas etapas
Para começar a usar a Biblioteca do Kit de Ferramentas CDK, consulte [Conceitos básicos da Biblioteca do Kit de Ferramentas CDK](toolkit-library-gs.md).
## Saiba mais
Para saber mais sobre a Biblioteca do Kit de Ferramentas CDK, consulte:
+ Arquivo [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib) no pacote `npm` *@aws-cdk/toolkit-lib*.
+ [Referência de API da Biblioteca do Kit de Ferramentas CDK da AWS](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Conceitos básicos da Biblioteca do Kit de Ferramentas CDK
Comece a usar a Biblioteca do Kit de Ferramentas CDK da AWS para executar programaticamente ações do CDK, como síntese e implantação, em seu código.
## Pré-requisitos
1. Versão com suporte ai Node.js instalada.
1. Credenciais da AWS configuradas.
1. Familiaridade básica com o AWS CDK.
Para obter mais informações, consulte [Pré-requisitos do AWS CDK](prerequisites.md).
## Etapa 1: instalação da Biblioteca do Kit de Ferramentas CDK
Instale o pacote da Biblioteca do Kit de Ferramentas CDK no ambiente de desenvolvimento do seu projeto executando o seguinte:
```
npm install --save @aws-cdk/toolkit-lib
```
## Etapa 2: inicialização da Biblioteca do Kit de Ferramentas CDK
Crie uma instância do Kit de Ferramentas CDK para realizar ações programáticas em sua aplicação do CDK.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit({
// Optional configuration options go here
});
```
É possível personalizar a instância do Kit de Ferramentas CDK durante a criação. Para obter instruções, consulte [Configuração da sua instância do Kit de Ferramentas CDK](toolkit-library-configure.md).
## Etapa 3: criação de uma fonte de conjunto de nuvem para sua aplicação do CDK
Uma fonte de conjunto de nuvem fornece instruções para gerar modelos do CloudFormation a partir da sua aplicação do CDK. É possível criar uma de várias maneiras. Veja a seguir alguns exemplos:
1. **Uma função de compilação de conjunto em linha**:
```
import * as cdk from 'aws-cdk-lib';
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new cdk.App();
new MyStack(app, 'MyStack');
return app.synth();
});
```
1. **Um arquivo de aplicação do CDK existente**:
```
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
```
Para obter mais informações, consulte [Configuração de fontes de conjunto de nuvem](toolkit-library-configure-ca.md).
## Etapa 4: definição de ações programáticas para sua aplicação do CDK
Agora que você criou uma instância do Kit de Ferramentas CDK e uma fonte de conjunto de nuvem, pode começar a definir ações programáticas. Veja a seguir um exemplo básico de como criar uma implantação da pilha `MyStack`:
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH, // Deploy only stacks that exactly match the provided patterns
patterns: ["MyStack"],
},
});
```
## Etapa 5: personalização adicional do Kit de Ferramentas CDK
É possível configurar e personalizar ainda mais o Kit de Ferramentas CDK de acordo com suas necessidades:
+ **Mensagens e interações**: configure como o Kit de Ferramentas CDK se comunica com usuários e aplicações. Consulte [Configuração de mensagens e interações](toolkit-library-configure-messages.md).
+ **Tratamento de erros**: implemente o tratamento estruturado de erros para operações do CDK. Consulte [Configuração do tratamento de erros](toolkit-library-configure.md#toolkit-library-configure-errors).
## Recursos adicionais
Para obter mais informações sobre o pacote `npm` da Biblioteca do Kit de Ferramentas CDK, consulte o arquivo [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib) no pacote `npm` *@aws-cdk/toolkit-lib*.
Para obter informações de referência de API, consulte a [referência de API da Biblioteca do Kit de Ferramentas CDK](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# 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
}
});
```
# Configuração da sua instância do Kit de Ferramentas CDK
Saiba como personalizar sua instância da Biblioteca do Kit de Ferramentas CDK da AWS com opções para tratamento de mensagens, seleção de perfil da AWS e estratégias de seleção de pilha. Este guia explica as opções de configuração disponíveis e como implementá-las de forma eficaz para atender aos requisitos específicos de implantação.
## Configuração do seu perfil da AWS
Quando você usa a Biblioteca do Kit de Ferramentas CDK, ela faz chamadas de API para a AWS usando o SDK. Embora a autenticação seja carregada automaticamente a partir do seu ambiente, é possível especificar explicitamente qual perfil usar:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## Configuração da seleção de pilha
A maioria das ações do Kit de Ferramentas CDK exige que você especifique em quais pilhas operar. A configuração ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` controla essa seleção.
### Seleção de todas as pilhas
Use isso quando quiser operar em todas as pilhas na sua aplicação do CDK:
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### Selecione somente pilhas do conjunto principal
Use isso para selecionar somente as pilhas de nível superior do conjunto principal:
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### Seleção de uma pilha única
Use isso quando seu conjunto contiver exatamente uma pilha e você quiser confirmar essa condição. Se o conjunto incluir uma única pilha, ele retornará essa pilha. Caso contrário, ele lançará uma exceção:
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### Seleção de pilhas por padrão
Use isso para selecionar pilhas específicas por padrão de nome:
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**dica**
Use `PATTERN_MUST_MATCH_SINGLE` para garantir que exatamente uma pilha corresponda aos seus padrões ou `PATTERN_MATCH` se for aceitável que nenhuma pilha corresponda. A correspondência de padrões oferece suporte a curingas como “\$1” para combinar várias pilhas com nomes semelhantes.
## Configuração do tratamento de erros
O Kit de Ferramentas CDK usa erros estruturados para ajudar você a identificar e lidar com problemas. Cada erro inclui:
+ Uma **fonte** indicando a origem do erro (kit de ferramentas ou usuário).
+ Um **tipo de erro** específico (autenticação, validação etc.).
+ Uma **mensagem** descritiva.
### Tratamento de erros
Use os métodos auxiliares fornecidos pelo Kit de Ferramentas CDK para detectar e lidar com tipos de erros específicos:
```
import { ToolkitError } from '@aws-cdk/toolkit-lib';
try {
// Attempt a CDK Toolkit operation
await toolkit.deploy(cloudAssemblySource, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS }
});
} catch (error) {
// Handle specific error types
if (ToolkitError.isAuthenticationError(error)) {
// Example: AWS credentials are missing or invalid
console.error('Authentication failed. Check your AWS credentials.');
} else if (ToolkitError.isAssemblyError(error)) {
// Example: Your CDK app has errors in stack definitions
console.error('CDK app error:', error.message);
} else if (ToolkitError.isDeploymentError(error)) {
// Example: CloudFormation deployment failed
console.error('Deployment failed:', error.message);
} else if (ToolkitError.isToolkitError(error)) {
// Handle all other Toolkit errors
console.error('CDK Toolkit error:', error.message);
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
```
**Importante**
Não confie em verificações de `instanceof` de tipos de erro, pois elas podem se comportar de forma inesperada ao trabalhar com várias cópias do mesmo pacote. Sempre use os métodos auxiliares fornecidos, como `ToolkitError.isAuthenticationError()`.
## Configuração de ações do kit de ferramentas
Cada ação do Kit de Ferramentas CDK (implantar, sintetizar, listar etc.) tem suas próprias opções de configuração específicas. Essas ações permitem que você gerencie o ciclo de vida completo da sua infraestrutura do CDK. Para obter informações detalhadas sobre a configuração de ações individuais, consulte [Configuração de ações programáticas do Kit de Ferramentas CDK](toolkit-library-actions.md).
**dica**
Ao criar fluxos de trabalho de automação, considere combinar várias ações em sequência. Por exemplo, talvez você queira `synth` sua aplicação, `list` as pilhas para verificar o que será implantado e, em seguida, `deploy` a infraestrutura.
# Gerenciamento de fontes de conjuntos de nuvem da Biblioteca do Kit de Ferramentas CDK da AWS
Use a Biblioteca do Kit de Ferramentas CDK da AWS para configurar fontes de conjuntos de nuvem e personalizar a forma como você implanta suas aplicações do CDK. Este guia mostra como configurar fontes de conjuntos de nuvem para atender aos requisitos de implantação e às necessidades de fluxo de trabalho.
Antes de usar o Kit de Ferramentas CDK, especifique uma fonte de conjunto de nuvem. Uma *fonte de conjunto de nuvem* fornece instruções para gerar um conjunto de nuvem a partir da sua aplicação do CDK. O conjunto de nuvem resultante contém os artefatos de infraestrutura sintetizados nos quais o Kit de Ferramentas CDK é implantado na AWS.
A Biblioteca do Kit de Ferramentas CDK oferece várias abordagens para configurar fontes de conjuntos de nuvem, cada uma adequada a diferentes cenários e fluxos de trabalho.
## Seleção de uma fonte de conjunto de nuvem
| Método | Melhor para | Consideração |
| --- | --- | --- |
| `fromCdkApp` | Trabalho com aplicações existente do CDK em qualquer linguagem com suporte. | Requer que o runtime da linguagem apropriada seja instalado. |
| `fromAssemblyBuilder` | Criação de constructos do CDK em linha com controle total sobre o processo de síntese. | Fornece acesso de baixo nível à funcionalidade do CDK e pode ser usado para criar versões personalizadas de outros métodos, como o `fromCdkApp`. |
| `fromAssemblyDirectory` | Uso de conjuntos de nuvem pré-sintetizados. | Execução mais rápida à medida que a etapa de síntese é ignorada. |
| Fonte personalizada | Cenários extremamente especializados que exijam uma implementação personalizada completa. | Requer a implementação da interface `ICloudAssemblySource` a partir do zero; carece de funcionalidades integradas, como pesquisas de contexto; raramente é necessário para a maioria dos casos de uso. |
## Configuração da sua fonte de conjunto de nuvem
### A partir de um aplicação do CDK existente
Use o método `fromCdkApp` para trabalhar com aplicações do CDK escritas em qualquer linguagem com suporte. Essa abordagem é ideal quando você tem uma aplicação do CDK existente e deseja implantá-la programaticamente.
```
import { App } from 'aws-cdk-lib';
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance
const toolkit = new Toolkit();
// TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Deploy a specific stack from the assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: ['MyStack']
});
// Other language examples:
// JavaScript app
// const cloudAssemblySource = await toolkit.fromCdkApp("node app.js");
// Python app
// const cloudAssemblySource = await toolkit.fromCdkApp("python app.py");
// Java app
// const cloudAssemblySource = await toolkit.fromCdkApp("mvn -e -q exec:java -Dexec.mainClass=com.mycompany.app.App");
```
### De um construtor de conjunto em linha
Crie um aplicação do CDK diretamente no seu código usando uma função de construtor de conjuntos. Essa abordagem é útil para implantações simples ou cenários de teste em que você deseja definir sua infraestrutura em linha.
```
import { App, Stack, RemovalPolicy, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Toolkit } from '@aws-cdk/toolkit-lib';
import { Construct } from 'constructs';
// Create a cloud assembly source from an inline CDK app
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new App();
// Define a simple stack with an S3 bucket
class MyStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Create an S3 bucket
new Bucket(this, 'MyBucket', {
versioned: true,
removalPolicy: RemovalPolicy.DESTROY,
autoDeleteObjects: true
});
}
}
// Instantiate the stack
new MyStack(app, 'MyInlineStack');
return app.synth();
});
// Deploy using the cloud assembly source
await toolkit.deploy(cloudAssemblySource, {
stacks: ['MyInlineStack']
});
```
### De um diretório de conjunto existente
Caso você já tenha um conjunto de nuvem sintetizado, será possível usá-lo diretamente. Isso é útil quando você já executa `cdk synth` ou trabalha com conjuntos de nuvem gerados por pipelines de CI/CD.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance
const toolkit = new Toolkit();
// Use an existing cloud assembly directory
const cloudAssemblySource = await toolkit.fromAssemblyDirectory("cdk.out");
// Deploy using the cloud assembly source
await toolkit.deploy(cloudAssemblySource, {
stacks: ['MyStack']
});
```
## Trabalho com conjuntos de nuvem armazenados em cache
Ao trabalhar com conjuntos de nuvem, você tem duas opções:
1. Usar uma fonte de conjunto de nuvem diretamente (simples, mas pode ser mais lento):
```
// Each operation triggers a new synthesis
await toolkit.deploy(cloudAssemblySource, { /* options */ });
await toolkit.list(cloudAssemblySource, { /* options */ });
```
1. Armazenar em cache o conjunto da nuvem (mais rápido para várias operações):
```
// Synthesize once and reuse
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Multiple operations use the same assembly
await toolkit.deploy(cloudAssembly, { /* options */ });
await toolkit.list(cloudAssembly, { /* options */ });
} finally {
// Clean up when done
await cloudAssembly.dispose();
}
```
Use conjuntos em cache quando:
+ Você está executando várias operações (implantação, lista, comparação etc.).
+ Sua aplicação do CDK não muda com frequência durante as operações.
+ Você quer uma performance mais rápida.
Usar fontes de conjunto de nuvem diretamente quando:
+ Você está executando uma única operação.
+ Sua aplicação do CDK muda com frequência.
+ Você quer um código mais simples e não precisa priorizar a velocidade de operação do Kit de Ferramentas.
**Importante**
A maioria das interações do kit de ferramentas deve usar um conjunto em cache para melhorar a performance. A única ocasião a evitar o armazenamento em cache é quando sua fonte muda com frequência, e a verificação de alterações seria cara.
### Como criar, armazenar em cache e reutilizar conjuntos de nuvem
Depois de criar uma fonte de conjunto de nuvem, será possível gerar um conjunto de nuvem sintetizando-o. Um conjunto de nuvem contém os modelos e ativos do AWS CloudFormation necessários para a implantação.
Recomendamos que você gere um conjunto de nuvem uma vez e o reutilize para várias operações do Kit de Ferramentas. Essa abordagem de armazenamento em cache é mais eficiente do que regenerar o conjunto para cada operação. Considere regenerar o conjunto somente quando sua fonte mudar com frequência.
Veja como criar um conjunto de nuvem armazenado em cache:
```
// Generate a cloud assembly from your source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
```
Será possível então realizar várias ações do Kit de Ferramentas no conjunto de nuvem armazenado em cache, como `list()`, `deploy()` e `diff()`. Ao armazenar em cache os conjuntos de nuvem, as ações subsequentes do Kit de Ferramentas são executadas mais rapidamente, pois a síntese ocorre apenas uma vez. Para obter mais informações, consulte [synth - Geração de conjuntos de nuvem](toolkit-library-actions.md#toolkit-library-actions-synth).
### Descarte de recursos de conjunto de nuvem
Sempre descarte os conjuntos de nuvem ao concluir usá-los para limpar recursos temporários. Recomendamos usar um bloco try/finally para garantir a limpeza adequada, especialmente ao realizar várias operações:
```
// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Use the cloud assembly for multiple operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
```
Veja um exemplo que mostra como criar e descartar um conjunto de nuvem armazenado em cache:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit();
// Create cloud assembly source from a CDK app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Create cloud assembly from source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// List stacks in the assembly
await toolkit.list(cloudAssembly);
// Check for changes
await toolkit.diff(cloudAssembly);
// Deploy if needed
await toolkit.deploy(cloudAssembly);
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
```
### Noções básicas sobre a vida útil dos conjuntos de nuvem
Ao criar um conjunto de nuvem armazenado em cache usando `synth()`, você obtém um tipo especial que serve tanto como um `CloudAssembly` legível quanto como uma `CloudAssemblySource`. Todos os conjuntos de nuvem produzidos a partir desse conjunto armazenado em cache (por exemplo, a partir de operações de lista ou implantação) estão vinculados à vida útil do pai:
+ Somente a chamada dispose() do pai realmente limpa os recursos
+ Os conjuntos de nuvem das operações de lista/implantação são gerenciados por seus pais
+ Deixar de descartar um conjunto de nuvem armazenado em cache é considerado um bug
## Práticas recomendadas para fontes de conjunto de nuvem
Ao trabalhar com fontes de conjuntos de nuvem, considere estas práticas recomendadas:
+ **Escolha o método de fonte correto**: selecione a abordagem que melhor se adapta ao seu fluxo de trabalho e aos seus requisitos.
+ **Armazene conjuntos de nuvem em cache**: gere um conjunto de nuvem uma vez usando `synth()` e reutilize-o para várias operações para evitar sínteses desnecessárias, especialmente para aplicações grandes.
+ **Tratamento de erros**: implemente o tratamento básico de erros para capturar e exibir erros para os usuários. Mantenha o tratamento de erros simples e concentre-se em fornecer mensagens de erro claras.
+ **Compatibilidade de versões**: garanta que sua versão da Biblioteca do Kit de Ferramentas CDK ofereça suporte aos conjuntos de nuvem com os quais você está trabalhando. Se uma Biblioteca de Constructos usada para criar o conjunto de nuvem for mais recente do que a com suporte na sua Biblioteca do Kit de Ferramentas, você receberá um erro.
+ **Variáveis de ambiente**: esteja ciente de que determinadas variáveis de ambiente podem afetar a síntese e a implantação do conjunto de nuvem. Variáveis como `CDK_DEFAULT_ACCOUNT`, `CDK_DEFAULT_REGION`, `CDK_OUTDIR` e `CDK_CONTEXT_JSON` podem substituir os comportamentos padrão. Certifique-se de que elas estejam configuradas adequadamente para seu ambiente de implantação.
O exemplo a seguir demonstra como implementar o tratamento de erros e a limpeza adequada ao reutilizar um conjunto de nuvem para várias operações:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with error handling and proper cleanup
async function deployInfrastructure(): Promise {
let cloudAssembly;
try {
// Generate a cloud assembly once
cloudAssembly = await toolkit.synth(cloudAssemblySource);
// Reuse the same cloud assembly for multiple operations
await toolkit.list(cloudAssembly); // Uses existing assembly
await toolkit.deploy(cloudAssembly); // Uses existing assembly
await toolkit.diff(cloudAssembly); // Uses existing assembly
} catch (error) {
console.error("Failed to deploy:", error);
} finally {
// Always dispose when done
if (cloudAssembly) {
await cloudAssembly.dispose();
}
}
}
// Call the async function
deployInfrastructure().catch(error => {
console.error("Deployment failed:", error);
process.exit(1);
});
```
## Resolução de problemas em potencial
Para resolver problemas em potencial com fontes de conjuntos de nuvem, siga estas etapas:
+ **Instale dependências ausentes**: execute `npm install` para instalar as dependências necessárias para sua aplicação do CDK.
+ **Corrija problemas de caminho**: verifique se os caminhos para aplicações do CDK e diretórios de conjuntos existem e estão acessíveis.
+ **Resolva incompatibilidades de versão**: atualize sua versão da Biblioteca do Kit de Ferramentas CDK para corresponder à versão da sua aplicação do CDK.
+ **Corrija erros de síntese**: revise o código da sua aplicação do CDK em busca de erros de sintaxe ou configurações inválidas.
Quando ocorrerem erros durante as operações do Kit de Ferramentas, mantenha o tratamento de erros simples e concentre-se em fornecer mensagens de erro claras aos usuários. Sempre descarte os conjuntos de nuvem ao concluir seu uso. Veja um exemplo que mostra o tratamento básico de erros com a limpeza adequada:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with simple error handling
try {
// Create the cloud assembly source
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
// Use the cloud assembly
await toolkit.list(cloudAssembly);
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
} finally {
// Clean up resources
await cloudAssembly.dispose();
}
```
# Configuração de mensagens e interações do Kit de Ferramentas CDK
A Biblioteca do Kit de Ferramentas CDK da AWS fornece a interface ` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) ` para personalizar a forma como as mensagens e interações são tratadas durante as operações do CDK, permitindo que você controle a exibição do andamento da implantação, das mensagens de erro e dos avisos do usuário para melhor integração com a experiência do usuário da sua aplicação.
Antes de realizar operações como implantação ou síntese, você precisa entender como o Kit de Ferramentas CDK se comunica com os usuários. A interface `IIoHost` serve como canal de comunicação entre o Kit de Ferramentas CDK e sua aplicação, gerenciando tanto as mensagens enviadas quanto as respostas recebidas do usuário.
Quando o Kit de Ferramentas CDK executa operações, ele se comunica por meio de dois mecanismos principais:
+ **Mensagens**: saídas informativas que notificam você sobre o andamento da operação (como “Iniciando a implantação” ou “Recurso criado”).
+ **Solicitações**: pontos de decisão que exigem entrada ou confirmação (como “Deseja implantar essas alterações?”) , dando a você a oportunidade de fornecer informações que, de antemão, não eram necessárias.
## Uso da interface `IIoHost`
A interface `IIoHost` consiste em dois métodos principais:
1. `notify`: trata mensagens informativas unidirecionais.
1. `requestResponse`: trata de solicitações interativas que exijam uma resposta.
```
import { IoMessage, IoRequest } from '@aws-cdk/toolkit-lib';
interface IIoHost {
// Handle informational messages
notify(message: IoMessage): Promise;
// Handle requests that need responses
requestResponse(request: IoRequest): Promise;
}
```
## Níveis de mensagens e tipos de solicitação
O Kit de Ferramentas CDK gera vários tipos de mensagens e solicitações:
### Níveis de mensagens
+ **Depuração**: mensagens detalhadas para solução de problemas.
+ **Erro**: mensagens de erro que podem afetar a operação.
+ **Informações**: mensagens informativas gerais.
+ **Resultado**: mensagem principal de uma operação.
+ **Rastreamento**: informações muito detalhadas do fluxo de execução.
+ **Aviso**: mensagens de aviso que não impedem a operação.
Para obter uma lista completa, consulte [Registro de IoMessages](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) na *Referência de API da Biblioteca do Kit de Ferramentas CDK da AWS*.
### Tipos de solicitação
O Kit de Ferramentas CDK envia solicitações quando precisa de informações ou confirmação do usuário. Essas são mensagens especiais que permitem uma resposta. Se nenhuma resposta for fornecida, o Kit de Ferramentas usará uma resposta padrão quando disponível.
## Implementação básica do `IIoHost`
Aqui está um exemplo simples de implementação de um host de e/s personalizado:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit with custom message handling
const toolkit = new Toolkit({
ioHost: {
// Implementing the IIoHost interface
// Handle informational messages
notify: async function (msg) {
// Example: Handle different message levels appropriately
switch (msg.level) {
case 'error':
console.error(`[${msg.time}] ERROR: ${msg.message}`);
break;
case 'warning':
console.warn(`[${msg.time}] WARNING: ${msg.message}`);
break;
case 'info':
console.info(`[${msg.time}] INFO: ${msg.message}`);
break;
case 'debug':
console.debug(`[${msg.time}] DEBUG: ${msg.message}`);
break;
case 'trace':
console.debug(`[${msg.time}] TRACE: ${msg.message}`);
break;
default:
console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
}
},
// Handle requests that need responses
requestResponse: async function (msg) {
// Example: Log the request and use default response
console.log(`Request: ${msg.message}, using default: ${msg.defaultResponse}`);
return msg.defaultResponse;
// Or implement custom logic to provide responses
// if (msg.type === 'deploy') {
// return promptUserForDeployment(msg);
// }
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
O Kit de Ferramentas CDK aguarda a conclusão de cada chamada, permitindo que você execute operações assíncronas, como solicitações de HTTP ou solicitações do usuário, ao lidar com mensagens.
## Comportamento padrão do `IIoHost`
Se você não fornecer um host ide e/s personalizado, a Biblioteca do Kit de Ferramentas CDK usa uma implementação padrão não interativa:
+ Saída do console para mensagens (usando cores apropriadas para diferentes tipos de mensagens).
+ Totalmente não interativa, sem solicitações de entrada do usuário.
+ Usa automaticamente as respostas padrão sempre que possível (equivalente a responder “sim” às solicitações).
+ Falha quando a entrada é necessária, mas nenhuma resposta padrão está disponível.
Esse comportamento padrão é adequado para operações autônomas, mas não para aplicações de linha de comando interativas. Para aplicações de linha de comando que exijam interação do usuário, você precisará implementar um host de e/s personalizado. Implementações personalizadas também são úteis para integração com sistemas de log, interfaces de usuário ou outros ambientes especializados.
## Implementação avançada de host de e/s
Para cenários mais complexos, recomendamos estender a aula `NonInteractiveIoHost` como ponto de partida. Essa abordagem permite que você aproveite a implementação não interativa existente e, ao mesmo tempo, personalize somente os comportamentos específicos que você precisa alterar.
Veja abaixo um exemplo de host de e/s personalizado que estende a implementação básica:
```
import { NonInteractiveIoHost } from '@aws-cdk/toolkit-lib';
class MyCustomIoHost extends NonInteractiveIoHost {
// Override only the methods you need to customize
// Example: Custom implementation for notify
public async notify(msg: IoMessage): Promise {
// Add custom notification handling logic
if (msg.level === 'error') {
console.error(`ERROR: ${msg.message}`);
// Optionally log to a service or notify a monitoring system
await this.logToMonitoringService(msg);
} else {
await super.notify(msg);
}
}
// Example: Custom implementation for requestResponse
public async requestResponse(request: IoRequest): Promise {
// Implement custom request handling
console.log(`Received request: ${request.message}`);
return request.defaultResponse;
}
private async logToMonitoringService(msg: IoMessage): Promise {
// Implementation for monitoring service integration
console.log(`Logging to monitoring service: ${msg.level} - ${msg.message}`);
}
}
```
Essa abordagem é mais fácil de manter do que implementar toda a interface `IIoHost` do zero, pois você só precisa substituir os métodos específicos que exijam comportamento personalizado.
## Integração com diferentes ambientes
### Integração com aplicações da Web
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example for integrating with a web application
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Send message to frontend via WebSocket
webSocketServer.send(JSON.stringify({
type: 'cdk-notification',
messageLevel: msg.level,
message: msg.message,
time: msg.time
}));
},
requestResponse: async function (msg) {
// Create a promise that will be resolved when the user responds
return new Promise((resolve) => {
const requestId = generateUniqueId();
// Store the resolver function
pendingRequests[requestId] = resolve;
// Send request to frontend
webSocketServer.send(JSON.stringify({
type: 'cdk-request',
requestId: requestId,
requestType: msg.type,
message: msg.message,
defaultResponse: msg.defaultResponse
}));
// Frontend would call an API endpoint with the response,
// which would then call pendingRequests[requestId](response)
});
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
### Integração de ambientes de CI/CD
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example for CI/CD environments (non-interactive)
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Log all messages with appropriate level
switch (msg.level) {
case 'error':
console.error(msg.message);
break;
case 'warning':
console.warn(msg.message);
break;
default:
console.log(msg.message);
}
},
requestResponse: async function (msg) {
// In CI/CD, always use default responses or predefined answers
console.log(`Auto-responding to request: ${msg.message} with ${msg.defaultResponse}`);
return msg.defaultResponse;
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
## Práticas recomendadas para implementação de host de e/s
Ao implementar um host de e/s personalizado, considere estas práticas recomendadas:
+ **Tratamento de erros**: implemente um tratamento robusto de erros em seus métodos de host de e/s para evitar que falhas afetem as operações do CDK.
+ **Tempos limite**: considere a implementação de tempos limite para interações do usuário para evitar esperas indefinidas.
+ **Logs**: armazene mensagens importantes em logs para solução de problemas, especialmente em ambientes não interativos.
+ **Respostas padrão**: forneça respostas padrão sensatas para ambientes automatizados em que a interação do usuário não seja possível.
+ **Indicação de andamento**: para operações de longa duração, forneça indicadores de andamento claros para melhorar a experiência do usuário.
O exemplo a seguir demonstra essas melhores práticas implementando um host de e/s personalizado com tratamento de erros, tempos limite para interações do usuário e logs adequados. Essa implementação é adequada para aplicações interativas em que você precise equilibrar a capacidade de resposta do usuário com uma operação confiável:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with error handling and timeouts
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
try {
console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
// Additional logging or UI updates
} catch (error) {
// Ensure errors in notification handling don't break the CDK operation
console.error("Error handling notification:", error);
}
},
requestResponse: async function (msg) {
try {
// Implement timeout for user response
const response = await Promise.race([
getUserResponse(msg),
new Promise(resolve => setTimeout(() => resolve(msg.defaultResponse), 60000))
]);
return response;
} catch (error) {
console.error("Error handling request:", error);
return msg.defaultResponse;
}
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
## Solução de problemas
Considerações ao implementar um host de e/s personalizado:
+ **Rejeições de promessas não tratadas**: garanta que todas as operações assíncronas sejam tratadas adequadamente com blocos try/catch.
+ **Espera infinita**: implemente tempos limite para todas as interações do usuário para evitar que a aplicação seja interrompida.
+ **Níveis de mensagens ausentes**: esteja preparado para lidar com novos níveis de mensagens que possam ser adicionados em futuras versões do CDK.
+ **Respostas inconsistentes**: garanta que sua implementação de requestResponse retorne valores no formato esperado.
O exemplo a seguir demonstra uma abordagem robusta para lidar com níveis de mensagem, incluindo o tratamento elegante de tipos de mensagens desconhecidos que podem ser introduzidos em futuras versões do CDK. Essa implementação garante que seu host de e/s permaneça compatível com as atualizações do CDK, mantendo os logs adequados:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example of handling unknown message levels
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Handle known levels
const knownLevels = ['info', 'warning', 'error', 'debug', 'trace', 'status'];
if (knownLevels.includes(msg.level)) {
// Handle known level
handleKnownMessageLevel(msg);
} else {
// Handle unknown level as info
console.log(`Unknown message level "${msg.level}": ${msg.message}`);
}
},
requestResponse: async function (msg) {
// Default implementation
return msg.defaultResponse;
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
# Exemplos avançados da Biblioteca do Kit de Ferramentas CDK
Aprenda a usar os recursos avançados da Biblioteca do Kit de Ferramentas CDK da AWS por meio de exemplos práticos. Este guia fornece exemplos de código detalhados para tratamento de erros, monitoramento de implantação e gerenciamento de conjunto de nuvem que se baseiam nos conceitos básicos abordados em outras seções.
## Recursos de integração
O exemplo a seguir demonstra como combinar fontes de conjunto de nuvem, implementação personalizada de host io e opções de implantação:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
async function deployApplication(appPath, environment, options = {}) {
// Create toolkit with custom message handling
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
// Add environment to all messages
console.log(`[${environment}][${msg.time}] ${msg.level}: ${msg.message}`);
},
requestResponse: async (msg) => {
// In production environments, use default responses
if (environment === 'production') {
console.log(`Auto-approving for production: ${msg.message}`);
return msg.defaultResponse;
}
// For other environments, implement custom approval logic
return promptForApproval(msg);
}
} as IIoHost
});
try {
// Create cloud assembly source from the CDK app
console.log(`Creating cloud assembly source from ${appPath}`);
const cloudAssemblySource = await toolkit.fromCdkApp(appPath);
// Synthesize the cloud assembly
console.log(`Synthesizing cloud assembly`);
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy with environment-specific options
console.log(`Deploying to ${environment} environment`);
return await toolkit.deploy(cloudAssembly, {
stacks: options.stacks || { strategy: StackSelectionStrategy.ALL_STACKS },
parameters: options.parameters || {},
tags: {
Environment: environment,
DeployedBy: 'CDK-Toolkit-Library',
DeployTime: new Date().toISOString()
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
console.error(`Deployment to ${environment} failed:`, error);
throw error;
}
}
// Example usage
await deployApplication('ts-node app.ts', 'staging', {
parameters: {
MyStack: {
InstanceType: 't3.small'
}
}
});
```
## Rastreamento do andamento da implantação
Acompanhe o andamento da implantação com atualizações de status detalhadas:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
// Create a progress tracker
class DeploymentTracker {
private startTime: Date;
private resources = new Map();
constructor() {
this.startTime = new Date();
}
onStackEvent(stackName: string, event: string, timestamp: string) {
// Calculate elapsed time if needed, or use the provided timestamp
const elapsed = (new Date().getTime() - this.startTime.getTime()) / 1000;
console.log(`[${timestamp}] (${elapsed.toFixed(1)}s elapsed) Stack ${stackName}: ${event}`);
}
onResourceEvent(resourceId: string, status: string) {
this.resources.set(resourceId, status);
this.printProgress();
}
private printProgress() {
console.log('\nResource Status:');
for (const [id, status] of this.resources.entries()) {
console.log(`- ${id}: ${status}`);
}
console.log();
}
}
// Use the tracker with the toolkit
const tracker = new DeploymentTracker();
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
if (msg.code.startsWith('CDK_DEPLOY')) {
// Track deployment events
if (msg.data && 'stackName' in msg.data) {
tracker.onStackEvent(msg.data.stackName, msg.message, msg.time);
}
} else if (msg.code.startsWith('CDK_RESOURCE')) {
// Track resource events
if (msg.data && 'resourceId' in msg.data) {
tracker.onResourceEvent(msg.data.resourceId, msg.message);
}
}
}
} as IIoHost
});
// Example usage with progress tracking
async function deployWithTracking(cloudAssemblySource: any) {
try {
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy using the cloud assembly
await toolkit.deploy(cloudAssembly, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
throw error;
}
}
```
## Tratamento de erros com recuperação
Implemente um tratamento robusto de erros com estratégias de recuperação:
```
import { Toolkit, ToolkitError, StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
async function deployWithRetry(toolkit: Toolkit, cloudAssemblySource: any) {
try {
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy using the cloud assembly
await toolkit.deploy(cloudAssembly, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Simply show the error to the user
console.error("Operation failed:", error.message);
throw error;
}
}
// Example usage
try {
await deployWithRetry(toolkit, cloudAssemblySource);
} catch (error) {
console.error("Operation failed:", error.message);
process.exit(1);
}
```
## Integração com pipelines de CI/CD
Integração da Biblioteca do Kit de Ferramentas CDK a um pipeline de CI/CD:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
import * as fs from 'fs';
import * as path from 'path';
async function cicdDeploy() {
// Create a non-interactive toolkit for CI/CD environments
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
// Write to both console and log file
const logMessage = `${msg.time} [${msg.level}] ${msg.message}`;
console.log(logMessage);
// Append to deployment log file
fs.appendFileSync('deployment.log', logMessage + '\n');
},
requestResponse: async (msg) => {
// Always use default responses in CI/CD
console.log(`Auto-responding to: ${msg.message} with: ${msg.defaultResponse}`);
return msg.defaultResponse;
}
} as IIoHost
});
// Determine environment from CI/CD variables
const environment = process.env.DEPLOYMENT_ENV || 'development';
// Load environment-specific parameters
const paramsPath = path.join(process.cwd(), `params.${environment}.json`);
const parameters = fs.existsSync(paramsPath)
? JSON.parse(fs.readFileSync(paramsPath, 'utf8'))
: {};
try {
// Use pre-synthesized cloud assembly from build step
const cloudAssemblySource = await toolkit.fromAssemblyDirectory('cdk.out');
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy with CI/CD specific options
const result = await toolkit.deploy(cloudAssembly, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
parameters,
tags: {
Environment: environment,
BuildId: process.env.BUILD_ID || 'unknown',
CommitHash: process.env.COMMIT_HASH || 'unknown'
}
});
// Write outputs to a file for subsequent pipeline steps
fs.writeFileSync(
'stack-outputs.json',
JSON.stringify(result.outputs, null, 2)
);
return result;
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
process.exit(1);
}
}
// Run the CI/CD deployment
cicdDeploy().then(() => {
console.log('CI/CD deployment completed successfully');
});
```
## Recursos adicionais
Para obter informações mais detalhadas sobre componentes específicos usados nesses exemplos, consulte:
+ [Gerenciamento de fontes de conjunto de nuvem](toolkit-library-configure-ca.md): saiba como criar e gerenciar fontes de conjunto de nuvem.
+ [Configuração de mensagens e interações](toolkit-library-configure-messages.md): guia detalhado sobre como personalizar a interface do `IIoHost`.