Esta es la segunda versión de la Guía para desarrolladores de AWS CDK. 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.

Administración de las fuentes de ensamblaje en la nube de la biblioteca del kit de herramientas de AWS CDK

Utilice la biblioteca del kit de herramientas de AWS CDK para configurar las fuentes de ensamblaje en la nube y personalizar la manera 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 de 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 de AWS CDK.

La biblioteca del kit de herramientas de 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 método fromCdkApp 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 de forma programática.

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

A partir de un generador de ensamblajes en línea

Cree una aplicación de CDK directamente en su código mediante una función de creación de ensamblajes. Este enfoque es útil para implementaciones sencillas o situaciones 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']
});

A partir de un directorio de ensamblajes existente

Si ya tiene un conjunto de nubes sintetizado, puede usarlo de forma directa. Esto resulta útil cuando cdk synth ya se está ejecutando 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 conjuntos en la nube, cuenta con dos opciones:

Utilice los ensamblajes en caché cuando:

Utilice las fuentes de ensamblaje directamente 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 plantillas y los activos de AWS CloudFormation necesarios para la implementación.

Se recomienda generar un ensamblaje en la nube una vez y reutilizarlo 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 cambia con frecuencia.

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

// 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é, como list(), deploy() y diff(). Al almacenar en caché los conjuntos de nubes, las acciones posteriores del kit de herramientas 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 conjuntos en la nube cuando termine de utilizarlos para limpiar los recursos temporales. Recomendamos utilizar un bloque de prueba/final para garantizar una limpieza adecuada, en especial 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, tenemos un ejemplo que muestra cómo crear y eliminar un conjunto 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();
}

Comprender la vida útil de un ensamblaje en la nube

Cuando crea un ensamblaje de nube en caché utilizando synth(), 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 implementación) están vinculados a la vida útil del conjunto principal:

Prácticas recomendadas para orígenes de conjuntos en la nube

Cuando trabaje con fuentes de ensamblaje en la nube, tenga en cuenta las siguientes 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 problemas potenciales

Siga estos pasos para resolver problemas potenciales con las fuentes de conjuntos 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 a los usuarios mensajes de error claros. Deseche siempre los conjuntos en la nube cuando termine de utilizarlos. A continuación, tenemos un ejemplo que muestra una gestión de errores básica 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();
}