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à.
# Esegui azioni programmatiche utilizzando la libreria CDK Toolkit
## Comprendere la libreria CDK Toolkit
La CDK Toolkit Library consente di eseguire azioni CDK a livello di codice a livello di codice anziché utilizzare i comandi CLI. Puoi utilizzare questa libreria per creare strumenti personalizzati, creare applicazioni CLI specializzate e integrare le funzionalità CDK nei flussi di lavoro di sviluppo.
**Gestisci il ciclo di vita dell'infrastruttura con il controllo programmatico**
La CDK Toolkit Library fornisce interfacce programmatiche per le seguenti azioni CDK:
+ **Sintesi**: genera AWS CloudFormation modelli e artefatti di distribuzione.
+ **Distribuzione**: fornisce o aggiorna l'infrastruttura utilizzando CloudFormation modelli.
+ **Refactor**: preserva le risorse distribuite durante il refactoring del codice CDK, ad esempio rinominando i costrutti o spostandoli tra gli stack.
+ **Elenco: visualizza** le informazioni sugli stack e sulle loro dipendenze.
+ **Guarda**: monitora le app CDK per rilevare eventuali modifiche locali.
+ **Rollback: riporta** gli stack al loro ultimo stato stabile.
+ **Distruggi**: rimuove gli stack CDK e le risorse associate.
**Migliora e personalizza la gestione dell'infrastruttura**
+ **Controllo tramite codice**: integra la gestione dell'infrastruttura direttamente nelle applicazioni e crea pipeline di implementazione reattive.
+ **Gestisci gli assembly cloud**: crea, ispeziona e trasforma le definizioni dell'infrastruttura prima dell'implementazione.
+ **Personalizza le implementazioni**: configura i parametri, il comportamento di rollback e il monitoraggio in base alle tue esigenze.
+ **Conserva le risorse durante il refactoring**: rileva e preserva automaticamente le risorse quando esegui il refactoring del codice CDK.
+ **Gestisci gli errori con precisione**: implementa la gestione strutturata degli errori con informazioni diagnostiche dettagliate.
+ **Comunicazioni personalizzate**: configura indicatori di avanzamento personalizzati e registrazione delle implementazioni. `IoHost`
+ **Connect with AWS **: configura profili, regioni e flussi di autenticazione a livello di codice.
## Scelta del momento in cui utilizzare la CDK Toolkit Library
La CDK Toolkit Library è particolarmente utile quando è necessario:
+ Automatizza le implementazioni dell'infrastruttura come parte delle pipeline. CI/CD
+ Crea strumenti di distribuzione personalizzati in base alle esigenze della tua organizzazione.
+ Integra le azioni CDK nelle applicazioni o nelle piattaforme esistenti.
+ Crea flussi di lavoro di implementazione specializzati con fasi di convalida o approvazione personalizzate.
+ Implementa modelli avanzati di gestione dell'infrastruttura in più ambienti.
+ Automatizza le operazioni di refactoring per preservare le risorse quando esegui il refactoring del codice CDK.
## Utilizzo della CDK Toolkit Library
L'esempio seguente mostra come creare e distribuire un semplice bucket S3 utilizzando la CDK Toolkit Library:
```
// Import required packages
import { Toolkit } from '@aws-cdk/toolkit-lib';
import { App, Stack } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
// Create and configure the CDK Toolkit
const toolkit = new Toolkit();
// Create a cloud assembly source with an inline app
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new App();
const stack = new Stack(app, 'SimpleStorageStack');
// Create an S3 bucket in the stack
new s3.Bucket(stack, 'MyFirstBucket', {
versioned: true
});
return app.synth();
});
// Deploy the stack
await toolkit.deploy(cloudAssemblySource);
```
**Cosa puoi fare dopo**
+ **Automatizza le distribuzioni: attiva le distribuzioni** in modo programmatico e aggiungi passaggi di implementazione. pre/post
+ **Integrazione con i sistemi** - Connettiti con CI/CD flussi di lavoro, strumenti personalizzati e soluzioni di monitoraggio.
+ **Controlla i dettagli dell'implementazione**: configura opzioni dettagliate per la selezione degli stack e le implementazioni multiambiente.
+ **Migliora l'affidabilità**: implementa la gestione degli errori pronta per la produzione e il monitoraggio dei progressi di implementazione.
+ **Automatizza il refactoring**: rileva e preserva le risorse quando esegui il refactoring del codice CDK.
## Passaggi successivi
[Per iniziare a utilizzare la CDK Toolkit Library, consulta Guida introduttiva alla CDK Toolkit Library.](toolkit-library-gs.md)
## Ulteriori informazioni
Per ulteriori informazioni sulla CDK Toolkit Library, consulta quanto segue:
+ [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)nel pacchetto *@aws -cdk/toolkit-lib*`npm`.
+ [AWS Riferimento all'API CDK Toolkit Library](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Guida introduttiva alla libreria CDK Toolkit
Inizia a utilizzare la AWS CDK Toolkit Library per eseguire in modo programmatico azioni CDK, come la sintesi e la distribuzione, nel tuo codice.
## Prerequisiti
1. Versione supportata di Node.js installata.
1. AWS credenziali configurate.
1. Familiarità di base con il CDK. AWS
Per ulteriori informazioni, consulta Prerequisiti [AWS CDK](prerequisites.md).
## Fase 1: Installazione della libreria CDK Toolkit
Installa il pacchetto CDK Toolkit Library nell'ambiente di sviluppo del tuo progetto eseguendo quanto segue:
```
npm install --save @aws-cdk/toolkit-lib
```
## Fase 2: Inizializzazione della libreria CDK Toolkit
Crea un'istanza CDK Toolkit per eseguire azioni programmatiche sulla tua app CDK.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit({
// Optional configuration options go here
});
```
È possibile personalizzare l'istanza CDK Toolkit durante la creazione. Per istruzioni, consulta [Configurazione dell'istanza CDK Toolkit](toolkit-library-configure.md).
## Fase 3: Creazione di una fonte di assemblaggio cloud per l'app CDK
Una fonte di assemblaggio cloud fornisce istruzioni per generare CloudFormation modelli dall'app CDK. Puoi crearne uno in diversi modi. Di seguito sono riportati alcuni esempi:
1. **Una funzione di creazione di assemblaggi in linea:**
```
import * as cdk from 'aws-cdk-lib';
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new cdk.App();
new MyStack(app, 'MyStack');
return app.synth();
});
```
1. **Un file dell'app CDK esistente**:
```
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
```
Per ulteriori informazioni, consulta [Configurare le fonti di assemblaggio cloud](toolkit-library-configure-ca.md).
## Fase 4: Definizione delle azioni programmatiche per l'app CDK
Ora che avete creato un'istanza di CDK Toolkit e una fonte di assemblaggio cloud, potete iniziare a definire le azioni programmatiche. Di seguito è riportato un esempio di base che crea una distribuzione dello stack: `MyStack`
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH, // Deploy only stacks that exactly match the provided patterns
patterns: ["MyStack"],
},
});
```
## Fase 5: Personalizzazione ulteriore del CDK Toolkit
È possibile configurare e personalizzare ulteriormente il CDK Toolkit in base alle proprie esigenze:
+ **Messaggi e interazioni**: configura il modo in cui CDK Toolkit comunica con utenti e applicazioni. Vedi [Configurare messaggi](toolkit-library-configure-messages.md) e interazioni.
+ **Gestione degli errori**: implementa la gestione strutturata degli errori per le operazioni CDK. Vedi [Configurare la gestione degli errori](toolkit-library-configure.md#toolkit-library-configure-errors).
## Risorse aggiuntive
Per ulteriori informazioni sul pacchetto CDK Toolkit Library, consultate il `npm` pacchetto *@aws [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)`npm`-cdk/toolkit-lib*.
[Per informazioni di riferimento sulle API, consultate il riferimento all'API CDK Toolkit Library.](https://docs.aws.amazon.com/cdk/api/toolkit-lib/)
# Configurazione delle azioni programmatiche di CDK Toolkit
La AWS CDK Toolkit Library fornisce interfacce programmatiche per le azioni del ciclo di vita delle applicazioni come la sintesi, l'implementazione e la gestione dello stack. Questa guida spiega come utilizzare ogni azione del codice.
## Generazione di assemblaggi cloud con synth
L'`synth`azione genera un assemblaggio cloud dalla fonte dell'assemblaggio cloud. Per ulteriori informazioni sulla sintesi, consulta [Configurare ed eseguire la sintesi dello stack CDK](configure-synth.md). Un assemblaggio cloud contiene i seguenti elementi di distribuzione dall'app CDK:
+ AWS CloudFormation modelli che definiscono la tua infrastruttura.
+ Risorse come il codice della funzione Lambda o le immagini Docker.
+ Metadati e configurazione di distribuzione.
Ecco come utilizzare l'`synth`azione per creare un assembly cloud:
```
// Create a toolkit instance
const toolkit = new Toolkit();
// Create a cloud assembly source from a TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
// Use the cloud assembly for operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
await toolkit.diff(cloudAssembly);
// Query information from the cloud assembly
const template = cloudAssembly.getStack("my-stack").template;
```
**Suggerimento**
L'utilizzo di un assemblaggio cloud può ottimizzare le prestazioni quando è necessario eseguire più operazioni, poiché la sintesi avviene una sola volta. Per ulteriori informazioni sulla gestione degli assembly cloud, inclusi la memorizzazione nella cache e lo smaltimento, consulta [Creare e gestire](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache) gli assembly cloud.
## Visualizzazione delle informazioni sullo stack con elenco
L'`list`azione recupera le informazioni sugli stack nell'applicazione CDK, comprese le loro dipendenze e lo stato attuale. Utilizzate questa azione per ispezionare l'infrastruttura prima dell'implementazione o per generare report.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Get information about specific stacks
const stackDetails = await toolkit.list(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["my-stack"], // Only include stacks matching this pattern
}
});
// Process the returned stack information
for (const stack of stackDetails) {
console.log(`Stack: ${stack.id}, Dependencies: ${stack.dependencies}`);
}
```
## Fornitura dell'infrastruttura con distribuzione
L'`deploy`azione prevede o aggiorna l'infrastruttura AWS utilizzando l'assemblaggio cloud prodotto durante la sintesi. Per un'introduzione alla distribuzione, consulta [Distribuire le applicazioni AWS CDK.](deploy.md) È possibile controllare le opzioni di distribuzione come la selezione dello stack, i valori dei parametri e il comportamento di rollback.
```
// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
parameters: StackParameters.exactly({
"MyStack": {
"BucketName": "amzn-s3-demo-bucket"
}
})
});
```
L'azione deploy supporta diversi metodi di distribuzione per adattarsi a vari flussi di lavoro. Per la maggior parte degli scenari, specialmente negli ambienti di produzione, consigliamo di utilizzare il metodo di distribuzione predefinito che utilizza set di CloudFormation modifiche. Per gli ambienti di sviluppo in cui la velocità di iterazione è importante, è possibile utilizzare metodi alternativi come l'hotswap.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Deploy using default deployment method (recommended for production)
await toolkit.deploy(cloudAssemblySource, {
parameters: StackParameters.exactly({
"MyStack": {
"BucketName": "amzn-s3-demo-bucket"
}
})
});
// For development environments only: Deploy with hotswap for faster iterations
// Note: We recommend using default deployment methods for production environments
await toolkit.deploy(cloudAssemblySource, {
deploymentMethod: { method: "hotswap", fallback: true }, // Faster but introduces drift
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["dev-stack"]
}
});
```
## Conservazione delle risorse distribuite con refactor
**Importante**
L'azione di refactor è in versione di anteprima ed è soggetta a modifiche.
L'`refactor`azione preserva le risorse distribuite quando si esegue il refactoring del codice CDK, ad esempio rinominando i costrutti o spostandoli tra gli stack. Senza questa funzionalità, queste modifiche CloudFormation comporterebbero la sostituzione delle risorse, con conseguenti potenziali interruzioni del servizio o perdita di dati.
L'azione di refactor calcola automaticamente le mappature confrontando il codice corrente con lo stato distribuito. Verifica che l'applicazione CDK contenga esattamente lo stesso set di risorse dello stato distribuito, che differiscono solo nella loro posizione nell'albero di costruzione. Se rileva aggiunte, eliminazioni o modifiche alle risorse, l'operazione di refactoring verrà rifiutata con un messaggio di errore.
Una volta calcolate le mappature, l'azione di refactoring utilizza l'API di refactoring per aggiornare la logica CloudFormation delle risorse senza sostituirle. IDs Se rileva mappature ambigue (laddove esistono più mappature possibili), puoi fornire sostituzioni esplicite per risolvere queste ambiguità.
```
// Perform refactoring operation to preserve resources
await toolkit.refactor(cloudAssemblySource);
// With optional overrides to resolve ambiguities
await toolkit.refactor(cloudAssemblySource, {
overrides: {
"environments": [
{
"account": "123456789012",
"region": "us-east-2",
"resources": {
"StackA.OldName": "StackA.NewName"
}
}
]
}
});
```
**Importante**
Le operazioni di refactoring devono essere eseguite separatamente dalle altre azioni, come l'aggiunta di nuove risorse, l'eliminazione di risorse o la modifica delle proprietà delle risorse. Se è necessario apportare tali modifiche, è necessario innanzitutto distribuirle separatamente e quindi utilizzare il refactoring per riorganizzare le risorse.
**Suggerimento**
Per ulteriori informazioni sul refactoring CDK, incluso come funziona e quando utilizzarlo, consulta [Preservare](refactor.md) le risorse distribuite durante il refactoring del codice CDK.
## Ripristino delle distribuzioni non riuscite con il rollback
L'`rollback`azione riporta uno stack all'ultimo stato stabile quando una distribuzione fallisce e non può essere annullata automaticamente. Utilizzare questa azione per eseguire il ripristino da installazioni non riuscite che richiedono un intervento manuale.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Roll back stacks to their last stable state
await toolkit.rollback(cloudAssemblySource, {
orphanFailedResources: false, // When true, removes failed resources from CloudFormation management
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["failed-stack"]
}
});
```
## Monitoraggio delle modifiche con watch
L'`watch`azione monitora continuamente l'app CDK per rilevare eventuali modifiche ai file locali ed esegue automaticamente distribuzioni o hotswap. Questo crea un file watcher che funziona fino alla chiusura o alla chiusura del codice.
**avvertimento**
Le implementazioni Hotswap aggiornano le risorse direttamente senza interruzioni CloudFormation quando possibile, velocizzando gli aggiornamenti durante lo sviluppo. Questa opzione è abilitata per impostazione predefinita per il comando. `watch` Se da un lato ciò accelera il ciclo di sviluppo, dall'altro introduce un divario tra i CloudFormation modelli e le risorse distribuite. Pertanto, si consiglia di non utilizzare gli hotswap negli ambienti di produzione.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Start watching for changes
const watcher = await toolkit.watch(cloudAssemblySource, {
include: ["lib/**/*.ts"], // Only watch TypeScript files in the lib directory
exclude: ["**/*.test.ts"], // Ignore test files
deploymentMethod: { method: "hotswap" }, // This is the default, shown here for clarity
stacks: {
strategy: StackSelectionStrategy.ALL // Watch all stacks
}
});
// Later in your code, you can explicitly stop watching:
// await watcher.dispose();
```
La funzione watch restituisce un `IWatcher` oggetto che consente di controllare in modo esplicito quando smettere di guardare. Chiamate il `dispose()` metodo su questo oggetto quando volete terminare il processo di controllo.
## Rimuovere l'infrastruttura con destroy
L'`destroy`azione rimuove gli stack CDK e le risorse associate da. AWS Utilizzate questa azione per ripulire le risorse quando non sono più necessarie.
**Importante**
L'azione destroy rimuove definitivamente le risorse senza richiedere conferma, a differenza della versione CLI di questo comando. Assicurati di avere dei backup di tutti i dati importanti prima di distruggere gli stack.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Remove specific stacks and their resources
await toolkit.destroy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["dev-stack"], // Only destroy stacks matching this pattern
}
});
```
# Configurazione dell'istanza CDK Toolkit
Scopri come personalizzare l'istanza della libreria AWS CDK Toolkit con opzioni per la gestione dei messaggi, la selezione del AWS profilo e le strategie di selezione dello stack. Questa guida spiega le opzioni di configurazione disponibili e come implementarle in modo efficace per soddisfare i requisiti di implementazione specifici.
## Configurazione del profilo AWS
Quando utilizzi la CDK Toolkit Library, effettua chiamate API per AWS utilizzare l'SDK. Sebbene l'autenticazione venga caricata automaticamente dal tuo ambiente, puoi specificare esplicitamente quale profilo utilizzare:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## Configurazione della selezione dello stack
La maggior parte delle azioni di CDK Toolkit richiede di specificare su quali stack operare. La ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` configurazione controlla questa selezione.
### Seleziona tutte le pile
Usalo quando vuoi operare su ogni stack della tua app CDK:
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### Seleziona solo le pile di assemblaggio principali
Utilizzate questa opzione per selezionare solo le pile di primo livello dall'assieme principale:
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### Selezionate una singola pila
Utilizzatelo quando l'assieme contiene esattamente una pila e desiderate affermare questa condizione. Se l'assieme include una singola pila, restituisce quella pila. Altrimenti, genera un'eccezione:
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### Seleziona le pile per modello
Utilizzatelo per selezionare pile specifiche in base al modello di nome:
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**Suggerimento**
Utilizzalo `PATTERN_MUST_MATCH_SINGLE` per assicurarti che una pila corrisponda esattamente ai tuoi modelli, o `PATTERN_MATCH` se è accettabile che nessuna pila corrisponda. Il pattern matching supporta caratteri jolly come «\$1» per abbinare più pile con nomi simili.
## Configurazione della gestione degli errori
Il CDK Toolkit utilizza errori strutturati per aiutarvi a identificare e gestire i problemi. Ogni errore include:
+ Una **fonte** che indica l'origine dell'errore (toolkit o utente).
+ Un **tipo di errore** specifico (autenticazione, convalida, ecc.).
+ **Un messaggio descrittivo.**
### Gestione degli errori
Utilizzate i metodi di supporto forniti da CDK Toolkit per rilevare e gestire tipi di errore specifici:
```
import { ToolkitError } from '@aws-cdk/toolkit-lib';
try {
// Attempt a CDK Toolkit operation
await toolkit.deploy(cloudAssemblySource, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS }
});
} catch (error) {
// Handle specific error types
if (ToolkitError.isAuthenticationError(error)) {
// Example: AWS credentials are missing or invalid
console.error('Authentication failed. Check your AWS credentials.');
} else if (ToolkitError.isAssemblyError(error)) {
// Example: Your CDK app has errors in stack definitions
console.error('CDK app error:', error.message);
} else if (ToolkitError.isDeploymentError(error)) {
// Example: CloudFormation deployment failed
console.error('Deployment failed:', error.message);
} else if (ToolkitError.isToolkitError(error)) {
// Handle all other Toolkit errors
console.error('CDK Toolkit error:', error.message);
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
```
**Importante**
Non affidatevi ai `instanceof` controlli dei tipi di errore, poiché possono comportarsi in modo imprevisto quando si lavora con più copie dello stesso pacchetto. Usa sempre i metodi di supporto forniti come. `ToolkitError.isAuthenticationError()`
## Configurazione delle azioni del Toolkit
Ogni azione di CDK Toolkit (deploy, synth, list, ecc.) ha le sue opzioni di configurazione specifiche. Queste azioni consentono di gestire l'intero ciclo di vita dell'infrastruttura CDK. Per informazioni dettagliate sulla configurazione delle singole azioni, consulta [Configurare le azioni programmatiche di CDK](toolkit-library-actions.md) Toolkit.
**Suggerimento**
Nei flussi di lavoro di automazione degli edifici, prendi in considerazione la possibilità di combinare più azioni in sequenza. Ad esempio, potresti voler verificare `synth` la tua app, `list` gli stack per verificare cosa verrà distribuito e quindi `deploy` l'infrastruttura.
# 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
| 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
### 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:
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
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
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 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
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 {
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:
+ **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();
}
```
# Configurazione dei messaggi e delle interazioni di CDK Toolkit
La AWS CDK Toolkit Library fornisce l'` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) `interfaccia per personalizzare il modo in cui i messaggi e le interazioni vengono gestiti durante le operazioni CDK, consentendovi di controllare la visualizzazione dello stato di avanzamento della distribuzione, dei messaggi di errore e delle istruzioni utente per una migliore integrazione con l'esperienza utente dell'applicazione.
Prima di eseguire operazioni come l'implementazione o la sintesi, è necessario comprendere come CDK Toolkit comunica con gli utenti. L'`IIoHost`interfaccia funge da canale di comunicazione tra CDK Toolkit e l'applicazione, gestendo sia i messaggi in uscita che le risposte degli utenti in entrata.
Quando CDK Toolkit esegue le operazioni, comunica attraverso due meccanismi principali:
+ **Messaggi**: output informativi che informano l'utente sullo stato di avanzamento dell'operazione (come «Avvio della distribuzione» o «Creazione di risorse»).
+ **Richieste**: punti decisionali che richiedono l'immissione o la conferma (ad esempio «Vuoi implementare queste modifiche?») , offrendoti l'opportunità di fornire informazioni che prima non erano ritenute necessarie.
## Utilizzo dell'interfaccia `IIoHost`
L'`IIoHost`interfaccia è costituita da due metodi principali:
1. `notify`: gestisce i messaggi informativi unidirezionali.
1. `requestResponse`: gestisce le richieste interattive che richiedono una risposta.
```
import { IoMessage, IoRequest } from '@aws-cdk/toolkit-lib';
interface IIoHost {
// Handle informational messages
notify(message: IoMessage): Promise;
// Handle requests that need responses
requestResponse(request: IoRequest): Promise;
}
```
## Livelli di messaggi e tipi di richieste
Il CDK Toolkit genera diversi tipi di messaggi e richieste:
### Livelli di messaggio
+ **Debug**: messaggi dettagliati per la risoluzione dei problemi.
+ **Errore**: messaggi di errore che possono influire sul funzionamento.
+ **Informazioni**: messaggi informativi generali.
+ **Risultato**: messaggio principale di un'operazione.
+ **Trace**: informazioni molto dettagliate sul flusso di esecuzione.
+ **Avviso**: messaggi di avviso che non impediscono il funzionamento.
Per un elenco completo, consultate [IoMessages Registry](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) nel riferimento all'*API AWS CDK Toolkit Library*.
### Tipi di richieste
CDK Toolkit invia richieste quando necessita di input o conferma da parte dell'utente. Si tratta di messaggi speciali che consentono una risposta. Se non viene fornita alcuna risposta, il Toolkit utilizzerà una risposta predefinita quando disponibile.
## implementazione di base `IIoHost`
Ecco un semplice esempio di implementazione di un host io personalizzato:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit with custom message handling
const toolkit = new Toolkit({
ioHost: {
// Implementing the IIoHost interface
// Handle informational messages
notify: async function (msg) {
// Example: Handle different message levels appropriately
switch (msg.level) {
case 'error':
console.error(`[${msg.time}] ERROR: ${msg.message}`);
break;
case 'warning':
console.warn(`[${msg.time}] WARNING: ${msg.message}`);
break;
case 'info':
console.info(`[${msg.time}] INFO: ${msg.message}`);
break;
case 'debug':
console.debug(`[${msg.time}] DEBUG: ${msg.message}`);
break;
case 'trace':
console.debug(`[${msg.time}] TRACE: ${msg.message}`);
break;
default:
console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
}
},
// Handle requests that need responses
requestResponse: async function (msg) {
// Example: Log the request and use default response
console.log(`Request: ${msg.message}, using default: ${msg.defaultResponse}`);
return msg.defaultResponse;
// Or implement custom logic to provide responses
// if (msg.type === 'deploy') {
// return promptUserForDeployment(msg);
// }
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
Il CDK Toolkit attende il completamento di ogni chiamata e consente di eseguire operazioni asincrone come richieste HTTP o istruzioni utente durante la gestione dei messaggi.
## Comportamento predefinito `IIoHost`
Se non fornite un host io personalizzato, la CDK Toolkit Library utilizza un'implementazione non interattiva predefinita:
+ Output da console per i messaggi (utilizzando colori appropriati per diversi tipi di messaggi).
+ Completamente non interattivo senza richieste di input da parte dell'utente.
+ Utilizza automaticamente le risposte predefinite laddove possibile (equivalente a rispondere «sì» alle richieste).
+ Fallisce quando è richiesto un input ma non è disponibile una risposta predefinita.
Questo comportamento predefinito è adatto per le operazioni non presidiate, ma non per le applicazioni interattive a riga di comando. Per le applicazioni da riga di comando che richiedono l'interazione dell'utente, è necessario implementare un host io personalizzato. Le implementazioni personalizzate sono utili anche per l'integrazione con sistemi di registrazione o altri ambienti specializzati UIs.
## Implementazione avanzata dell'host io
Per scenari più complessi, consigliamo di estendere la `NonInteractiveIoHost` classe come punto di partenza. Questo approccio consente di sfruttare l'implementazione non interattiva esistente personalizzando solo i comportamenti specifici che è necessario modificare.
Ecco un esempio di un host io personalizzato che estende l'implementazione di base:
```
import { NonInteractiveIoHost } from '@aws-cdk/toolkit-lib';
class MyCustomIoHost extends NonInteractiveIoHost {
// Override only the methods you need to customize
// Example: Custom implementation for notify
public async notify(msg: IoMessage): Promise {
// Add custom notification handling logic
if (msg.level === 'error') {
console.error(`ERROR: ${msg.message}`);
// Optionally log to a service or notify a monitoring system
await this.logToMonitoringService(msg);
} else {
await super.notify(msg);
}
}
// Example: Custom implementation for requestResponse
public async requestResponse(request: IoRequest): Promise {
// Implement custom request handling
console.log(`Received request: ${request.message}`);
return request.defaultResponse;
}
private async logToMonitoringService(msg: IoMessage): Promise {
// Implementation for monitoring service integration
console.log(`Logging to monitoring service: ${msg.level} - ${msg.message}`);
}
}
```
Questo approccio è più gestibile rispetto all'implementazione dell'intera `IIoHost` interfaccia da zero, poiché è sufficiente sovrascrivere i metodi specifici che richiedono un comportamento personalizzato.
## Integrazione con ambienti diversi
### Integrazione di applicazioni Web
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example for integrating with a web application
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Send message to frontend via WebSocket
webSocketServer.send(JSON.stringify({
type: 'cdk-notification',
messageLevel: msg.level,
message: msg.message,
time: msg.time
}));
},
requestResponse: async function (msg) {
// Create a promise that will be resolved when the user responds
return new Promise((resolve) => {
const requestId = generateUniqueId();
// Store the resolver function
pendingRequests[requestId] = resolve;
// Send request to frontend
webSocketServer.send(JSON.stringify({
type: 'cdk-request',
requestId: requestId,
requestType: msg.type,
message: msg.message,
defaultResponse: msg.defaultResponse
}));
// Frontend would call an API endpoint with the response,
// which would then call pendingRequests[requestId](response)
});
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
### Integrazione dell'ambiente CI/CD
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example for CI/CD environments (non-interactive)
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Log all messages with appropriate level
switch (msg.level) {
case 'error':
console.error(msg.message);
break;
case 'warning':
console.warn(msg.message);
break;
default:
console.log(msg.message);
}
},
requestResponse: async function (msg) {
// In CI/CD, always use default responses or predefined answers
console.log(`Auto-responding to request: ${msg.message} with ${msg.defaultResponse}`);
return msg.defaultResponse;
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
## Le migliori pratiche per l'implementazione di io host
Quando implementi un host io personalizzato, prendi in considerazione queste best practice:
+ **Gestione degli errori**: implementate una solida gestione degli errori nei metodi degli host io per evitare che gli errori influiscano sulle operazioni CDK.
+ **Timeout**: prendete in considerazione l'implementazione di timeout per le interazioni con gli utenti per evitare attese indefinite.
+ **Registrazione**: archivia i messaggi importanti nei registri per la risoluzione dei problemi, specialmente in ambienti non interattivi.
+ **Risposte predefinite: fornisce risposte** predefinite ragionevoli per ambienti automatizzati in cui l'interazione dell'utente non è possibile.
+ **Indicazione dello stato di avanzamento**: per le operazioni di lunga durata, fornisci indicatori di avanzamento chiari per migliorare l'esperienza dell'utente.
L'esempio seguente dimostra queste best practice implementando un host io personalizzato con gestione degli errori, timeout per le interazioni con gli utenti e registrazione corretta. Questa implementazione è adatta per applicazioni interattive in cui è necessario bilanciare la reattività dell'utente con un funzionamento affidabile:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with error handling and timeouts
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
try {
console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
// Additional logging or UI updates
} catch (error) {
// Ensure errors in notification handling don't break the CDK operation
console.error("Error handling notification:", error);
}
},
requestResponse: async function (msg) {
try {
// Implement timeout for user response
const response = await Promise.race([
getUserResponse(msg),
new Promise(resolve => setTimeout(() => resolve(msg.defaultResponse), 60000))
]);
return response;
} catch (error) {
console.error("Error handling request:", error);
return msg.defaultResponse;
}
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
## Risoluzione dei problemi
Considerazioni sull'implementazione di un host io personalizzato:
+ **Rifiuti di promesse non gestiti**: assicurati che tutte le operazioni asincrone siano gestite correttamente con i blocchi try/catch.
+ **Attesa infinita**: implementa i timeout per tutte le interazioni degli utenti per evitare che l'applicazione si blocchi.
+ **Livelli di messaggio mancanti**: preparatevi a gestire nuovi livelli di messaggio che potrebbero essere aggiunti nelle future versioni di CDK.
+ **Risposte incoerenti**: assicurati che l'implementazione di RequestResponse restituisca valori nel formato previsto.
L'esempio seguente dimostra un approccio robusto alla gestione dei livelli di messaggio, inclusa la gestione corretta di tipi di messaggi sconosciuti che potrebbero essere introdotti nelle future versioni di CDK. Questa implementazione garantisce che il tuo host io rimanga compatibile con gli aggiornamenti CDK mantenendo una registrazione corretta:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example of handling unknown message levels
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Handle known levels
const knownLevels = ['info', 'warning', 'error', 'debug', 'trace', 'status'];
if (knownLevels.includes(msg.level)) {
// Handle known level
handleKnownMessageLevel(msg);
} else {
// Handle unknown level as info
console.log(`Unknown message level "${msg.level}": ${msg.message}`);
}
},
requestResponse: async function (msg) {
// Default implementation
return msg.defaultResponse;
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
# Esempi di librerie CDK Toolkit avanzate
Scopri come utilizzare le funzionalità avanzate della AWS CDK Toolkit Library attraverso esempi pratici. Questa guida fornisce esempi di codice dettagliati per la gestione degli errori, il monitoraggio della distribuzione e la gestione degli assemblaggi nel cloud che si basano sui concetti di base trattati in altre sezioni.
## Funzionalità di integrazione
L'esempio seguente dimostra come combinare sorgenti di assemblaggio cloud, implementazione di host IO personalizzati e opzioni di distribuzione:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
async function deployApplication(appPath, environment, options = {}) {
// Create toolkit with custom message handling
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
// Add environment to all messages
console.log(`[${environment}][${msg.time}] ${msg.level}: ${msg.message}`);
},
requestResponse: async (msg) => {
// In production environments, use default responses
if (environment === 'production') {
console.log(`Auto-approving for production: ${msg.message}`);
return msg.defaultResponse;
}
// For other environments, implement custom approval logic
return promptForApproval(msg);
}
} as IIoHost
});
try {
// Create cloud assembly source from the CDK app
console.log(`Creating cloud assembly source from ${appPath}`);
const cloudAssemblySource = await toolkit.fromCdkApp(appPath);
// Synthesize the cloud assembly
console.log(`Synthesizing cloud assembly`);
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy with environment-specific options
console.log(`Deploying to ${environment} environment`);
return await toolkit.deploy(cloudAssembly, {
stacks: options.stacks || { strategy: StackSelectionStrategy.ALL_STACKS },
parameters: options.parameters || {},
tags: {
Environment: environment,
DeployedBy: 'CDK-Toolkit-Library',
DeployTime: new Date().toISOString()
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
console.error(`Deployment to ${environment} failed:`, error);
throw error;
}
}
// Example usage
await deployApplication('ts-node app.ts', 'staging', {
parameters: {
MyStack: {
InstanceType: 't3.small'
}
}
});
```
## Monitoraggio dei progressi della distribuzione
Tieni traccia dell'avanzamento dell'implementazione con aggiornamenti di stato dettagliati:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
// Create a progress tracker
class DeploymentTracker {
private startTime: Date;
private resources = new Map();
constructor() {
this.startTime = new Date();
}
onStackEvent(stackName: string, event: string, timestamp: string) {
// Calculate elapsed time if needed, or use the provided timestamp
const elapsed = (new Date().getTime() - this.startTime.getTime()) / 1000;
console.log(`[${timestamp}] (${elapsed.toFixed(1)}s elapsed) Stack ${stackName}: ${event}`);
}
onResourceEvent(resourceId: string, status: string) {
this.resources.set(resourceId, status);
this.printProgress();
}
private printProgress() {
console.log('\nResource Status:');
for (const [id, status] of this.resources.entries()) {
console.log(`- ${id}: ${status}`);
}
console.log();
}
}
// Use the tracker with the toolkit
const tracker = new DeploymentTracker();
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
if (msg.code.startsWith('CDK_DEPLOY')) {
// Track deployment events
if (msg.data && 'stackName' in msg.data) {
tracker.onStackEvent(msg.data.stackName, msg.message, msg.time);
}
} else if (msg.code.startsWith('CDK_RESOURCE')) {
// Track resource events
if (msg.data && 'resourceId' in msg.data) {
tracker.onResourceEvent(msg.data.resourceId, msg.message);
}
}
}
} as IIoHost
});
// Example usage with progress tracking
async function deployWithTracking(cloudAssemblySource: any) {
try {
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy using the cloud assembly
await toolkit.deploy(cloudAssembly, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
throw error;
}
}
```
## Gestione degli errori con ripristino
Implementa una solida gestione degli errori con strategie di ripristino:
```
import { Toolkit, ToolkitError, StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
async function deployWithRetry(toolkit: Toolkit, cloudAssemblySource: any) {
try {
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy using the cloud assembly
await toolkit.deploy(cloudAssembly, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Simply show the error to the user
console.error("Operation failed:", error.message);
throw error;
}
}
// Example usage
try {
await deployWithRetry(toolkit, cloudAssemblySource);
} catch (error) {
console.error("Operation failed:", error.message);
process.exit(1);
}
```
## Integrazione con pipeline CI/CD
Integra la CDK Toolkit Library in una pipeline CI/CD:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
import * as fs from 'fs';
import * as path from 'path';
async function cicdDeploy() {
// Create a non-interactive toolkit for CI/CD environments
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
// Write to both console and log file
const logMessage = `${msg.time} [${msg.level}] ${msg.message}`;
console.log(logMessage);
// Append to deployment log file
fs.appendFileSync('deployment.log', logMessage + '\n');
},
requestResponse: async (msg) => {
// Always use default responses in CI/CD
console.log(`Auto-responding to: ${msg.message} with: ${msg.defaultResponse}`);
return msg.defaultResponse;
}
} as IIoHost
});
// Determine environment from CI/CD variables
const environment = process.env.DEPLOYMENT_ENV || 'development';
// Load environment-specific parameters
const paramsPath = path.join(process.cwd(), `params.${environment}.json`);
const parameters = fs.existsSync(paramsPath)
? JSON.parse(fs.readFileSync(paramsPath, 'utf8'))
: {};
try {
// Use pre-synthesized cloud assembly from build step
const cloudAssemblySource = await toolkit.fromAssemblyDirectory('cdk.out');
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy with CI/CD specific options
const result = await toolkit.deploy(cloudAssembly, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
parameters,
tags: {
Environment: environment,
BuildId: process.env.BUILD_ID || 'unknown',
CommitHash: process.env.COMMIT_HASH || 'unknown'
}
});
// Write outputs to a file for subsequent pipeline steps
fs.writeFileSync(
'stack-outputs.json',
JSON.stringify(result.outputs, null, 2)
);
return result;
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
process.exit(1);
}
}
// Run the CI/CD deployment
cicdDeploy().then(() => {
console.log('CI/CD deployment completed successfully');
});
```
## Risorse aggiuntive
Per informazioni più dettagliate sui componenti specifici utilizzati in questi esempi, fate riferimento a:
+ [Gestione delle fonti di assemblaggio cloud](toolkit-library-configure-ca.md): scopri come creare e gestire le fonti di assemblaggio cloud.
+ [Configurazione di messaggi e interazioni](toolkit-library-configure-messages.md) - Guida dettagliata sulla personalizzazione dell'`IIoHost`interfaccia.