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.

Conserve los recursos implementados al refactorizar el código del CDK

Con AWS la refactorización del Cloud Development Kit (AWS CDK), puede refactorizar el código del CDK, por ejemplo, cambiar el nombre de las construcciones, mover los recursos entre pilas y reorganizar la aplicación, a la vez que conserva los recursos desplegados en lugar de sustituirlos. Esta característica le ayuda a mantener las prácticas recomendadas de ingeniería de software sin tener que sustituir recursos de forma no intencionada.

¿De qué se trata la refactorización de CDK con la preservación de recursos?

Al implementar una aplicación de CDK, identifica los recursos según su lógica. AWS CloudFormation IDs La AWS CDK genera estas lógicas en IDs función del ID de construcción y su ruta en el árbol de construcción. Si cambias el identificador de una construcción o la mueves a una ubicación diferente del código, AWS CloudFormation normalmente se interpreta como una solicitud para crear un nuevo recurso y eliminar el anterior. En el caso de los recursos con estado, como bases de datos, buckets de almacenamiento o colas, esta sustitución puede provocar interrupciones en el servicio o la pérdida de datos.

La refactorización de CDK aborda este desafío de esta manera:

Puede realizar la refactorización de CDK mediante el comando cdk refactor de la CLI de CDK o la acción refactor de la biblioteca del kit de herramientas de CDK. Esta guía analiza principalmente el enfoque de la CLI, pero los principios subyacentes se aplican a ambos métodos. Para obtener información sobre el uso de la biblioteca del kit de herramientas, consulte Realizar acciones programáticas con la biblioteca del kit de herramientas de CDK.

Beneficios de la refactorización de CDK

La refactorización de CDK ofrece las siguientes ventajas a los desarrolladores de CDK: AWS

Cómo funciona el comando cdk refactor de la CLI de CDK

En primer lugar, debe implementar su aplicación de CDK inicial para establecer los recursos de referencia en su cuenta. AWS Tras refactorizar el código de CDK, por ejemplo, cambiar el nombre de los constructos o mover los recursos entre pilas, utilice el comando cdk refactor para iniciar el proceso de refactorización de los recursos implementados.

Al ejecutar el comando de refactorización, la CLI de CDK detecta los cambios locales 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. A continuación, la CLI de CDK genera un plan de refactorización que asigna las ubicaciones anteriores de los recursos a sus nuevas ubicaciones. La CLI de CDK le muestra los cambios propuestos y, tras su confirmación, utiliza AWS CloudFormation la API de refactorización para actualizar la lógica IDs de los recursos sin sustituirlos.

Entre bastidores, la CLI de CDK determina qué recursos se han movido comparando sus propiedades y dependencias e identificando los recursos que son funcionalmente equivalentes, pero que tienen diferentes rutas en el árbol de constructos. Si detecta que se agrega, se elimina o se modifica algún recurso, la operación de refactorización se rechazará con un mensaje de error.

Ejemplo de conservación de recursos al refactorizar el código de CDK

En este ejemplo, preservamos los recursos implementados y, al mismo tiempo, refactorizamos nuestro código de CDK mediante el comando cdk refactor de la CLI de CDK.

Nuestro ejemplo de aplicación CDK consta de una sola pila que contiene un bucket de S3, una CloudFront distribución y una función Lambda. El árbol de constructos está estructurado del siguiente modo:

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

A continuación, se muestra un ejemplo de nuestro código de aplicación:

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Ahora, imagine que quiere refactorizar este código para hacer lo siguiente:

Tras la refactorización, el árbol de constructos debería tener el siguiente aspecto:

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

Y el código de refactorización sería:

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Sin la refactorización de CDK, estos cambios provocarían la AWS CloudFormation creación de nuevos recursos y la eliminación de los antiguos, ya que la lógica cambiaría: IDs

Con la refactorización de CDK, la CLI de CDK detecta estos cambios de ruta y utiliza las capacidades AWS CloudFormation de refactorización para preservar los recursos subyacentes. Cuando se ejecuta cdk refactor, la CLI le muestra los cambios que realizará:

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

Cuando confirma ingresando y, la CLI de CDK muestra el progreso de la operación de refactorización:

Refactoring...
✅  Stack refactor complete

Tras la confirmación, la CLI de CDK ejecuta la operación de refactorización, conservando ambos recursos y actualizando su lógica IDs para que coincida con la nueva estructura de código.

El mismo mapeo también se muestra en el resultado del comando cdk diff, organizado por pila:

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

Introducción a la refactorización de CDK

Para comenzar con la refactorización, complete estos requisitos previos:

Use archivos de anulación para resolver las ambigüedades en la refactorización

La CLI de CDK calcula de forma automática todas las asignaciones de recursos en función de la comparación del código con los recursos implementados. En la mayoría de los casos, esta detección automática funciona de forma adecuada, pero hay situaciones en las que la CLI puede encontrar ambigüedades que no puede resolver por sí sola. Utilice un archivo de anulación para proporcionar orientación a la CLI de CDK.

Refactorización de pilas en varios entornos

Una aplicación de CDK puede contener varias pilas que se despliegan en diferentes entornos (AWS cuentas y regiones). Al conservar los recursos durante la refactorización en estas aplicaciones, la CLI de CDK gestiona los entornos de una manera específica:

Este comportamiento garantiza que los recursos permanezcan dentro de su AWS cuenta y región originales, lo cual es necesario porque CloudFormation los recursos no se pueden mover físicamente entre los límites de la cuenta o la región.

Por ejemplo, si la aplicación de CDK define pilas para los entornos de desarrollo y de producción, la operación de refactorización se realizará de forma independiente en cada entorno. Los recursos se pueden trasladar entre pilas dentro del entorno de desarrollo o dentro del entorno de producción, pero no desde el entorno de desarrollo a la producción o viceversa.

Gestión de recursos diseñados para ser reemplazados

Algunas construcciones de CDK se basan en el comportamiento CloudFormation de reemplazo de recursos como parte de su diseño. Por ejemplo, los constructos Version de API Gateway Deployment y Lambda están diseñados para crear nuevos recursos cuando sus propiedades cambian.

Al refactorizar, no incluya cambios que puedan provocar la sustitución de recursos. De lo contrario, la CLI de CDK puede detectar y conservar estos recursos. Esto significa que los recursos que están diseñados para ser reemplazados deben gestionarse de forma independiente a las operaciones de refactorización.

Para administrar de forma adecuada los recursos diseñados para ser reemplazados:

Este enfoque de dos pasos garantiza que los recursos diseñados para ser reemplazados se gestionen de forma adecuada y, al mismo tiempo, le permite beneficiarse de la refactorización de CDK para otros recursos.

Consideraciones y limitaciones generales

Al conservar los recursos durante la refactorización del CDK, tenga en cuenta estas consideraciones:

Refactorización con tuberías CI/CD

Para utilizar la función de refactorización en CI/CD canalizaciones, debe poder ejecutar la CLI de CDK como parte de su canalización. Las siguientes son algunas consideraciones importantes para integrar la refactorización en su flujo de trabajo. CI/CD

Recursos relacionados

Para obtener información sobre las opciones y los argumentos del comando cdk refactor de la CLI de CDK, consulte cdk refactor .

Para empezar con la acción refactor de la biblioteca del kit de herramientas del CDK, consulte Realizar acciones programáticas con la biblioteca del kit de herramientas del CDK.