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.
# Realice acciones programáticas con la biblioteca del kit de herramientas de CDK
## Comprensión de la biblioteca del kit de herramientas de CDK
La biblioteca del kit de herramientas de CDK le permite realizar acciones de CDK mediante programación en lugar de utilizar la CLI. Puede usar esta biblioteca para crear herramientas personalizadas, crear aplicaciones de CLI especializadas e integrar las capacidades de CDK en sus flujos de trabajo de desarrollo.
**Administre el ciclo de vida de su infraestructura con un control programático**
La biblioteca del kit de herramientas de CDK proporciona interfaces programáticas para las siguientes acciones del CDK:
+ **Síntesis**: genere plantillas de AWS CloudFormation y artefactos de implementación.
+ **Implementación**: aprovisione o actualice la infraestructura con las plantillas de CloudFormation.
+ **Refactorización**: 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.
+ **Lista**: muestra información sobre las pilas y sus dependencias.
+ **Supervisión**: supervise las aplicaciones de CDK para ver si hay cambios locales.
+ **Reversión**: devuelve las pilas a su último estado estable.
+ **Destruir**: elimine las pilas de CDK y los recursos asociados.
**Mejore y personalice la administración de su infraestructura**
+ **Control mediante código**: integre la administración de la infraestructura directamente en sus aplicaciones y cree procesos de implementación adaptables.
+ **Gestione los conjuntos en la nube**: cree, inspeccione y transforme las definiciones de su infraestructura antes de la implementación.
+ **Personalice las implementaciones**: configure los parámetros, el comportamiento de reversión y la supervisión para que se adapten a sus necesidades.
+ **Conserve los recursos durante la refactorización**: detecte y conserve automáticamente los recursos al refactorizar el código de CDK.
+ **Gestione los errores con precisión**: implemente una gestión estructurada de errores con información de diagnóstico detallada.
+ **Personalice las comunicaciones**: configure indicadores de progreso personalizados y registre las implementaciones `IoHost`.
+ **Conéctese con AWS**: configure perfiles, regiones y flujos de autenticación de forma programática.
## Elegir cuándo usar la biblioteca del kit de herramientas de CDK
La biblioteca del kit de herramientas de CDK es especialmente valiosa cuando se necesita:
+ Automatice las implementaciones de infraestructura como parte de los procesos de CI/CD.
+ Cree herramientas de implementación personalizadas adaptadas a las necesidades de su organización.
+ Integre las acciones de CDK en las aplicaciones o plataformas existentes.
+ Cree flujos de trabajo de implementación especializados con pasos de validación o aprobación personalizados.
+ Implemente patrones avanzados de administración de infraestructuras en varios entornos.
+ Automatice las operaciones de refactorización para conservar los recursos al refactorizar el código de CDK.
## Utilice la biblioteca del kit de herramientas de CDK
En el siguiente ejemplo se muestra cómo crear e implementar un bucket de S3 sencillo con el kit de herramientas de CDK:
```
// 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);
```
**¿Qué puede hacer ahora?**
+ **Automatice las implementaciones**: active las implementaciones de forma programática y añada pasos previos y posteriores a la implementación.
+ **Integre con los sistemas**: conéctese con flujos de trabajo de CI/CD, herramientas personalizadas y soluciones de supervisión.
+ **Controle los detalles de la implementación**: configure opciones detalladas para la selección de pilas y las implementaciones en varios entornos.
+ **Mejore la fiabilidad**: implemente una gestión de errores lista para la producción y un seguimiento del progreso de la implementación.
+ **Automatice la refactorización**: detecte y conserve los recursos al refactorizar el código de CDK.
## Pasos a seguir a continuación
Para empezar a utilizar la biblioteca del kit de herramientas de CDK, consulte [Introducción a la biblioteca del kit de herramientas de CDK](toolkit-library-gs.md).
## Más información
Para obtener más información acerca de la biblioteca del kit de herramientas de CDK, consulte lo siguiente:
+ [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib) en el paquete `npm` *@aws-cdk/toolkit-lib*.
+ [Referencia de la API de la biblioteca del kit de herramientas de AWS CDK](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Introducción a la Biblioteca dek kit de herramientas de CDK
Comience a usar la biblioteca del kit de herramientas de AWS CDK para realizar de forma programática acciones de CDK, como la síntesis e implementación, en su código.
## Requisitos previos
1. Se ha instalado una versión compatible de Node.js.
1. Credenciales de AWS configuradas.
1. Familiaridad básica con AWS CDK.
Para más información, consulte [Requisitos previos de AWS CDK](prerequisites.md).
## Paso 1: instalar la biblioteca del kit de herramientas de CDK
Instale el paquete de bibliotecas del kit de herramientas CDK en el entorno de desarrollo de su proyecto ejecutando lo siguiente:
```
npm install --save @aws-cdk/toolkit-lib
```
## Paso 2: inicializar la biblioteca del kit de herramientas de CDK
Cree una instancia del kit de herramientas de CDK para realizar acciones programáticas en su aplicación de CDK.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit({
// Optional configuration options go here
});
```
Puede personalizar la instancia del kit de herramientas de CDK durante la creación. Para obtener instrucciones, consulte [Configurar la instancia del kit de herramientas de CDK](toolkit-library-configure.md).
## Paso 3: crear una fuente de ensamblaje en la nube para su aplicación de CDK
Una fuente de ensamblaje en la nube proporciona instrucciones para generar un ensamblaje en la nube a partir de su aplicación de CDK. Puede crear uno de varias maneras. A continuación, se muestran algunos ejemplos:
1. **Una función de creación de conjuntos en línea**:
```
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 archivo de aplicación de CDK existente**:
```
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
```
Consulte [Configurar las fuentes de ensamblaje en la nube](toolkit-library-configure-ca.md) para obtener más información.
## Paso 4: definir acciones programáticas para su aplicación de CDK
Ahora que ha creado una instancia del kit de herramientas de CDK y una fuente de ensamblaje en la nube, puede empezar a definir las acciones programáticas. A continuación, se muestra un ejemplo básico que crea una implementación de la pila `MyStack`:
```
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"],
},
});
```
## Paso 5: seguir personalizando el kit de herramientas de CDK
Puede configurar y personalizar aún más el kit de herramientas de CDK según sus necesidades:
+ **Mensajes e interacciones**: configure la forma en que el kit de herramientas de CDK se comunica con los usuarios y las aplicaciones. Consulte [Configurar mensajes e interacciones](toolkit-library-configure-messages.md).
+ **Gestión de errores**: implemente una gestión estructurada de errores para las operaciones de CDK. Consulte [Configurar la gestión de errores](toolkit-library-configure.md#toolkit-library-configure-errors).
## Recursos adicionales
Para obtener más información sobre el paquete `npm` de bibliotecas del kit de herramientas de CDK, consulte [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib) en el paquete `npm` *@aws-cdk/toolkit-lib*.
Para obtener información de referencia sobre la API, consulte la [referencia sobre las API de la biblioteca del kit de herramientas de CDK.](https://docs.aws.amazon.com/cdk/api/toolkit-lib/)
# 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
}
});
```
# Configuración de la instancia del kit de herramientas de CDK
Aprenda a personalizar su instancia de la biblioteca del kit de herramientas de AWS CDK con opciones de gestión de mensajes, selección de perfiles de AWS y estrategias de selección de pilas. Esta guía explica las opciones de configuración disponibles y cómo implementarlas de manera eficaz para cumplir con sus requisitos específicos de implementación.
## Configuración de su perfil de AWS
Cuando utiliza la biblioteca del kit de herramientas de CDK, esta realiza llamadas a la API para AWS mediante el SDK. Si bien la autenticación se carga de forma automática desde su entorno, puede especificar de forma explícita qué perfil usar:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## Configurar la selección de pila
La mayoría de las acciones del kit de herramientas de CDK requieren que especifique en qué pilas operar. La configuración ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` controla esta selección.
### Seleccionar todas las pilas
Úselo cuando desee operar en todas las pilas de su aplicación de CDK:
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### Seleccione solo las pilas de ensamblaje principales
Utilice esta opción para seleccionar solo las pilas de nivel superior del conjunto principal:
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### Seleccione una pila individual
Úselo cuando su ensamblaje contenga exactamente una pila y desee hacer valer esta condición. Si el ensamblaje incluye una sola pila, este devuelve esa pila. De lo contrario, inicia una excepción:
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### Seleccione las pilas por patrón
Use esto para seleccionar pilas específicas por patrón de nombre:
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**sugerencia**
Utilice `PATTERN_MUST_MATCH_SINGLE` para asegurarse de que exactamente una pila coincida con sus patrones, o `PATTERN_MATCH` si es aceptable, para que ninguna pila coincida. La coincidencia de patrones admite caracteres comodín como “\$1” para hacer coincidir varias pilas con nombres similares.
## Configurar la gestión de errores
El kit de herramientas de CDK utiliza errores estructurados para ayudarlo a identificar y gestionar los problemas. Cada error incluye:
+ Una **fuente** que indique dónde se originó el error (kit de herramientas o usuario).
+ Un **tipo de error** específico (autenticación, validación, etc.).
+ Un **mensaje** descriptivo.
### Gestión de errores
Utilice los métodos auxiliares que proporciona el kit de herramientas de CDK para detectar y gestionar tipos de errores específicos:
```
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);
}
}
```
**importante**
No confíe en las comprobaciones `instanceof` de los tipos de error, ya que pueden comportarse de forma inesperada cuando se trabaja con varias copias del mismo paquete. Utilice siempre los métodos de ayuda proporcionados, como por ejemplo `ToolkitError.isAuthenticationError()`.
## Configuración de las acciones del kit de herramientas
Cada acción del kit de herramientas de CDK (implementar, sintetizar, enumerar, etc.) tiene sus propias opciones de configuración específicas. Estas acciones le permiten administrar el ciclo de vida completo de su infraestructura de CDK. Para obtener información detallada sobre la configuración de acciones individuales, consulte [Configurar las acciones programáticas del kit de herramientas de CDK](toolkit-library-actions.md).
**sugerencia**
Al crear flujos de trabajo de automatización, considere la posibilidad de combinar varias acciones en secuencia. Por ejemplo, es posible que desee usar su aplicación `synth`, las pilas `list` para verificar lo que se va a implementar y, después, la infraestructura `deploy`.
# Administración de las fuentes de ensamblaje en la nube de la biblioteca del kit de herramientas de AWS CDK
Utilice la biblioteca del kit de herramientas de AWS CDK para configurar las fuentes de ensamblaje en la nube y personalizar la manera de implementar las aplicaciones de CDK. Esta guía le muestra cómo configurar las fuentes de ensamblaje en la nube para satisfacer sus requisitos de implementación y sus necesidades de flujo de trabajo.
Antes de usar el kit de herramientas de CDK, especifique una fuente de ensamblaje en la nube. Una *fuente de ensamblaje en la nube* proporciona instrucciones para generar un ensamblaje en la nube a partir de su aplicación de CDK. El ensamblaje de nube resultante contiene los artefactos de infraestructura sintetizados en los que se implementa el kit de herramientas de AWS CDK.
La biblioteca del kit de herramientas de CDK ofrece varios enfoques para configurar las fuentes de ensamblaje en la nube, cada uno adecuado para diferentes escenarios y flujos de trabajo.
## Selección de una fuente de ensamblaje en la nube
| Método | Lo mejor para | Consideración |
| --- | --- | --- |
| `fromCdkApp` | Trabajar con las aplicaciones de CDK existentes en cualquier idioma compatible. | Requiere la instalación del tiempo de ejecución del idioma adecuado. |
| `fromAssemblyBuilder` | Creación de constructos de CDK en línea con un control total sobre el proceso de síntesis. | Proporciona un acceso de bajo nivel a la funcionalidad del CDK y se puede utilizar para crear versiones personalizadas de otros métodos, por ejemplo `fromCdkApp`. |
| `fromAssemblyDirectory` | Uso de ensamblajes de nubes sintetizados previamente. | Ejecución más rápida al omitir el paso de síntesis. |
| Fuente personalizada | Escenarios extremadamente especializados que requieren una implementación personalizada completa. | Requiere implementar la interfaz `ICloudAssemblySource` desde cero; carece de funciones integradas, como las búsquedas de contexto; rara vez se necesita en la mayoría de los casos de uso. |
## Configurar su fuente de ensamblaje en la nube
### Desde una aplicación de CDK existente
Utilice el método `fromCdkApp` para trabajar con aplicaciones de CDK escritas en cualquier idioma compatible. Este enfoque es ideal cuando tiene una aplicación de CDK existente y desea implementarla de forma programática.
```
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");
```
### A partir de un generador de ensamblajes en línea
Cree una aplicación de CDK directamente en su código mediante una función de creación de ensamblajes. Este enfoque es útil para implementaciones sencillas o situaciones de prueba en los que desee definir su infraestructura en línea.
```
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']
});
```
### A partir de un directorio de ensamblajes existente
Si ya tiene un conjunto de nubes sintetizado, puede usarlo de forma directa. Esto resulta útil cuando `cdk synth` ya se está ejecutando o cuando se trabaja con ensamblados en la nube generados por canalizaciones de 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']
});
```
## Trabajar con ensamblajes en la nube almacenados en caché
Al trabajar con conjuntos en la nube, cuenta con dos opciones:
1. Utilice directamente una fuente de ensamblaje en la nube (simple, pero puede ser más lenta):
```
// Each operation triggers a new synthesis
await toolkit.deploy(cloudAssemblySource, { /* options */ });
await toolkit.list(cloudAssemblySource, { /* options */ });
```
1. Almacene en caché el ensamblaje de la nube (más rápido para distintas operaciones):
```
// 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();
}
```
Utilice los ensamblajes en caché cuando:
+ Está realizando varias operaciones (implementar, enumerar, diferenciar, etc.).
+ Su aplicación de CDK no cambia con frecuencia durante las operaciones.
+ Quiere un rendimiento más rápido.
Utilice las fuentes de ensamblaje directamente en la nube cuando:
+ Está realizando una sola operación.
+ Su aplicación de CDK cambia con frecuencia.
+ Desea un código más simple y no necesita priorizar la velocidad de operación del kit de herramientas.
**importante**
La mayoría de las interacciones del kit de herramientas deberían usar un ensamblaje en caché para mejorar el rendimiento. El único momento para evitar el almacenamiento en caché es cuando la fuente cambia con frecuencia y cuando comprobar si hay cambios puede resultar caro.
### Cómo crear, almacenar en caché y reutilizar conjuntos en la nube
Tras crear una fuente de ensamblaje de nube, puede generar un ensamblaje de nube sintetizándolo. Un ensamblaje de nube contiene las plantillas y los activos de AWS CloudFormation necesarios para la implementación.
Se recomienda generar un ensamblaje en la nube una vez y reutilizarlo para varias operaciones del kit de herramientas. Este enfoque de almacenamiento en caché es más eficiente que regenerar el ensamblaje para cada operación. Considere la posibilidad de regenerar el ensamblaje solo cuando la fuente cambia con frecuencia.
A continuación, se explica cómo crear un ensamblaje en la nube:
```
// Generate a cloud assembly from your source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
```
A continuación, puede realizar varias acciones del kit de herramientas en el ensamblaje de nube almacenado en caché, como `list()`, `deploy()` y `diff()`. Al almacenar en caché los conjuntos de nubes, las acciones posteriores del kit de herramientas se realizan más rápido, ya que la síntesis se produce solo una vez. Para obtener más información, consulte [synth: Generar ensamblajes en la nube](toolkit-library-actions.md#toolkit-library-actions-synth).
### Elimine los recursos de ensamblaje en la nube
Deseche siempre los conjuntos en la nube cuando termine de utilizarlos para limpiar los recursos temporales. Recomendamos utilizar un bloque de prueba/final para garantizar una limpieza adecuada, en especial cuando se realizan varias operaciones:
```
// 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();
}
```
A continuación, tenemos un ejemplo que muestra cómo crear y eliminar un conjunto en la nube almacenado en caché:
```
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();
}
```
### Comprender la vida útil de un ensamblaje en la nube
Cuando crea un ensamblaje de nube en caché utilizando `synth()`, obtiene un tipo especial que sirve tanto de legible como `CloudAssembly` de `CloudAssemblySource`. Todos los ensamblajes de nube generados a partir de este ensamblaje en caché (por ejemplo, a partir de operaciones de lista o implementación) están vinculados a la vida útil del conjunto principal:
+ En realidad, solo la llamada dispose() de la entidad principal limpia los recursos
+ Los ensamblajes en la nube de las operaciones de lista o implementación los administra su entidad principal
+ Se considera un error no eliminar un ensamblaje en la nube almacenado en caché
## Prácticas recomendadas para orígenes de conjuntos en la nube
Cuando trabaje con fuentes de ensamblaje en la nube, tenga en cuenta las siguientes prácticas recomendadas:
+ **Elija el método de origen correcto**: seleccione el enfoque que mejor se adapte a su flujo de trabajo y sus requisitos.
+ **Almacene en caché los ensamblajes en la nube**: genere un ensamblaje en la nube una vez mediante `synth()` y reutilícelo para varias operaciones a fin de evitar una síntesis innecesaria, especialmente en aplicaciones de gran tamaño.
+ **Manejo de errores**: implemente un manejo de errores básico para encontrar y mostrar los errores a los usuarios. Simplifique la gestión de errores y concéntrese en proporcionar mensajes de error claros.
+ **Compatibilidad de versiones**: asegúrese de que su versión de la biblioteca del kit de herramientas de CDK sea compatible con los ensamblajes de nube con los que está trabajando. Si la biblioteca de constructos utilizada para crear el ensamblaje en la nube es más reciente de lo que admite la biblioteca del kit de herramientas, recibirá un mensaje de error.
+ **Variables de entorno**: tenga en cuenta que determinadas variables de entorno pueden afectar a la síntesis y la implementación del ensamblaje en la nube. Variables como `CDK_DEFAULT_ACCOUNT`, `CDK_DEFAULT_REGION`, `CDK_OUTDIR` y `CDK_CONTEXT_JSON` pueden anular los comportamientos predeterminados. Asegúrese de que estén configurados de forma adecuada para su entorno de implementación.
El siguiente ejemplo demuestra cómo implementar la gestión de errores y la limpieza adecuada al reutilizar un ensamblaje en la nube para varias operaciones:
```
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);
});
```
## Resolver problemas potenciales
Siga estos pasos para resolver problemas potenciales con las fuentes de conjuntos en la nube:
+ **Instale las dependencias que faltan**: ejecute `npm install` para instalar las dependencias necesarias para su aplicación de CDK.
+ **Solucione problemas de rutas**: compruebe que las rutas a las aplicaciones y los directorios de ensamblaje del CDK existan y estén accesibles.
+ **Resuelva las discrepancias entre versiones**: actualice la versión de la biblioteca del kit de herramientas del CDK para que coincida con la versión de la aplicación de CDK.
+ **Corrija los errores de síntesis**: revise el código de su aplicación de CDK para ver si hay errores de sintaxis o configuraciones no válidas.
Cuando se produzcan errores durante las operaciones del kit de herramientas, simplifique la gestión de los errores y concéntrese en proporcionar a los usuarios mensajes de error claros. Deseche siempre los conjuntos en la nube cuando termine de utilizarlos. A continuación, tenemos un ejemplo que muestra una gestión de errores básica con una limpieza adecuada:
```
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();
}
```
# Configuración de mensajes e interacciones del kit de herramientas de CDK
La biblioteca del kit de herramientas de AWS CDK proporciona la interfaz ` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) ` para personalizar la forma en que se gestionan los mensajes y las interacciones durante las operaciones del CDK, lo que le permite controlar la visualización del progreso de la implementación, los mensajes de error y las indicaciones de los usuarios para integrarlos mejor con la experiencia de usuario de la aplicación.
Antes de realizar operaciones como la implementación o la síntesis, debe comprender cómo se comunica el kit de herramientas de CDK con los usuarios. La interfaz `IIoHost` sirve como canal de comunicación entre el kit de herramientas del CDK y su aplicación, y gestiona tanto los mensajes salientes como las respuestas entrantes de los usuarios.
Cuando el kit de herramientas de CDK ejecuta operaciones, se comunica a través de dos mecanismos principales:
+ **Mensajes**: resultados informativos que le notifican el progreso de la operación (como “Inicio de la implementación” o “Recurso creado”).
+ **Solicitudes**: puntos de decisión que requieren información o confirmación (como “¿Desea implementar estos cambios?”) , lo que le da la oportunidad de proporcionar información que de antemano no se sabía que era necesaria.
## Uso de la interfaz `IIoHost`
La interfaz `IIoHost` consta de dos métodos principales:
1. `notify`: gestiona los mensajes informativos unidireccionales.
1. `requestResponse`: gestiona las solicitudes interactivas que requieren una respuesta.
```
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;
}
```
## Niveles de mensajes y tipos de solicitudes
El kit de herramientas de CDK genera varios tipos de mensajes y solicitudes:
### Niveles de mensajes
+ **Depuración**: mensajes detallados para solucionar problemas.
+ **Error**: mensajes de error que pueden afectar al funcionamiento.
+ **Información**: mensajes de información general.
+ **Resultado**: mensaje principal de una operación.
+ **Rastreo**: información muy detallada del flujo de ejecución.
+ **Advertencia**: mensajes de advertencia que no impiden el funcionamiento.
Para obtener una lista completa, consulte el [registro de IoMessages](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) en la *referencia de la API de la biblioteca del kit de herramientas de AWS CDK*.
### Tipos de solicitud
El kit de herramientas de CDK envía solicitudes cuando necesita información o confirmación por parte del usuario. Se trata de mensajes especiales que dan lugar a una respuesta. Si no se proporciona ninguna respuesta, el kit de herramientas utilizará una respuesta predeterminada cuando esté disponible.
## Implementación básica de `IIoHost`
Este es un ejemplo sencillo de implementación de un host E/S personalizado:
```
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
});
```
El kit de herramientas de CDK espera a que se complete cada llamada, lo que le permite realizar operaciones asíncronas, como solicitudes HTTP o mensajes de usuario, al gestionar los mensajes.
## Comportamiento `IIoHost` predeterminado
Si no proporciona un host E/S personalizado, la biblioteca del kit de herramientas de CDK utiliza una implementación no interactiva predeterminada:
+ Resultado de la consola para los mensajes (con los colores adecuados para los diferentes tipos de mensajes).
+ No interactivo en su totalidad y sin solicitudes de entrada al usuario.
+ Utiliza automáticamente las respuestas predeterminadas siempre que es posible (equivalente a responder “sí” a las preguntas).
+ Falla cuando es necesario introducir datos, pero no hay ninguna respuesta predeterminada disponible.
Este comportamiento predeterminado es adecuado para operaciones desatendidas, pero no para aplicaciones interactivas de la línea de comandos. Para las aplicaciones de línea de comandos que requieren la interacción del usuario, necesitará implementar un host E/S personalizado. Las implementaciones personalizadas también son útiles para la integración con sistemas de registro, interfaces de usuario u otros entornos especializados.
## Implementación avanzada de host E/S
Para escenarios más complejos, recomendamos extender la clase `NonInteractiveIoHost` como punto de partida. Este enfoque le permite aprovechar la implementación no interactiva existente y, al mismo tiempo, personalizar solo los comportamientos específicos que necesita modificar.
A continuación, se muestra un ejemplo de un host E/S personalizado que amplía la implementación 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}`);
}
}
```
Este enfoque es más fácil de mantener que implementar toda la interfaz `IIoHost` desde cero, ya que solo necesita anular los métodos específicos que requieren un comportamiento personalizado.
## Integración con entornos diferentes
### Integración de aplicaciones 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
});
```
### Integración con entornos de 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
});
```
## Prácticas recomendadas para la implementación del host E/S
Al implementar un host E/S personalizado, tenga en cuenta estas prácticas recomendadas:
+ **Gestión de errores**: implemente una gestión de errores sólida en sus métodos de host E/S para evitar que las fallas afecten a las operaciones de CDK.
+ **Tiempos de espera**: considere implementar tiempos de espera para las interacciones de los usuarios a fin de evitar esperas indefinidas.
+ **Registro**: almacene los mensajes importantes en registros para solucionar problemas, en especial en entornos no interactivos.
+ **Respuestas predeterminadas**: proporcione respuestas predeterminadas razonables para entornos automatizados en los que la interacción del usuario no sea posible.
+ **Indicación de progreso**: en el caso de operaciones de larga duración, proporciona indicadores de progreso claros para mejorar la experiencia del usuario.
El siguiente ejemplo demuestra estas prácticas recomendadas mediante la implementación de un host E/S personalizado con gestión de errores, tiempos de espera para las interacciones de los usuarios y un registro adecuado. Esta implementación es adecuada para aplicaciones interactivas en las que es necesario equilibrar la capacidad de respuesta del usuario con un funcionamiento fiable:
```
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
});
```
## Solución de problemas
Consideraciones al implementar un host E/S personalizado:
+ **Rechazos de promesas no gestionados**: asegúrese de que todas las operaciones asincrónicas se gestionen correctamente con bloques try/catch.
+ **Espera infinita**: implementa tiempos de espera para todas las interacciones de los usuarios para evitar que la aplicación se bloquee.
+ **Niveles de mensajes faltantes**: prepárese para gestionar los niveles nuevos de mensajes que puedan agregarse en versiones futuras de CDK.
+ **Respuestas incoherentes**: asegúrese de que la implementación de requestResponse devuelva los valores en el formato esperado.
El siguiente ejemplo demuestra un enfoque sólido para gestionar los niveles de mensajes, que incluye un manejo correcto de los tipos de mensajes desconocidos que podrían introducirse en versiones futuras de CDK. Esta implementación garantiza que su host E/S siga siendo compatible con las actualizaciones de CDK y, al mismo tiempo, mantenga un registro adecuado:
```
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
});
```
# Ejemplos de la biblioteca avanzada del kit de herramientas de CDK
Aprenda a utilizar las funciones avanzadas de la biblioteca del kit de herramientas de AWS CDK mediante ejemplos prácticos. Esta guía proporciona ejemplos de códigos detallados para la gestión de errores, la supervisión de implementación y la gestión del ensamblaje de la nube, que se basan en los conceptos básicos que se tratan en otras secciones.
## Características de integración
En el siguiente ejemplo, se muestra cómo combinar las fuentes de ensamblaje en la nube, la implementación de un host E/S personalizado y las opciones de implementación:
```
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'
}
}
});
```
## Seguimiento del progreso de la implementación
Realice un seguimiento del progreso de la implementación con actualizaciones de estado detalladas:
```
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;
}
}
```
## Gestión de errores con recuperación
Implemente una gestión sólida de los errores con estrategias de recuperación:
```
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);
}
```
## Integración con canalización de CI/CD
Integre la biblioteca del kit de herramientas de CDK en una canalización de 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');
});
```
## Recursos adicionales
Para obtener información más detallada sobre los componentes específicos utilizados en estos ejemplos, consulte:
+ [Gestión de fuentes de ensamblaje en la nube](toolkit-library-configure-ca.md): aprenda a crear y administrar fuentes de ensamblaje en la nube.
+ [Configuración de mensajes e interacciones](toolkit-library-configure-messages.md): guía detallada sobre cómo personalizar la interfaz `IIoHost`.