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