Conserve los recursos implementados al refactorizar el código de la CDK - AWS Kit Cloud Development Kit (AWS CDK) v2
¿Qué es la refactorización de CDK con la preservación de recursos?Ventajas de la refactorización de CDKCómo funciona el cdk refactor comando CDK CLIEjemplo de conservación de recursos al refactorizar el código CDKComience con la refactorización de CDKUtilice archivos de anulación para resolver las ambigüedades de la refactorizaciónRefactorización de pilas en varios entornosManejo de recursos diseñados para ser reemplazadosConsideraciones y limitaciones generalesRefactorización con canalizaciones CI/CD Recursos relacionados

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 de la CDK

importante

La refactorización de CDK se encuentra en versión preliminar y está sujeta a cambios.

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 función le ayuda a mantener las buenas prácticas de ingeniería de software sin tener que sustituir recursos de forma no intencionada.

¿Qué es la refactorización de CDK con la preservación de recursos?

Al implementar una aplicación de CDK, AWS CloudFormation identifica los recursos por su lógica. 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, depósitos 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 la siguiente manera:

  • Detectar cuándo los recursos se han movido o cambiado de nombre en su código.

  • Uso AWS CloudFormation de las capacidades de refactorización para preservar los recursos físicos subyacentes.

  • Actualizar la lógica IDs sin reemplazar los recursos reales.

  • Mantener las referencias entre los recursos en todas sus pilas.

Puede realizar la refactorización de CDK mediante el cdk refactor comando CLI de CDK o la acción de la biblioteca de CDK Toolkit. refactor Esta guía analiza principalmente el enfoque 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 CDK.

importante

Las operaciones de refactorización deben realizarse por sí solas, independientemente de otras acciones, como añadir nuevos recursos, eliminarlos o modificar las propiedades de los recursos.

Si necesita añadir, eliminar o modificar recursos además de refactorizarlos, primero debe implementar esos cambios por separado y, a continuación, utilizar la refactorización para reorganizar los recursos.

Ventajas de la refactorización de CDK

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

  • Mejore la organización del código: cambie el nombre de las construcciones y reorganice la estructura de su aplicación de CDK sin reemplazar recursos.

  • Cree componentes reutilizables: extraiga el código duplicado en construcciones L3 reutilizables y, al mismo tiempo, conserve los recursos desplegados.

  • Mejore la separación arquitectónica: mueva los recursos entre pilas para aislar mejor las diferentes partes de su aplicación.

  • Evite el reemplazo accidental de recursos: evite la recreación involuntaria de recursos al cambiar el nombre de las construcciones.

  • Mitigue los cambios en bibliotecas de terceros: proteja su aplicación de los cambios de identificador lógico en las bibliotecas de construcción de las que depende.

  • Aplique las mejores prácticas de ingeniería de software: refactorice su código sin comprometer la infraestructura implementada.

Cómo funciona el cdk refactor comando CDK CLI

importante

Debe proporcionar la --unstable=refactor opción con todos los comandos que utilizan esta función.

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

Al ejecutar el comando refactor, la CLI de CDK detecta los cambios locales comparando el código actual con el estado implementado. Verifica que la aplicación CDK contenga exactamente el mismo conjunto de recursos que el estado desplegado, y solo se diferencian en sus ubicaciones en el árbol de construcción. A continuación, la CLI de CDK genera un plan de refactorización que asigna las ubicaciones de recursos antiguas 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 construcción. 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.

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

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

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 construcción se estructura de la siguiente manera:

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

El siguiente es un ejemplo del código de nuestra 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, imagina que quieres refactorizar este código para:

  1. Cambie el nombre del depósito Bucket a uno más descriptivo. WebsiteOrigin

  2. Mueva el depósito y la distribución a una nueva WebStack pila.

Tras la refactorización, el árbol de construcción tendría este aspecto:

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

Y el código refactorizado 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 AWS CloudFormation provocarían la creación de nuevos recursos y la eliminación de los antiguos, ya que la lógica cambiaría: IDs

  • MyStack/Bucket/Resourcese convertiría en. WebStack/WebsiteOrigin/Resource

  • MyStack/Distribution/Resourcese convertiría enWebStack/Distribution/Resource.

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 ejecutacdk 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)?

Al confirmar ingresandoy, 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 cdk diff comando, 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)
...

Comience con la refactorización de CDK

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

Inicie su entorno con la plantilla más reciente

La función de refactorización de CDK requiere nuevos permisos en la pila de bootstrap. Para asegurarse de que dispone de los permisos necesarios, inicie su entorno con la plantilla más reciente:

cdk bootstrap

Para obtener más información sobre el arranque, consulte Entornos de arranque para AWS CDK.

Instale la última versión de CDK CLI

La refactorización de CDK requiere una versión reciente de la CLI de CDK. Para asegurarse de tener la versión más reciente:

npm install -g aws-cdk

Para obtener instrucciones de instalación detalladas, consulte Introducción a la AWS CDK.

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

La CLI de CDK calcula automáticamente 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 bien, pero hay situaciones en las que la CLI puede encontrar ambigüedades que no puede resolver por sí sola. Para proporcionar orientación a la CLI de CDK, utilice un archivo de anulación.

Cree un archivo de anulación para resolver las ambigüedades

Un archivo de anulación es un archivo JSON que proporciona mapeos cuando la CLI de CDK no puede determinar una resolución de refactorización para los recursos. El archivo contiene asignaciones de recursos organizadas por entorno:

{
    "environments": [
        {
            "account": "123456789012",
            "region": "us-east-2",
            "resources": {
                "StackA.OldName": "StackB.NewName",
                "StackC.Foo": "StackC.Bar"
            }
        }
    ]
}

En este archivo:

  • La environments matriz contiene una o más entradas de entorno con la cuenta y la región.

  • Dentro de cada entorno, el resources objeto contiene las asignaciones.

  • Las claves representan las ubicaciones actuales en el formato. <stack name>.<logical ID>

  • Los valores representan las nuevas ubicaciones en el mismo formato.

Para usar un archivo de anulación con la CLI de CDK:

cdk refactor --override-file=overrides.json

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 dichas aplicaciones, la CLI de CDK gestiona los entornos de una manera específica:

  • La CLI agrupa las pilas por entorno y realiza la refactorización por separado en cada entorno.

  • Puede mover recursos entre pilas durante la refactorización, pero todas las pilas implicadas en el movimiento deben estar en el mismo entorno.

  • Si intenta mover recursos de un entorno a otro, se producirá un error.

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 su aplicación de CDK define pilas para los entornos de desarrollo y producción, la operación de refactorización se realizará de forma independiente en cada entorno. Los recursos se pueden mover entre pilas dentro del entorno de desarrollo o dentro del entorno de producción, pero no del desarrollo a la producción o viceversa.

Manejo 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, las Version construcciones de API Gateway Deployment y Lambda están diseñadas para crear nuevos recursos cuando sus propiedades cambian.

Al refactorizar, no incluya ningún cambio que pueda 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 por separado de las operaciones de refactorización.

Para administrar adecuadamente los recursos diseñados para ser reemplazados:

  1. En primer lugar, implemente la aplicación para reemplazar estos recursos según sea necesario.

  2. A continuación, realice las operaciones de refactorización por separado para reorganizar el código.

Este enfoque de dos pasos garantiza que los recursos diseñados para ser reemplazados se gestionen correctamente 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 de las CDK, tenga en cuenta estas consideraciones:

  • Restricciones del entorno: los recursos solo se pueden mover entre pilas del mismo entorno. No se admiten los movimientos entre entornos.

  • Ambigüedad: si tiene varios recursos idénticos a los que se les cambia el nombre simultáneamente, es posible que la CLI de CDK no pueda determinar automáticamente la asignación correcta. En estos casos, tendrá que proporcionar un mapeo explícito mediante un archivo de anulación.

  • Requisitos de Bootstrap: Para conservar los recursos durante la refactorización, debes actualizar tu pila de bootstrap con la última versión que incluya los permisos necesarios.

  • Se excluyen algunas construcciones: algunas construcciones, como las de API Gateway Deployment y Lambda, se Version basan en la sustitución de recursos y se excluyen automáticamente de la refactorización.

Refactorización con canalizaciones 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

Requisitos previos para utilizar la refactorización en CI/CD

Debe poder utilizar la CLI de CDK en su CI/CD entorno para beneficiarse de esta función.

Integrar la refactorización en el flujo de trabajo de su proceso

Si utilizas la CLI para la implementación en tu CI/CD canalización, el script suele tener el siguiente aspecto:

...
cdk deploy <stack filter>
...

Si quieres incluir la refactorización como parte del flujo de trabajo, el siguiente es un ejemplo básico:

...
cdk refactor <stack filter>
cdk deploy <stack filter>
...

También puedes incluir la refactorización como un paso independiente de tu proceso.

Gestión de los fallos de refactorización

Tenga en cuenta que se cdk refactor producirá un error si el código incluye modificaciones reales de los recursos junto con la refactorización. Como en tu proceso de creación se utiliza la refactorización de forma automática, debes gestionar los posibles errores:

# Allow refactoring to fail but continue the pipeline
cdk refactor <stack filter> || true
cdk deploy <stack filter>

Como alternativa, puedes asegurarte de que no se realice ninguna implementación hasta que hayas realizado una refactorización correcta:

# Only deploy if refactoring succeeds
cdk refactor <stack filter> && cdk deploy <stack filter>
Prácticas recomendadas para entornos CI/CD

Para utilizar la refactorización de forma eficaz en CI/CD las tuberías:

  • Separe la refactorización de otros cambios: recuerde que las operaciones de refactorización deben estar separadas de las adiciones, eliminaciones o modificaciones de recursos. En proyecto, considere la posibilidad de contar con confirmaciones e implementaciones específicas para la refactorización.

  • Utilice los archivos de anulación de forma adecuada: comprenda que la CLI de CDK solo utiliza los archivos de anulación como alternativa para resolver los casos de ambigüedad.

  • No es necesario usar canalizaciones: --force en entornos no interactivos, como las CI/CD canalizaciones, el comando CDK refactor se ejecuta automáticamente sin solicitar confirmación. La --force opción solo es necesaria en entornos interactivos.

Recursos relacionados

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

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