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
<a name="toolkit-library-configure-ca"></a>

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
<a name="toolkit-library-configure-ca-options"></a>


| Metodo | Ideale per | Considerazione | 
| --- | --- | --- | 
|  `fromCdkApp`  | Utilizzo delle applicazioni CDK esistenti in qualsiasi lingua supportata. | Richiede l'installazione del linguaggio di esecuzione appropriato. | 
|  `fromAssemblyBuilder`  | Creazione di costrutti CDK in linea con il pieno controllo del processo di sintesi. | Fornisce un accesso di basso livello alla funzionalità CDK e può essere utilizzato per creare versioni personalizzate di altri metodi come. `fromCdkApp` | 
|  `fromAssemblyDirectory`  | Utilizzo di assemblaggi cloud presintetizzati. | Esecuzione più rapida in quanto la fase di sintesi viene saltata. | 
| Fonte personalizzata | Scenari estremamente specializzati che richiedono un'implementazione personalizzata completa. | Richiede l'implementazione dell'`ICloudAssemblySource`interfaccia da zero; manca di funzionalità integrate come la ricerca contestuale; raramente è necessaria per la maggior parte dei casi d'uso. | 

## Configurazione della fonte di assemblaggio cloud
<a name="toolkit-library-configure-ca-how"></a>

### Da un'app CDK esistente
<a name="toolkit-library-configure-ca-how-app"></a>

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
<a name="toolkit-library-configure-ca-how-builder"></a>

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
<a name="toolkit-library-configure-ca-how-directory"></a>

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
<a name="toolkit-library-configure-ca-cache"></a>

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

1. Utilizza direttamente una fonte di assemblaggio cloud (semplice ma potrebbe essere più lenta):

   ```
   // Each operation triggers a new synthesis
   await toolkit.deploy(cloudAssemblySource, { /* options */ });
   await toolkit.list(cloudAssemblySource, { /* options */ });
   ```

1. Memorizza nella cache l'assembly cloud (più veloce per più operazioni):

   ```
   // Synthesize once and reuse
   const cloudAssembly = await toolkit.synth(cloudAssemblySource);
   try {
     // Multiple operations use the same assembly
     await toolkit.deploy(cloudAssembly, { /* options */ });
     await toolkit.list(cloudAssembly, { /* options */ });
   } finally {
     // Clean up when done
     await cloudAssembly.dispose();
   }
   ```

Utilizza gli assembly memorizzati nella cache quando:
+ Stai eseguendo più operazioni (deploy, list, diff, ecc.).
+ La tua app CDK non cambia frequentemente durante le operazioni.
+ Desiderate prestazioni più veloci.

Utilizza direttamente le fonti di assemblaggio cloud quando:
+ Stai eseguendo una singola operazione.
+ La tua app CDK cambia frequentemente.
+ Desideri un codice più semplice e non devi dare priorità alla velocità operativa di Toolkit.

**Importante**  
La maggior parte delle interazioni con Toolkit dovrebbe utilizzare un assembly memorizzato nella cache per prestazioni migliori. L'unico momento per evitare la memorizzazione nella cache è quando la fonte cambia frequentemente e il controllo delle modifiche sarebbe costoso.

### Come creare, memorizzare nella cache e riutilizzare gli assembly cloud
<a name="toolkit-library-configure-ca-cache-how"></a>

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 esempio`list()`, `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](toolkit-library-actions.md#toolkit-library-actions-synth) - Generate cloud assembly.

### Smaltisci le risorse di assemblaggio nel cloud
<a name="toolkit-library-configure-ca-cache-dispose"></a>

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
<a name="toolkit-library-configure-ca-cache-lifetime"></a>

Quando si crea un assembly cloud memorizzato nella cache utilizzando`synth()`, 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:
+ Solo la chiamata dispose () del genitore pulisce effettivamente le risorse
+ Gli assembly cloud delle operazioni list/deploy sono gestiti dai rispettivi componenti principali
+ La mancata eliminazione di un assembly cloud memorizzato nella cache è considerata un bug

## Le migliori pratiche per i sorgenti di assemblaggio su cloud
<a name="toolkit-library-configure-ca-best-practices"></a>

Quando lavori con sorgenti di assemblaggio su cloud, prendi in considerazione queste best practice:
+  **Scegli il metodo di origine giusto**: seleziona l'approccio più adatto al tuo flusso di lavoro e ai tuoi requisiti.
+  **Cache degli assembly cloud**: genera un assembly cloud una volta utilizzato `synth()` e riutilizzalo per più operazioni per evitare sintesi non necessarie, soprattutto per applicazioni di grandi dimensioni.
+  **Gestione degli errori**: implementa la gestione degli errori di base per catturare e visualizzare gli errori agli utenti. Mantieni la gestione degli errori semplice e concentrati sulla fornitura di messaggi di errore chiari.
+  **Compatibilità delle versioni: assicurati che la tua versione** di CDK Toolkit Library sia in grado di supportare gli assembly cloud con cui stai lavorando. Se la Construct Library utilizzata per creare l'assembly cloud è più recente di quella supportata dalla Toolkit Library, riceverai un errore.
+  Variabili di **ambiente: tieni presente che alcune variabili** di ambiente possono influire sulla sintesi e sulla distribuzione degli assemblaggi nel cloud. Variabili come`CDK_DEFAULT_ACCOUNT`, `CDK_DEFAULT_REGION``CDK_OUTDIR`, e `CDK_CONTEXT_JSON` possono sovrascrivere i comportamenti predefiniti. Assicurati che siano impostate in modo appropriato per il tuo ambiente di distribuzione.

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
<a name="toolkit-library-configure-ca-troubleshooting"></a>

Segui questi passaggi per risolvere potenziali problemi con le fonti di assemblaggio cloud:
+  **Installa le dipendenze mancanti**: `npm install` esegui per installare le dipendenze richieste per la tua app CDK.
+  **Risolvi i problemi relativi ai percorsi**: verifica che i percorsi verso le app CDK e le directory di assemblaggio esistano e siano accessibili.
+  **Risolvi le mancate corrispondenze tra le versioni: aggiorna la versione** della CDK Toolkit Library in modo che corrisponda alla versione dell'app CDK.
+  **Correggi gli errori di sintesi**: controlla il codice dell'app CDK per eventuali errori di sintassi o configurazioni non valide.

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