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.
# Réaliser des actions programmatiques à l'aide de la bibliothèque du kit d'outils CDK
## Comprendre la bibliothèque du kit d'outils CDK
La bibliothèque du kit d'outils CDK vous permet d'effectuer des actions CDK par programmation via du code au lieu d'utiliser des commandes CLI. Vous pouvez utiliser cette bibliothèque pour créer des outils personnalisés, créer des applications CLI spécialisées et intégrer les fonctionnalités du CDK dans vos flux de travail de développement.
**Gérez le cycle de vie de votre infrastructure grâce au contrôle programmatique**
La bibliothèque du kit d'outils CDK fournit des interfaces de programmation pour les actions CDK suivantes :
+ **Synthèse** : générez des AWS CloudFormation modèles et des artefacts de déploiement.
+ **Déploiement** : provisionnez ou mettez à jour l'infrastructure à l'aide CloudFormation de modèles.
+ **Refactoriser** - Préservez les ressources déployées lors de la refactorisation du code CDK, par exemple en renommant des constructions ou en les déplaçant entre des piles.
+ **Liste** : permet d'afficher des informations sur les piles et leurs dépendances.
+ **Surveiller** - Surveillez les applications CDK pour détecter les modifications locales.
+ **Annulation : redonne** aux piles leur dernier état stable.
+ **Détruire** : supprimez les piles de CDK et les ressources associées.
**Améliorez et personnalisez la gestion de votre infrastructure**
+ **Contrôle par le code** : intégrez la gestion de l'infrastructure directement dans vos applications et créez des pipelines de déploiement réactifs.
+ **Gérez les assemblages cloud** : créez, inspectez et transformez les définitions de votre infrastructure avant le déploiement.
+ **Personnalisez les déploiements** : configurez les paramètres, le comportement de restauration et la surveillance en fonction de vos besoins.
+ **Préservez les ressources lors de la refactorisation** : détectez et préservez automatiquement les ressources lorsque vous refactorisez le code CDK.
+ **Gérez les erreurs avec précision** : implémentez une gestion structurée des erreurs avec des informations de diagnostic détaillées.
+ **Personnalisez les communications** : configurez des indicateurs de progression personnalisés et enregistrez `IoHost` les mises en œuvre.
+ **Connectez-vous avec AWS ** : configurez les profils, les régions et les flux d'authentification par programmation.
## Choisir quand utiliser la bibliothèque du kit d'outils CDK
La bibliothèque du kit d'outils CDK est particulièrement utile lorsque vous devez :
+ Automatisez les déploiements d'infrastructures dans le cadre de CI/CD pipelines.
+ Créez des outils de déploiement personnalisés adaptés aux besoins de votre organisation.
+ Intégrez les actions du CDK dans les applications ou plateformes existantes.
+ Créez des flux de travail de déploiement spécialisés avec des étapes de validation ou d'approbation personnalisées.
+ Mettez en œuvre des modèles de gestion d'infrastructure avancés dans plusieurs environnements.
+ Automatisez les opérations de refactorisation pour préserver les ressources lorsque vous refactorisez le code CDK.
## Utilisation de la bibliothèque du kit d'outils CDK
L'exemple suivant montre comment créer et déployer un compartiment S3 simple à l'aide de la bibliothèque CDK Toolkit :
```
// 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);
```
**Ce que vous pouvez faire ensuite**
+ **Automatisez les déploiements** : déclenchez les déploiements par programmation et ajoutez des étapes de déploiement. pre/post
+ **Intégration aux systèmes** : connectez-vous aux CI/CD flux de travail, aux outils personnalisés et aux solutions de surveillance.
+ **Contrôlez les détails du déploiement** : configurez des options précises pour la sélection des piles et les déploiements multi-environnements.
+ **Améliorez la fiabilité** : mettez en œuvre une gestion des erreurs adaptée à la production et un suivi de la progression du déploiement.
+ **Automatisez le refactoring** : détectez et préservez les ressources lorsque vous refactorisez le code CDK.
## Étapes suivantes
Pour commencer à utiliser la bibliothèque de boîtes à outils CDK, voir [Commencer à utiliser la bibliothèque de boîtes à outils CDK](toolkit-library-gs.md).
## En savoir plus
Pour en savoir plus sur la bibliothèque du kit d'outils CDK, consultez ce qui suit :
+ [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)dans le package *@aws -cdk/toolkit-lib*`npm`.
+ [AWS Référence de l'API de la bibliothèque CDK Toolkit](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Commencer à utiliser la bibliothèque du kit d'outils CDK
Commencez par utiliser la bibliothèque AWS CDK Toolkit pour exécuter par programmation des actions CDK, telles que la synthèse et le déploiement, dans votre code.
## Prérequis
1. Version prise en charge de Node.js installée.
1. AWS informations d'identification configurées.
1. Connaissance de base du AWS CDK.
Pour plus d'informations, consultez la section [Conditions préalables au AWS CDK](prerequisites.md).
## Étape 1 : Installation de la bibliothèque du kit d'outils CDK
Installez le package CDK Toolkit Library dans l'environnement de développement de votre projet en exécutant ce qui suit :
```
npm install --save @aws-cdk/toolkit-lib
```
## Étape 2 : Initialisation de la bibliothèque du kit d'outils CDK
Créez une instance de CDK Toolkit pour effectuer des actions programmatiques sur votre application CDK.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit({
// Optional configuration options go here
});
```
Vous pouvez personnaliser l'instance du CDK Toolkit lors de sa création. Pour obtenir des instructions, consultez [Configurer votre instance du CDK Toolkit](toolkit-library-configure.md).
## Étape 3 : Création d'une source d'assemblage cloud pour votre application CDK
Une source d'assemblage dans le cloud fournit des instructions pour générer des CloudFormation modèles à partir de votre application CDK. Vous pouvez en créer un de plusieurs manières. Voici quelques exemples :
1. **Une fonction de création d'assemblages en ligne** :
```
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 fichier d'application CDK existant** :
```
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
```
Pour plus d'informations, consultez la section [Configurer les sources d'assemblage dans le cloud](toolkit-library-configure-ca.md).
## Étape 4 : Définition des actions programmatiques pour votre application CDK
Maintenant que vous avez créé une instance CDK Toolkit et une source d'assemblage cloud, vous pouvez commencer à définir des actions programmatiques. Voici un exemple de base qui crée un déploiement de la `MyStack` pile :
```
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"],
},
});
```
## Étape 5 : Personnaliser davantage le kit d'outils CDK
Vous pouvez configurer et personnaliser le kit CDK en fonction de vos besoins :
+ **Messages et interactions** - Configurez la manière dont le kit d'outils CDK communique avec les utilisateurs et les applications. Voir [Configurer les messages et les interactions](toolkit-library-configure-messages.md).
+ **Gestion des erreurs** - Implémentez une gestion structurée des erreurs pour les opérations CDK. Voir [Configuration de la gestion des erreurs](toolkit-library-configure.md#toolkit-library-configure-errors).
## Ressources supplémentaires
Pour plus d'informations sur le package CDK Toolkit Library, consultez le `npm` [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)package *@aws -cdk/toolkit-lib*`npm`.
Pour obtenir des informations de référence sur les API, consultez la [référence de l'API de la bibliothèque CDK Toolkit](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Configuration des actions programmatiques du CDK Toolkit
La bibliothèque AWS CDK Toolkit fournit des interfaces programmatiques pour les actions du cycle de vie des applications telles que la synthèse, le déploiement et la gestion des piles. Ce guide explique comment utiliser chaque action de votre code.
## Génération d'assemblages cloud avec un synthétiseur
L'`synth`action génère un assemblage cloud à partir de votre source d'assemblage cloud. Pour plus d'informations sur la synthèse, voir [Configurer et exécuter la synthèse de piles CDK](configure-synth.md). Un assembly cloud contient les artefacts de déploiement suivants provenant de votre application CDK :
+ AWS CloudFormation des modèles qui définissent votre infrastructure.
+ Des actifs tels que le code de fonction Lambda ou les images Docker.
+ Métadonnées et configuration du déploiement.
Voici comment utiliser l'`synth`action pour créer un assemblage 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;
```
**Astuce**
L'utilisation d'un assemblage cloud peut optimiser les performances lorsque vous devez effectuer plusieurs opérations, car la synthèse n'a lieu qu'une seule fois. Pour plus d'informations sur la gestion des assemblages cloud, y compris la mise en cache et l'élimination, voir [Création et gestion des assemblages cloud](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache).
## Afficher les informations de la pile avec une liste
L'`list`action récupère des informations sur les piles de votre application CDK, notamment leurs dépendances et leur état actuel. Utilisez cette action pour inspecter votre infrastructure avant le déploiement ou pour générer des rapports.
```
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}`);
}
```
## Provisionnement de l'infrastructure avec déploiement
L'`deploy`action provisionne ou met à jour votre infrastructure en AWS utilisant l'assemblage cloud produit lors de la synthèse. Pour une introduction au déploiement, voir [Déployer des applications AWS CDK.](deploy.md) Vous pouvez contrôler les options de déploiement telles que la sélection des piles, les valeurs des paramètres et le comportement de restauration.
```
// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
parameters: StackParameters.exactly({
"MyStack": {
"BucketName": "amzn-s3-demo-bucket"
}
})
});
```
L'action de déploiement prend en charge différentes méthodes de déploiement pour s'adapter à différents flux de travail. Pour la plupart des scénarios, en particulier dans les environnements de production, nous recommandons d'utiliser la méthode de déploiement par défaut qui utilise des ensembles de CloudFormation modifications. Pour les environnements de développement où la vitesse d'itération est importante, vous pouvez utiliser des méthodes alternatives telles que le 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"]
}
});
```
## Préserver les ressources déployées grâce au refactorisation
**Important**
L'action de refactorisation est dans la version préliminaire et est sujette à modification.
L'`refactor`action préserve les ressources déployées lorsque vous refactorisez le code CDK, par exemple en renommant des constructions ou en les déplaçant entre des piles. Sans cette fonctionnalité, ces modifications entraîneraient le remplacement CloudFormation des ressources, ce qui pourrait entraîner des interruptions de service ou des pertes de données.
L'action de refactorisation calcule automatiquement les mappages en comparant votre code actuel à l'état déployé. Il vérifie que votre application CDK contient exactement le même ensemble de ressources que l'état déployé, les différences se limitant à leur emplacement dans l'arbre de construction. S'il détecte des ajouts, des suppressions ou des modifications de ressources, l'opération de refactorisation sera rejetée avec un message d'erreur.
Une fois les mappages calculés, l'action de refactorisation utilise l'API CloudFormation de refactorisation pour mettre à jour la logique IDs des ressources sans les remplacer. S'il rencontre des mappages ambigus (où plusieurs mappages possibles existent), vous pouvez fournir des remplacements explicites pour résoudre ces ambiguïtés.
```
// 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"
}
}
]
}
});
```
**Important**
Les opérations de refactorisation doivent être effectuées séparément des autres actions, telles que l'ajout de nouvelles ressources, la suppression de ressources ou la modification des propriétés des ressources. Si vous devez apporter de telles modifications, vous devez d'abord les déployer séparément, puis utiliser le refactoring pour réorganiser vos ressources.
**Astuce**
Pour plus d'informations sur le refactoring du CDK, notamment sur son fonctionnement et le moment de son utilisation, voir [Préserver les ressources déployées lors de la refactorisation](refactor.md) du code CDK.
## Annuler les déploiements ayant échoué grâce à la restauration
L'`rollback`action ramène une pile à son dernier état stable lorsqu'un déploiement échoue et ne peut pas être automatiquement inversée. Utilisez cette action pour effectuer une restauration après un échec de déploiement nécessitant une intervention manuelle.
```
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"]
}
});
```
## Surveillance des modifications à l'aide d'une montre
L'`watch`action surveille en permanence votre application CDK pour détecter les modifications apportées aux fichiers locaux et effectue automatiquement des déploiements ou des hotswaps. Cela crée un observateur de fichiers qui s'exécute jusqu'à ce que votre code soit terminé ou terminé.
**Avertissement**
Les déploiements Hotswap mettent à jour les ressources directement sans passer par là CloudFormation lorsque cela est possible, ce qui accélère les mises à jour pendant le développement. Ceci est activé par défaut pour la `watch` commande. Bien que cela accélère le cycle de développement, cela introduit un décalage entre vos CloudFormation modèles et les ressources déployées. Par conséquent, nous vous recommandons de ne pas utiliser de hotswap dans les environnements de production.
```
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 fonction watch renvoie un `IWatcher` objet qui vous permet de contrôler explicitement le moment où vous devez arrêter de regarder. Appelez la `dispose()` méthode sur cet objet lorsque vous souhaitez mettre fin au processus de surveillance.
## Suppression de l'infrastructure par destruction
L'`destroy`action supprime les piles de CDK et leurs ressources associées. AWS Utilisez cette action pour nettoyer les ressources lorsqu'elles ne sont plus nécessaires.
**Important**
L'action de destruction supprime définitivement les ressources sans demander de confirmation, contrairement à la version CLI de cette commande. Assurez-vous de disposer de copies de sauvegarde de toutes les données importantes avant de détruire les piles.
```
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
}
});
```
# Configuration de votre instance du CDK Toolkit
Découvrez comment personnaliser votre instance de bibliothèque AWS CDK Toolkit avec des options de gestion des messages, de sélection de AWS profils et de stratégies de sélection de piles. Ce guide explique les options de configuration disponibles et explique comment les mettre en œuvre efficacement pour répondre à vos exigences de déploiement spécifiques.
## Configuration de votre AWS profil
Lorsque vous utilisez la bibliothèque du kit d'outils CDK, elle effectue des appels d'API pour AWS utiliser le SDK. Alors que l'authentification est chargée automatiquement depuis votre environnement, vous pouvez spécifier explicitement le profil à utiliser :
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## Configuration de la sélection des piles
La plupart des actions du CDK Toolkit nécessitent que vous spécifiiez les piles sur lesquelles vous souhaitez opérer. La ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` configuration contrôle cette sélection.
### Sélectionnez toutes les piles
Utilisez-le lorsque vous souhaitez opérer sur chaque pile de votre application CDK :
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### Sélectionnez uniquement les piles d'assemblage principales
Utilisez cette option pour sélectionner uniquement les piles de niveau supérieur de l'assemblage principal :
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### Sélectionnez une seule pile
Utilisez-le lorsque votre assemblage contient exactement une pile et que vous souhaitez affirmer cette condition. Si l'assemblage inclut une seule pile, il renvoie cette pile. Dans le cas contraire, il lance une exception :
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### Sélectionnez les piles par motif
Utilisez-le pour sélectionner des piles spécifiques par modèle de nom :
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**Astuce**
`PATTERN_MUST_MATCH_SINGLE`À utiliser pour vous assurer qu'une pile correspond exactement à vos modèles, ou `PATTERN_MATCH` s'il est acceptable qu'aucune pile ne corresponde. La correspondance de modèles prend en charge les caractères génériques tels que « \$1 » pour faire correspondre plusieurs piles portant des noms similaires.
## Configuration de la gestion des erreurs
Le kit d'outils CDK utilise des erreurs structurées pour vous aider à identifier et à gérer les problèmes. Chaque erreur inclut :
+ Une **source** indiquant l'origine de l'erreur (boîte à outils ou utilisateur).
+ Un **type d'erreur** spécifique (authentification, validation, etc.)
+ Un **message** descriptif.
### Gestion des erreurs
Utilisez les méthodes d'assistance fournies par le kit d'outils CDK pour détecter et gérer des types d'erreurs spécifiques :
```
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);
}
}
```
**Important**
Ne vous fiez pas aux `instanceof` vérifications pour détecter les types d'erreurs, car elles peuvent se comporter de manière inattendue lorsque vous travaillez avec plusieurs copies du même package. Utilisez toujours les méthodes d'assistance fournies, telles que`ToolkitError.isAuthenticationError()`.
## Configuration des actions du kit d'outils
Chaque action du CDK Toolkit (déploiement, synthé, liste, etc.) possède ses propres options de configuration spécifiques. Ces actions vous permettent de gérer le cycle de vie complet de votre infrastructure CDK. Pour des informations détaillées sur la configuration des actions individuelles, voir [Configurer les actions programmatiques du CDK Toolkit](toolkit-library-actions.md).
**Astuce**
Lorsque vous créez des flux de travail d'automatisation, pensez à combiner plusieurs actions en séquence. Par exemple, vous pouvez avoir besoin de `synth` votre application, `list` des piles pour vérifier ce qui sera déployé, puis de `deploy` l'infrastructure.
# 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
| Méthode | Idéal pour | Considération |
| --- | --- | --- |
| `fromCdkApp` | Travailler avec des applications CDK existantes dans n'importe quelle langue prise en charge. | Nécessite l'installation du langage d'exécution approprié. |
| `fromAssemblyBuilder` | Création de constructions CDK en ligne avec un contrôle total sur le processus de synthèse. | Fournit un accès de bas niveau aux fonctionnalités du CDK et peut être utilisé pour créer des versions personnalisées d'autres méthodes telles que. `fromCdkApp` |
| `fromAssemblyDirectory` | Utilisation d'assemblages cloud présynthétisés. | Exécution plus rapide car l'étape de synthèse est ignorée. |
| Source personnalisée | Scénarios extrêmement spécialisés nécessitant une mise en œuvre personnalisée complète. | Nécessite l'implémentation de l'`ICloudAssemblySource`interface à partir de zéro ; manque de fonctionnalités intégrées telles que les recherches contextuelles ; rarement nécessaire dans la plupart des cas d'utilisation. |
## 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 :
1. Utilisez directement une source d'assemblage dans le cloud (c'est simple mais peut être plus lent) :
```
// Each operation triggers a new synthesis
await toolkit.deploy(cloudAssemblySource, { /* options */ });
await toolkit.list(cloudAssemblySource, { /* options */ });
```
1. Mettez en cache l'assemblage cloud (plus rapide pour plusieurs opérations) :
```
// 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();
}
```
Utilisez des assemblages mis en cache lorsque :
+ Vous effectuez plusieurs opérations (déploiement, liste, comparaison, etc.).
+ Votre application CDK ne change pas fréquemment pendant les opérations.
+ Vous voulez des performances plus rapides.
Utilisez directement les sources d'assemblage dans le cloud lorsque :
+ Vous n'effectuez qu'une seule opération.
+ Votre application CDK change fréquemment.
+ Vous voulez un code plus simple et vous n'avez pas besoin de prioriser la vitesse de fonctionnement du Toolkit.
**Important**
La plupart des interactions avec le Toolkit doivent utiliser un assembly mis en cache pour de meilleures performances. Le seul moment où vous pouvez éviter la mise en cache est lorsque votre source change fréquemment et que la vérification des modifications s'avère coûteuse.
### 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()`, et`diff()`. 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](toolkit-library-actions.md#toolkit-library-actions-synth).
### É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 de`synth()`, vous obtenez un type spécial qui sert à la fois de lisible `CloudAssembly` et de`CloudAssemblySource`. 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 :
+ Seul l'appel dispose () du parent nettoie réellement les ressources
+ Les assemblages cloud issus des opérations de liste/déploiement sont gérés par leur parent
+ Le fait de ne pas supprimer un assembly cloud mis en cache est considéré comme un bogue
## 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 :
+ **Choisissez la bonne méthode source** : sélectionnez l'approche qui correspond le mieux à votre flux de travail et à vos exigences.
+ **Cache les assemblages cloud** : générez un assemblage cloud une fois que vous l'utilisez `synth()` et réutilisez-le pour plusieurs opérations afin d'éviter toute synthèse inutile, en particulier pour les applications volumineuses.
+ **Gestion des erreurs** : implémentez une gestion des erreurs de base pour détecter et afficher les erreurs aux utilisateurs. Simplifiez la gestion des erreurs et concentrez-vous sur la fourniture de messages d'erreur clairs.
+ **Compatibilité des versions : assurez-vous que la version** de votre bibliothèque CDK Toolkit peut prendre en charge les assemblages cloud avec lesquels vous travaillez. Si la bibliothèque Construct utilisée pour créer l'assemblage cloud est plus récente que celle prise en charge par votre bibliothèque de boîtes à outils, vous recevrez un message d'erreur.
+ **Variables d'environnement** : sachez que certaines variables d'environnement peuvent affecter la synthèse et le déploiement des assemblages dans le cloud. Des variables telles que `CDK_DEFAULT_ACCOUNT``CDK_DEFAULT_REGION`,`CDK_OUTDIR`, et `CDK_CONTEXT_JSON` peuvent remplacer les comportements par défaut. Assurez-vous qu'ils sont définis de manière appropriée pour votre environnement de déploiement.
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 {
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 :
+ **Installer les dépendances manquantes** : Exécutez `npm install` pour installer les dépendances requises pour votre application CDK.
+ **Résoudre les problèmes de chemin** : vérifiez que les chemins d'accès aux applications CDK et aux répertoires d'assemblage existent et sont accessibles.
+ **Résolvez les incohérences de version** : mettez à jour la version de votre bibliothèque CDK Toolkit pour qu'elle corresponde à la version de votre application CDK.
+ **Corrigez les erreurs de synthèse** : vérifiez le code de votre application CDK pour détecter les erreurs de syntaxe ou les configurations non valides.
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();
}
```
# Configuration des messages et des interactions du CDK Toolkit
La bibliothèque du kit d'outils AWS CDK fournit l'` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) `interface permettant de personnaliser la façon dont les messages et les interactions sont gérés pendant les opérations du CDK, ce qui vous permet de contrôler l'affichage de la progression du déploiement, des messages d'erreur et des instructions utilisateur afin de mieux s'intégrer à l'expérience utilisateur de votre application.
Avant d'effectuer des opérations telles que le déploiement ou la synthèse, vous devez comprendre comment le CDK Toolkit communique avec les utilisateurs. L'`IIoHost`interface sert de canal de communication entre le kit CDK et votre application, gérant à la fois les messages sortants et les réponses des utilisateurs entrants.
Lorsque le CDK Toolkit exécute des opérations, il communique par le biais de deux mécanismes principaux :
+ **Messages** : sorties d'information qui vous informent de la progression de l'opération (comme « Démarrage du déploiement » ou « Ressource créée »).
+ **Demandes** : points de décision nécessitant une saisie ou une confirmation (comme « Voulez-vous déployer ces modifications ? ») , vous donnant la possibilité de fournir des informations dont vous ne saviez pas qu'elles étaient nécessaires à l'avance.
## Utilisation de l'`IIoHost`interface
L'`IIoHost`interface comprend deux méthodes principales :
1. `notify`: gère les messages d'information unidirectionnels.
1. `requestResponse`: gère les demandes interactives qui nécessitent une réponse.
```
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;
}
```
## Niveaux de message et types de demandes
Le kit d'outils CDK génère plusieurs types de messages et de demandes :
### Niveaux des messages
+ **Débogage** : messages détaillés pour le dépannage.
+ **Erreur** : messages d'erreur susceptibles d'affecter le fonctionnement.
+ **Info** : messages d'information généraux.
+ **Résultat** : message principal d'une opération.
+ **Trace** : informations très détaillées sur le flux d'exécution.
+ **Avertissement** : messages d'avertissement qui n'empêchent pas le fonctionnement.
Pour une liste complète, voir [IoMessages Registry](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) dans le manuel de *référence de l'API de la bibliothèque AWS CDK Toolkit*.
### Types de demande
Le kit d'outils CDK envoie des demandes lorsqu'il a besoin d'une saisie ou d'une confirmation de la part de l'utilisateur. Il s'agit de messages spéciaux qui permettent d'obtenir une réponse. Si aucune réponse n'est fournie, le kit d'outils utilisera une réponse par défaut lorsqu'elle sera disponible.
## Mise en `IIoHost` œuvre de base
Voici un exemple simple de mise en œuvre d'un hôte io personnalisé :
```
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
});
```
Le kit d'outils CDK attend la fin de chaque appel, ce qui vous permet d'effectuer des opérations asynchrones telles que des requêtes HTTP ou des instructions utilisateur lors de la gestion des messages.
## `IIoHost`Comportement par défaut
Si vous ne fournissez pas d'hôte io personnalisé, la bibliothèque du kit d'outils CDK utilise une implémentation non interactive par défaut :
+ Sortie console pour les messages (en utilisant les couleurs appropriées pour les différents types de messages).
+ Entièrement non interactif, aucune demande de saisie par l'utilisateur.
+ Utilise automatiquement les réponses par défaut dans la mesure du possible (équivalent à répondre « oui » aux invites).
+ Échoue lorsque la saisie est requise mais qu'aucune réponse par défaut n'est disponible.
Ce comportement par défaut convient aux opérations sans assistance, mais pas aux applications de ligne de commande interactives. Pour les applications en ligne de commande qui nécessitent une interaction de l'utilisateur, vous devez implémenter un hôte io personnalisé. Les implémentations personnalisées sont également utiles pour l'intégration aux systèmes de journalisation ou à d'autres environnements spécialisés. UIs
## Implémentation avancée de l'hôte io
Pour les scénarios plus complexes, nous recommandons d'étendre la `NonInteractiveIoHost` classe comme point de départ. Cette approche vous permet de tirer parti de l'implémentation non interactive existante tout en personnalisant uniquement les comportements spécifiques que vous devez modifier.
Voici un exemple d'hôte io personnalisé qui étend l'implémentation de 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}`);
}
}
```
Cette approche est plus facile à maintenir que d'implémenter l'intégralité de l'`IIoHost`interface à partir de zéro, car il suffit de remplacer les méthodes spécifiques qui nécessitent un comportement personnalisé.
## Intégration à différents environnements
### Intégration d'applications 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
});
```
### Intégration de l'environnement 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
});
```
## Bonnes pratiques pour la mise en œuvre d'un hôte io
Lorsque vous implémentez un hôte io personnalisé, tenez compte des meilleures pratiques suivantes :
+ **Gestion des erreurs** : implémentez une gestion robuste des erreurs dans vos méthodes d'hôte io afin d'éviter que les défaillances n'affectent les opérations du CDK.
+ **Délais d'attente** : envisagez de mettre en place des délais d'attente pour les interactions avec les utilisateurs afin d'éviter une attente indéfinie.
+ **Journalisation** : stockez les messages importants dans les journaux à des fins de résolution des problèmes, en particulier dans les environnements non interactifs.
+ **Réponses par défaut : fournissez des réponses** par défaut judicieuses pour les environnements automatisés dans lesquels l'interaction de l'utilisateur n'est pas possible.
+ **Indication de progression** : pour les opérations de longue durée, fournissez des indicateurs de progression clairs afin d'améliorer l'expérience utilisateur.
L'exemple suivant illustre ces meilleures pratiques en implémentant un hôte io personnalisé avec gestion des erreurs, délais d'expiration pour les interactions avec les utilisateurs et journalisation appropriée. Cette implémentation convient aux applications interactives dans lesquelles vous devez trouver un équilibre entre la réactivité des utilisateurs et la fiabilité du fonctionnement :
```
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
});
```
## Résolution des problèmes
Considérations à prendre en compte lors de l'implémentation d'un hôte io personnalisé :
+ **Rejets de promesses non gérés : assurez-vous** que toutes les opérations asynchrones sont correctement gérées avec des blocs try/catch.
+ **Une attente illimitée** : implémentez des délais d'attente pour toutes les interactions avec les utilisateurs afin d'éviter que l'application ne se bloque.
+ **Niveaux de message manquants** : soyez prêt à gérer les nouveaux niveaux de message qui pourraient être ajoutés dans les futures versions du CDK.
+ **Réponses incohérentes** : assurez-vous que votre implémentation RequestResponse renvoie les valeurs dans le format attendu.
L'exemple suivant illustre une approche robuste de gestion des niveaux de message, y compris la gestion progressive des types de messages inconnus qui pourraient être introduits dans les futures versions du CDK. Cette implémentation garantit que votre hôte io reste compatible avec les mises à jour du CDK tout en maintenant une journalisation correcte :
```
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
});
```
# Exemples de bibliothèque de boîtes à outils CDK avancées
Apprenez à utiliser les fonctionnalités avancées de la bibliothèque du kit d'outils AWS CDK grâce à des exemples pratiques. Ce guide fournit des exemples de code détaillés pour la gestion des erreurs, la surveillance du déploiement et la gestion des assemblages dans le cloud, qui s'appuient sur les concepts de base abordés dans d'autres sections.
## Fonctionnalités d'intégration
L'exemple suivant montre comment combiner les sources d'assemblage cloud, l'implémentation d'hôtes IO personnalisés et les options de déploiement :
```
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'
}
}
});
```
## Suivi de la progression du déploiement
Suivez la progression du déploiement grâce à des mises à jour de statut détaillées :
```
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;
}
}
```
## Gestion des erreurs lors de la restauration
Mettez en œuvre une gestion robuste des erreurs grâce à des stratégies de restauration :
```
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);
}
```
## Intégration aux pipelines CI/CD
Intégrez la bibliothèque du kit d'outils CDK dans un 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');
});
```
## Ressources supplémentaires
Pour des informations plus détaillées sur les composants spécifiques utilisés dans ces exemples, reportez-vous à :
+ [Gestion des sources d'assemblage cloud](toolkit-library-configure-ca.md) - Découvrez comment créer et gérer des sources d'assemblage cloud.
+ [Configuration des messages et des interactions](toolkit-library-configure-messages.md) - Guide détaillé sur la personnalisation de l'`IIoHost`interface.