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'synthaction 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. Un assembly cloud contient les artefacts de déploiement suivants provenant de votre application CDK :

Voici comment utiliser l'synthaction 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;

Afficher les informations de la pile avec une liste

L'listaction 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'deployaction 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. 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

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

Annuler les déploiements ayant échoué grâce à la restauration

L'rollbackaction 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'watchaction 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é.

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'destroyaction 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.

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