Esta es la segunda versión de la Guía para desarrolladores de AWS CDK. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.

Configuración de las acciones programáticas del kit de herramientas de CDK

La biblioteca del kit de herramientas de AWS CDK proporciona interfaces programáticas para las acciones del ciclo de vida de las aplicaciones, como la síntesis, la implementación y la administración de la pila. En esta guía, se explica cómo utilizar cada acción del código.

Generación de ensamblajes en la nube con sintetizadores

La acción synth genera un ensamblaje de nube a partir de su fuente de ensamblaje de nube. Para obtener más información sobre la síntesis, consulte Configurar y realizar la síntesis de pilas de CDK. Un ensamblaje de nube contiene los siguientes artefactos de implementación de su aplicación de CDK:

A continuación, se explica cómo utilizar la acción synth para crear un ensamblaje en la nube:

// 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;

Visualización de la información de la pila con lista

La acción list recupera información sobre las pilas de la aplicación CDK, incluidas sus dependencias y su estado actual. Utilice esta acción para inspeccionar la infraestructura antes de la implementación o para generar informes.

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

Aprovisionamiento de la infraestructura con implementación

La acción deploy aprovisiona o actualiza su infraestructura en AWS al utilizar el ensamblaje de nube creado durante la síntesis. Para obtener una introducción a la implementación, consulte Implementación de aplicaciones de AWS CDK. Puede controlar las opciones de implementación, como la selección de pilas, los valores de los parámetros y el comportamiento de reversión.

// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
  parameters: StackParameters.exactly({
    "MyStack": {
      "BucketName": "amzn-s3-demo-bucket"
    }
  })
});

La acción de implementación admite distintos métodos de implementación para adaptarse a distintos flujos de trabajo. Para la mayoría de las situaciones, especialmente en entornos de producción, recomendamos usar el método de implementación predeterminado, que usa conjuntos de cambios de CloudFormation. Para los entornos de desarrollo en los que la velocidad de iteración es importante, puede utilizar métodos alternativos, como 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"]
  }
});

Preservar los recursos implementados con la refactorización

La acción refactor preserva los recursos implementados al refactorizar el código de CDK, por ejemplo, al cambiar el nombre de los constructos o al moverlas entre pilas. Sin esta función, estos cambios provocarían que CloudFormation sustituyera los recursos, lo que podría provocar interrupciones en el servicio o la pérdida de datos.

La acción de refactorización calcula automáticamente las asignaciones comparando el código actual con el estado implementado. Verifica que la aplicación de CDK contenga exactamente el mismo conjunto de recursos que el estado implementado, y solo se diferencian en sus ubicaciones en el árbol de constructos. Si detecta la adición, eliminación o modificación de algún recurso, la operación de refactorización se rechazará con un mensaje de error.

Una vez que calcula las asignaciones, la acción de refactorización utiliza la API de refactorización de CloudFormation para actualizar los ID lógicos de los recursos sin reemplazarlos. En el caso de que encuentre mapeos ambiguos (si existen varios mapeos posibles), puede proporcionar anulaciones explícitas para resolver estas ambigüedades.

// 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"
        }
      }
    ]
  }
});

Revertir las implementaciones fallidas mediante la reversión

La acción rollback devuelve una pila a su último estado estable cuando se produce un error en una implementación y no se puede revertir automáticamente. Utilice esta acción para recuperarse de implementaciones fallidas que requieran una intervención manual.

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

Supervise los cambios con un reloj

La acción watch supervisa continuamente su aplicación de CDK para detectar cambios en los archivos locales y realiza implementaciones o intercambios en caliente de forma automática. De este modo, se crea un detector de archivos que se ejecuta hasta que el código finaliza o se termina.

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 función de vigilancia devuelve un objeto IWatcher que le permite controlar de forma explícita cuándo dejar de mirar. Llame al método dispose() de este objeto cuando quiera finalizar el proceso de visualización.

Eliminar la infraestructura mediante la destrucción

La acción destroy elimina las pilas de CDK y sus recursos asociados de AWS: Utilice esta acción para limpiar los recursos cuando ya no los necesite.

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