Esta es la guía para desarrolladores de AWS CDK v2. 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.
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# 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](configure-synth.md). Un ensamblaje de nube contiene los siguientes artefactos de implementación de su aplicación de CDK:
+ Plantillas de AWS CloudFormation que definen su infraestructura.
+ Activos como el código de función Lambda o las imágenes de Docker.
+ Configuración y metadatos de implementación.
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;
```
**sugerencia**
El uso del ensamblaje en la nube puede optimizar el rendimiento cuando se necesitan realizar varias operaciones, ya que la síntesis solo se produce una vez. Para obtener más información sobre la administración de los ensamblajes en la nube, incluidos el almacenamiento en caché y la eliminación, consulte [Crear y administrar los ensamblajes en la nube](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache).
## 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](deploy.md). 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
**importante**
La acción de refactorizar está en la versión preliminar y está sujeto a cambios.
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"
}
}
]
}
});
```
**importante**
Las operaciones de refactorización deben realizarse por separado, independientemente de otras acciones, como agregar nuevos recursos, eliminar recursos o modificar las propiedades de los recursos. Si necesita realizar estos cambios, primero debe implementarlos por separado y, a continuación, utilizar la refactorización para volver a organizar los recursos.
**sugerencia**
Para obtener más información sobre la refactorización de CDK, incluido cómo funciona y cuándo usarla, consulte [Preservar los recursos implementados al refactorizar el código de CDK](refactor.md).
## 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.
**aviso**
Las implementaciones de Hotswap actualizan los recursos de forma directa sin pasar por CloudFormation cuando es posible, lo que agiliza las actualizaciones durante el desarrollo. Esta opción está habilitada de forma predeterminada para el comando `watch`. Si bien esto acelera el ciclo de desarrollo, introduce una desviación entre las plantillas de CloudFormation y los recursos implementados. Por lo tanto, le recomendamos que no utilice hotswaps en un entorno de producción.
```
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.
**importante**
La acción de destrucción elimina permanentemente los recursos sin solicitar confirmación, a diferencia de la versión de la CLI de este comando. Asegúrese de tener copias de seguridad de todos los datos importantes antes de destruir las pilas.
```
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
}
});
```