Esta es la guía para desarrolladores de AWS CDK v2. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Administración de las AWS fuentes de ensamblaje en la nube de CDK Toolkit Library

Utilice la biblioteca del kit de herramientas de AWS CDK para configurar las fuentes de ensamblaje en la nube y personalizar la forma de implementar las aplicaciones de CDK. Esta guía le muestra cómo configurar las fuentes de ensamblaje en la nube para satisfacer sus requisitos de implementación y sus necesidades de flujo de trabajo.

Antes de usar el kit de herramientas CDK, especifique una fuente de ensamblaje en la nube. Una fuente de ensamblaje en la nube proporciona instrucciones para generar un ensamblaje en la nube a partir de su aplicación de CDK. El ensamblaje de nube resultante contiene los artefactos de infraestructura sintetizados en los que se implementa el kit de herramientas del CDK. AWS

La biblioteca del kit de herramientas CDK ofrece varios enfoques para configurar las fuentes de ensamblaje en la nube, cada uno adecuado para diferentes escenarios y flujos de trabajo.

Selección de una fuente de ensamblaje en la nube

Configurar su fuente de ensamblaje en la nube

Desde una aplicación de CDK existente

Utilice el fromCdkApp método para trabajar con aplicaciones de CDK escritas en cualquier idioma compatible. Este enfoque es ideal cuando tiene una aplicación de CDK existente y desea implementarla mediante programación.

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 un generador de ensamblajes en línea

Cree una aplicación CDK directamente en su código mediante una función de creación de ensamblajes. Este enfoque es útil para implementaciones sencillas o escenarios de prueba en los que desee definir su infraestructura en línea.

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']
});

Desde un directorio de ensamblaje existente

Si ya tiene un ensamblaje de nube sintetizado, puede usarlo directamente. Esto resulta útil cuando ya se está ejecutando cdk synth o cuando se trabaja con ensamblados en la nube generados por canalizaciones 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']
});

Trabajar con ensamblajes en la nube almacenados en caché

Al trabajar con ensamblajes en la nube, tiene dos opciones:

Utilice los ensamblados en caché cuando:

Utilice directamente las fuentes de ensamblaje en la nube cuando:

Cómo crear, almacenar en caché y reutilizar conjuntos en la nube

Tras crear una fuente de ensamblaje de nube, puede generar un ensamblaje de nube sintetizándolo. Un ensamblaje de nube contiene las AWS CloudFormation plantillas y los activos necesarios para la implementación.

Le recomendamos que genere un ensamblaje en la nube una vez y lo reutilice para varias operaciones del kit de herramientas. Este enfoque de almacenamiento en caché es más eficiente que regenerar el ensamblaje para cada operación. Considere la posibilidad de regenerar el ensamblaje solo cuando la fuente cambie con frecuencia.

A continuación, se explica cómo crear un ensamblaje en la nube en caché:

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

A continuación, puede realizar varias acciones del kit de herramientas en el ensamblaje de nube almacenado en caché, comolist(), ydeploy(). diff() Al almacenar en caché los conjuntos de nubes, las siguientes acciones del Toolkit se realizan más rápido, ya que la síntesis se produce solo una vez. Para obtener más información, consulte synth: Generar ensamblajes en la nube.

Elimine los recursos de ensamblaje en la nube

Deseche siempre los ensamblajes en la nube cuando termine de usarlos para limpiar los recursos temporales. Recomendamos utilizar un bloque de prueba/final para garantizar una limpieza adecuada, especialmente cuando se realizan varias operaciones:

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

A continuación, se muestra un ejemplo que muestra cómo crear y eliminar un ensamblaje en la nube almacenado en caché:

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

Comprenda la vida útil de un ensamblaje en la nube

Cuando crea un ensamblaje de nube en caché utilizandosynth(), obtiene un tipo especial que sirve tanto de legible como CloudAssembly de. CloudAssemblySource Todos los ensamblajes de nube generados a partir de este ensamblaje en caché (por ejemplo, a partir de operaciones de lista o despliegue) están vinculados a la vida útil del conjunto principal:

Mejores prácticas para las fuentes de ensamblaje en la nube

Cuando trabaje con fuentes de ensamblaje en la nube, tenga en cuenta estas prácticas recomendadas:

El siguiente ejemplo demuestra cómo implementar la gestión de errores y la limpieza adecuada al reutilizar un ensamblaje en la nube para varias operaciones:

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

Resolver posibles problemas

Siga estos pasos para resolver posibles problemas con las fuentes de ensamblaje en la nube:

Cuando se produzcan errores durante las operaciones del kit de herramientas, simplifique la gestión de los errores y concéntrese en proporcionar mensajes de error claros a los usuarios. Deseche siempre los ensamblados en la nube cuando haya terminado de usarlos. Este es un ejemplo que muestra el manejo básico de errores con una limpieza adecuada:

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