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á.
# 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();
}
```