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á.

Gerenciando fontes de montagem em nuvem da AWS CDK Toolkit Library

Use a AWS CDK Toolkit Library para configurar fontes de montagem em nuvem e personalizar a forma como você implanta seus aplicativos CDK. Este guia mostra como configurar fontes de montagem em nuvem para atender aos requisitos de implantação e às necessidades de fluxo de trabalho.

Antes de usar o CDK Toolkit, especifique uma fonte de montagem em nuvem. Uma fonte de montagem em nuvem fornece instruções para gerar uma montagem em nuvem a partir do seu aplicativo CDK. O conjunto de nuvem resultante contém os artefatos de infraestrutura sintetizados nos quais o CDK Toolkit é implantado. AWS

A CDK Toolkit Library oferece várias abordagens para configurar fontes de montagem em nuvem, cada uma adequada para diferentes cenários e fluxos de trabalho.

Seleção de uma fonte de montagem em nuvem

Configurando sua fonte de montagem em nuvem

De um aplicativo CDK existente

Use o fromCdkApp método para trabalhar com aplicativos CDK escritos em qualquer linguagem compatível. Essa abordagem é ideal quando você tem um aplicativo CDK existente e deseja implantá-lo 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 montagem em linha

Crie um aplicativo CDK diretamente no seu código usando uma função de construtor de montagens. 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 montagem existente

Se você já tem uma montagem de nuvem sintetizada, pode usá-la diretamente. Isso é útil quando você já executa cdk synth ou trabalha com assemblies em 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']
});

Trabalhando com assemblies de nuvem em cache

Ao trabalhar com montagens em nuvem, você tem duas opções:

Use montagens em cache quando:

Use fontes de montagem em nuvem diretamente quando:

Como criar, armazenar em cache e reutilizar assemblies de nuvem

Depois de criar uma fonte de montagem em nuvem, você pode gerar uma montagem em nuvem sintetizando-a. Um conjunto de nuvem contém os AWS CloudFormation modelos e ativos necessários para a implantação.

Recomendamos que você gere uma montagem em nuvem uma vez e a reutilize para várias operações do Toolkit. Essa abordagem de armazenamento em cache é mais eficiente do que regenerar a montagem para cada operação. Considere regenerar a montagem somente quando sua fonte mudar com frequência.

Veja como criar um conjunto de nuvem em cache:

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

Em seguida, você pode realizar várias ações do Toolkit no conjunto de nuvem em cache, como list()deploy(), e. diff() Ao armazenar em cache os conjuntos de nuvem, as ações subsequentes do Toolkit são executadas mais rapidamente, pois a síntese ocorre apenas uma vez. Para obter mais informações, consulte synth - Gere assemblies em nuvem.

Elimine os recursos de montagem da nuvem

Sempre descarte os conjuntos de nuvem quando terminar de 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();
}

Aqui está um exemplo que mostra como criar e descartar um conjunto de nuvem 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();
}

Entendendo a vida útil da montagem em nuvem

Ao criar um conjunto de nuvem em cache usandosynth(), você obtém um tipo especial que serve tanto como legível CloudAssembly quanto como. CloudAssemblySource Todos os conjuntos de nuvem produzidos a partir desse conjunto em cache (por exemplo, a partir de operações de lista ou implantação) estão vinculados à vida útil do pai:

Melhores práticas para fontes de montagem em nuvem

Ao trabalhar com fontes de montagem em nuvem, considere estas melhores práticas:

O exemplo a seguir demonstra como implementar o tratamento de erros e a limpeza adequada ao reutilizar uma montagem em 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);
});

Resolvendo possíveis problemas

Siga estas etapas para resolver possíveis problemas com fontes de montagem em nuvem:

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 quando terminar de usá-los. Aqui está 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();
}