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.

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

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:

Use conjuntos em cache quando:

Usar fontes de conjunto de nuvem diretamente quando:

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.

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:

Práticas recomendadas para fontes de conjunto de nuvem

Ao trabalhar com fontes de conjuntos de nuvem, considere estas práticas recomendadas:

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<void> {
    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:

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();
}