Ceci est le guide du développeur du AWS CDK v2. L'ancien CDK v1 est entré en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Gestion des sources d'assemblage cloud de la bibliothèque AWS CDK Toolkit

Utilisez la bibliothèque du kit d'outils AWS CDK pour configurer les sources d'assemblage dans le cloud et personnaliser la façon dont vous déployez vos applications CDK. Ce guide explique comment configurer les sources d'assemblage dans le cloud pour répondre à vos exigences de déploiement et à vos besoins en matière de flux de travail.

Avant d'utiliser le kit d'outils CDK, spécifiez une source d'assemblage cloud. Une source d'assemblage cloud fournit des instructions pour générer un assemblage cloud à partir de votre application CDK. L'assemblage cloud qui en résulte contient les artefacts d'infrastructure synthétisés sur lesquels le CDK Toolkit est déployé. AWS

La bibliothèque CDK Toolkit propose plusieurs approches pour configurer les sources d'assemblage dans le cloud, chacune adaptée à différents scénarios et flux de travail.

Sélection d'une source d'assemblage dans le cloud

Configuration de votre source d'assemblage dans le cloud

À partir d'une application CDK existante

Utilisez fromCdkApp cette méthode pour travailler avec des applications CDK écrites dans n'importe quelle langue prise en charge. Cette approche est idéale lorsque vous avez une application CDK existante et que vous souhaitez la déployer par programmation.

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

À partir d'un constructeur d'assemblages en ligne

Créez une application CDK directement dans votre code à l'aide d'une fonction de création d'assemblages. Cette approche est utile pour les déploiements simples ou les scénarios de test dans lesquels vous souhaitez définir votre infrastructure en ligne.

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

À partir d'un répertoire d'assemblage existant

Si vous disposez déjà d'un assemblage cloud synthétisé, vous pouvez l'utiliser directement. Cela est utile lorsque vous avez déjà exécuté cdk synth ou lorsque vous travaillez avec des assemblages cloud générés par des pipelines 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']
});

Utilisation d'assemblages cloud mis en cache

Lorsque vous travaillez avec des assemblages cloud, deux options s'offrent à vous :

Utilisez des assemblages mis en cache lorsque :

Utilisez directement les sources d'assemblage dans le cloud lorsque :

Comment créer, mettre en cache et réutiliser des assemblages cloud

Après avoir créé une source d'assemblage cloud, vous pouvez générer un assemblage cloud en le synthétisant. Un assembly cloud contient les AWS CloudFormation modèles et les ressources nécessaires au déploiement.

Nous vous recommandons de générer un assemblage cloud une seule fois et de le réutiliser pour plusieurs opérations du Toolkit. Cette approche de mise en cache est plus efficace que la régénération de l'assemblage pour chaque opération. Pensez à régénérer l'assemblage uniquement lorsque votre source change fréquemment.

Voici comment créer un assemblage cloud mis en cache :

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

Vous pouvez ensuite effectuer diverses actions du Toolkit sur l'assembly cloud mis en cache, telles que list()deploy(), etdiff(). En mettant en cache les assemblages cloud, les actions suivantes du Toolkit sont exécutées plus rapidement, car la synthèse n'a lieu qu'une seule fois. Pour plus d'informations, consultez Synth - Generate cloud assemblies.

Éliminez les ressources d'assemblage dans le cloud

Éliminez toujours les assemblages cloud lorsque vous avez fini de les utiliser pour nettoyer des ressources temporaires. Nous vous recommandons d'utiliser un bloc try/finally pour garantir un nettoyage correct, en particulier lorsque vous effectuez plusieurs opérations :

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

Voici un exemple montrant comment créer et supprimer un assembly cloud mis en 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();
}

Comprendre la durée de vie des assemblages dans le cloud

Lorsque vous créez un assemblage cloud mis en cache à l'aide desynth(), vous obtenez un type spécial qui sert à la fois de lisible CloudAssembly et deCloudAssemblySource. Tous les assemblages cloud produits à partir de cet assemblage mis en cache (par exemple, à partir d'opérations de liste ou de déploiement) sont liés à la durée de vie du parent :

Bonnes pratiques pour les sources d'assemblage dans le cloud

Lorsque vous travaillez avec des sources d'assemblage dans le cloud, tenez compte des meilleures pratiques suivantes :

L'exemple suivant montre comment implémenter la gestion des erreurs et un nettoyage approprié tout en réutilisant un assemblage cloud pour plusieurs opérations :

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

Résoudre les problèmes potentiels

Suivez ces étapes pour résoudre les problèmes potentiels liés aux sources d'assemblage dans le cloud :

Lorsque des erreurs se produisent pendant le fonctionnement du Toolkit, maintenez la gestion des erreurs simple et concentrez-vous sur l'envoi de messages d'erreur clairs aux utilisateurs. Éliminez toujours les assemblages cloud lorsque vous avez fini de les utiliser. Voici un exemple illustrant la gestion de base des erreurs avec un nettoyage approprié :

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