Questa è la AWS CDK v2 Developer Guide. Il vecchio CDK v1 è entrato in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Gestione delle fonti di assemblaggio cloud di AWS CDK Toolkit Library

Utilizza la AWS CDK Toolkit Library per configurare le sorgenti di assemblaggio su cloud e personalizzare il modo in cui distribuisci le tue applicazioni CDK. Questa guida mostra come configurare le sorgenti di assemblaggio cloud per soddisfare i requisiti di distribuzione e le esigenze del flusso di lavoro.

Prima di utilizzare CDK Toolkit, specificate una fonte di assemblaggio cloud. Una fonte di assemblaggio cloud fornisce istruzioni per generare un assemblaggio cloud dall'app CDK. L'assembly cloud risultante contiene gli artefatti dell'infrastruttura sintetizzati su cui viene distribuito il CDK Toolkit. AWS

La CDK Toolkit Library offre diversi approcci per configurare le fonti di assemblaggio su cloud, ciascuno adatto a scenari e flussi di lavoro diversi.

Selezione di una fonte di assemblaggio cloud

Configurazione della fonte di assemblaggio cloud

Da un'app CDK esistente

Usa il fromCdkApp metodo per lavorare con le app CDK scritte in qualsiasi lingua supportata. Questo approccio è ideale quando si dispone di un'applicazione CDK esistente e si desidera distribuirla a livello di codice.

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

Da un costruttore di assemblaggi in linea

Crea un'app CDK direttamente nel tuo codice utilizzando una funzione assembly builder. Questo approccio è utile per semplici implementazioni o scenari di test in cui si desidera definire l'infrastruttura in linea.

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

Da una directory di assembly esistente

Se disponi già di un assembly cloud sintetizzato, puoi utilizzarlo direttamente. Ciò è utile quando lo hai già eseguito cdk synth o quando lavori con assembly cloud generati da pipeline 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']
});

Lavorare con gli assembly cloud memorizzati nella cache

Quando si lavora con gli assembly cloud, sono disponibili due opzioni:

Utilizza gli assembly memorizzati nella cache quando:

Utilizza direttamente le fonti di assemblaggio cloud quando:

Come creare, memorizzare nella cache e riutilizzare gli assembly cloud

Dopo aver creato una fonte di assemblaggio cloud, è possibile generare un assembly cloud sintetizzandolo. Un cloud assembly contiene i AWS CloudFormation modelli e le risorse necessari per la distribuzione.

Ti consigliamo di generare un assembly cloud una sola volta e di riutilizzarlo per più operazioni Toolkit. Questo approccio di memorizzazione nella cache è più efficiente della rigenerazione dell'assieme per ogni operazione. Prendete in considerazione la possibilità di rigenerare l'assieme solo quando la fonte cambia frequentemente.

Ecco come creare un assembly cloud memorizzato nella cache:

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

È quindi possibile eseguire varie azioni Toolkit sull'assembly cloud memorizzato nella cache, ad esempiolist(), deploy() e. diff() Memorizzando nella cache gli assembly cloud, le azioni successive di Toolkit vengono eseguite più rapidamente poiché la sintesi avviene una sola volta. Per ulteriori informazioni, consulta synth - Generate cloud assembly.

Smaltisci le risorse di assemblaggio nel cloud

Smaltisci sempre gli assembly cloud quando hai finito di utilizzarli per ripulire le risorse temporanee. Ti consigliamo di utilizzare un blocco try/finally per garantire una pulizia corretta, specialmente quando si eseguono più operazioni:

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

Ecco un esempio che mostra come creare ed eliminare un assembly cloud memorizzato nella 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();
}

Comprensione della durata degli assemblaggi cloud

Quando si crea un assembly cloud memorizzato nella cache utilizzandosynth(), si ottiene un tipo speciale che funge sia da leggibile CloudAssembly che da. CloudAssemblySource Tutti gli assembly cloud prodotti da questo assembly memorizzato nella cache (ad esempio, da operazioni di elenco o distribuzione) sono legati alla durata di vita del componente principale:

Le migliori pratiche per i sorgenti di assemblaggio su cloud

Quando lavori con sorgenti di assemblaggio su cloud, prendi in considerazione queste best practice:

L'esempio seguente dimostra come implementare la gestione degli errori e la corretta pulizia riutilizzando un assembly cloud per più operazioni:

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

Risoluzione di potenziali problemi

Segui questi passaggi per risolvere potenziali problemi con le fonti di assemblaggio cloud:

Quando si verificano errori durante le operazioni di Toolkit, mantieni la gestione degli errori semplice e concentrati sulla fornitura di messaggi di errore chiari agli utenti. Smaltisci sempre gli assembly cloud quando hai finito di utilizzarli. Ecco un esempio che mostra la gestione di base degli errori con una corretta pulizia:

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