Migre los recursos y AWS CloudFormation plantillas existentes al CDK AWS - AWS Kit Cloud Development Kit (AWS CDK) v2
Cómo funciona la migraciónBeneficios de CDK MigrateConsideracionesRequisitos previosComience a usar CDK MigrateMigre desde una AWS CloudFormation pilaMigre desde una plantilla AWS CloudFormation Migración a partir de los recursos implementadosAdministración e implementación de su aplicación de CDK

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.

Migre los recursos y AWS CloudFormation plantillas existentes al CDK AWS

La función CDK Migrate se encuentra en una versión preliminar de AWS CDK y está sujeta a cambios.

Use la interfaz de línea de comandos (AWS CDK AWS CLI) del AWS Cloud Development Kit (CDK) para migrar AWS los recursos implementados, las AWS CloudFormation pilas implementadas y las AWS CloudFormation plantillas locales a CDK. AWS

Cómo funciona la migración

Utilice el cdk migrate comando AWS CDK CLI para migrar desde las siguientes fuentes:

  • AWS Recursos desplegados.

  • AWS CloudFormation Pilas desplegadas.

  • AWS CloudFormation Plantillas locales.

AWS Recursos desplegados

Puede migrar AWS los recursos desplegados desde un entorno específico (AWS cuenta y AWS región) que no estén asociados a una AWS CloudFormation pila.

La CLI de AWS CDK utiliza el servicio de generador IaC para buscar recursos en su AWS entorno y recopilar detalles de los recursos. Para obtener más información sobre el generador de iAC, consulte Generación de plantillas para los recursos existentes en la Guía del usuario. AWS CloudFormation

Tras recopilar los detalles de los recursos, la CLI de AWS CDK crea una nueva aplicación de CDK que incluye una única pila que contiene los recursos migrados.

Pilas implementadas AWS CloudFormation

Puede migrar una sola AWS CloudFormation pila a una nueva aplicación de AWS CDK. La CLI de AWS CDK recuperará la AWS CloudFormation plantilla de su pila y creará una nueva aplicación de CDK. La aplicación CDK constará de una sola pila que contendrá la pila migrada. AWS CloudFormation

Plantillas locales AWS CloudFormation

Puede migrar desde una AWS CloudFormation plantilla local. Las plantillas locales pueden contener recursos implementados o no. La CLI de AWS CDK creará una nueva aplicación de CDK que contiene una sola pila con sus recursos.

Tras la migración, puede administrar, modificar e implementar su aplicación de CDK para aprovisionar o AWS CloudFormation actualizar sus recursos.

Beneficios de CDK Migrate

Históricamente, la migración de recursos a la AWS CDK ha sido un proceso manual que requiere tiempo y experiencia con una AWS CDK para AWS CloudFormation empezar. Con CDK Migrate, la AWS CLI de CDK le facilita la mayor parte del esfuerzo de migración en una fracción del tiempo. CDK Migrate le permitirá empezar rápidamente a utilizar la AWS CDK para desarrollar y gestionar aplicaciones nuevas y existentes. AWS

Consideraciones

Consideraciones generales

CDK Migrate frente a CDK Import

El comando cdk import puede importar los recursos implementados a una aplicación de CDK nueva o existente. Durante la importación, tendrá que definirse manualmente cada recurso como un constructo de nivel 1 en la aplicación. Recomendamos el uso de cdk import para importar uno o más recursos a la vez a una aplicación de CDK nueva o existente. Para obtener más información, consulte Importar los recursos existentes a una pila.

El cdk migrate comando migra desde los recursos desplegados, las AWS CloudFormation pilas desplegadas o las AWS CloudFormation plantillas locales a una nueva aplicación de CDK. Durante la migración, la CLI de AWS CDK se utiliza cdk import para importar los recursos a la nueva aplicación de CDK. La CLI de AWS CDK también genera por usted construcciones de L1 para cada recurso. Se recomienda utilizarla cdk migrate al importar desde una fuente de migración compatible a una nueva AWS aplicación de CDK.

CDK Migrate solo crea construcciones de capa 1

La aplicación de CDK recién creada incluirá únicamente constructos de nivel 1. Puede agregar constructos de nivel superior a su aplicación después de la migración.

CDK Migrate crea aplicaciones de CDK que contienen una sola pila

La aplicación de CDK recién creada contendrá una sola pila.

Al migrar los recursos implementados, todos los recursos migrados se incluirán en una sola pila en la nueva aplicación de CDK.

Al migrar AWS CloudFormation pilas, solo puede migrar una única pila a una única AWS CloudFormation pila en la nueva aplicación CDK.

Migración de activos

Los activos del proyecto, como el código AWS Lambda, no se migrarán directamente a la nueva aplicación CDK. Después de la migración, puede especificar los valores de los activos para incluirlos en la aplicación de CDK.

Migración de recursos con estado

Al migrar recursos con estado, como bases de datos y buckets de Amazon Simple Storage Service (Amazon S3), lo más habitual es migrar el recurso existente, en lugar de crear uno nuevo.

Para migrar y conservar los recursos con estado, haga lo siguiente:

  • Compruebe que el recurso con estado admite la importación. Para obtener más información, consulte la compatibilidad con los tipos de recursos en la Guía del AWS CloudFormation usuario.

  • Después de la migración, compruebe que el ID lógico del recurso migrado en la nueva aplicación de CDK coincide con el ID lógico del recurso implementado.

  • Si vas a migrar desde una AWS CloudFormation pila, comprueba que el nombre de la pila de la nueva aplicación CDK coincide con la AWS CloudFormation pila.

  • Implemente la aplicación CDK con la misma AWS cuenta y AWS región del recurso migrado.

Consideraciones a la hora de migrar desde una plantilla AWS CloudFormation

CDK Migrate admite la migración de una sola plantilla

Al migrar AWS CloudFormation plantillas, puede seleccionar una sola plantilla para migrar. No se admiten las plantillas anidadas.

Migración de plantillas con funciones intrínsecas

Al migrar desde una AWS CloudFormation plantilla que utiliza funciones intrínsecas, la AWS CLI de CDK intentará migrar la lógica a la aplicación de CDK con la clase. Fn Para obtener más información, consulte la clase Fn en la referencia de la API del AWS Cloud Development Kit (AWS CDK).

Consideraciones a la hora de realizar migraciones a partir de recursos implementados

Limitaciones de escaneo

Al buscar recursos en su entorno, el generador IaC tiene limitaciones específicas en cuanto a los datos que puede recuperar y cuotas para los análisis. Para obtener más información, consulte las consideraciones en la Guía AWS CloudFormation del usuario.

Requisitos previos

Antes de usar el cdk migrate comando, complete todos los pasos de configuración que se describen en Introducción al AWS CDK.

Comience a usar CDK Migrate

Para empezar, ejecute el cdk migrate comando AWS CDK CLI desde el directorio que elija. Elija las opciones obligatorias y optativas, según el tipo de migración que vaya a realizar.

Para obtener una lista completa y una descripción de las opciones con las que puede utilizarcdk migrate, consulte cdk migrate.

A continuación, se indican algunas opciones importantes que debería proporcionar.

Nombre de pila

La única opción obligatoria es --stack-name. Use esta opción para especificar un nombre para la pila que se creará en la aplicación AWS CDK después de la migración. El nombre de la pila también se utilizará como nombre de la AWS CloudFormation pila en el momento de la implementación.

Idioma

Use --language para especificar el lenguaje de programación de la nueva aplicación de CDK.

AWS cuenta y AWS región

La CLI de AWS CDK recupera la información de la AWS cuenta y AWS la región de las fuentes predeterminadas. Para obtener más información, consulte Entornos del AWS CDK. Puede utilizar las opciones --account y --region con cdk migrate para proporcionar otros valores.

Directorio de salida de su nuevo proyecto de CDK

De forma predeterminada, la CLI de AWS CDK creará un nuevo proyecto de CDK en su directorio de trabajo y utilizará el valor que proporcione --stack-name para asignar un nombre a la carpeta del proyecto. Si actualmente existe una carpeta con el mismo nombre, la CLI de AWS CDK sobrescribirá esa carpeta.

Puede especificar una ruta de salida diferente para la nueva carpeta del proyecto de CDK con la opción --output-path.

Fuente de migración

Elija una opción para especificar el origen desde el que está realizando la migración.

  • --from-path— Migrar desde una AWS CloudFormation plantilla local.

  • --from-scan— Migre desde los recursos desplegados en una AWS cuenta o AWS región.

  • --from-stack— Migre desde una AWS CloudFormation pila.

En función del origen de la migración, puede proporcionar más opciones para personalizar el comando cdk migrate.

Migre desde una AWS CloudFormation pila

Para migrar desde una AWS CloudFormation pila implementada, ofrezca la --from-stack opción. Proporcione el nombre de la AWS CloudFormation pila implementada con--stack-name. A continuación, se muestra un ejemplo:

$ cdk migrate --from-stack --stack-name "myCloudFormationStack"

La CLI de AWS CDK hará lo siguiente:

  1. Recupere la AWS CloudFormation plantilla de la pila implementada.

  2. Ejecute cdk init para iniciar una nueva aplicación de CDK

  3. Cree una pila dentro de la aplicación CDK que contenga la AWS CloudFormation pila migrada.

Al migrar desde una AWS CloudFormation pila implementada, la CLI de la AWS CDK intenta hacer coincidir la lógica del recurso implementado IDs y el nombre de la AWS CloudFormation pila implementada con los recursos y la pila migrados en la nueva aplicación de CDK.

Después de la migración, puede administrar y modificar su aplicación de CDK con normalidad. Al realizar la implementación, AWS CloudFormation identificará la implementación como una actualización de AWS CloudFormation pila debido al nombre de la AWS CloudFormation pila coincidente. Se IDs actualizarán los recursos con una lógica coincidente. Para obtener más información sobre la implementación, consulte Administrar e implementar su aplicación CDK.

Migre desde una plantilla AWS CloudFormation

CDK Migrate admite la migración desde AWS CloudFormation plantillas formateadas en o. JSON YAML

Para migrar desde una AWS CloudFormation plantilla local, utilice la --from-path opción y proporcione una ruta a la plantilla local. También debe proporcionar la opción --stack-name requerida. A continuación, se muestra un ejemplo:

$ cdk migrate --from-path "./template.json" --stack-name "myCloudFormationStack"

La CLI de AWS CDK hará lo siguiente:

  1. Recupere su AWS CloudFormation plantilla local.

  2. Ejecute cdk init para iniciar una nueva aplicación de CDK

  3. Cree una pila dentro de la aplicación CDK que contenga la AWS CloudFormation plantilla migrada.

Después de la migración, puede administrar y modificar su aplicación de CDK con normalidad. En el momento de la implementación, tiene las siguientes opciones:

  • Actualizar una AWS CloudFormation pila: si la AWS CloudFormation plantilla local se implementó anteriormente, puede actualizar la AWS CloudFormation pila implementada.

  • Implementar una AWS CloudFormation pila nueva: si la AWS CloudFormation plantilla local nunca se implementó o si desea crear una nueva pila a partir de una plantilla implementada anteriormente, puede implementar una nueva AWS CloudFormation pila.

Migre desde una plantilla AWS SAM

Para migrar desde una plantilla de modelo de aplicaciones AWS sin servidor (AWS SAM), primero debe convertirla en una AWS CloudFormation plantilla o implementarla para crear una AWS CloudFormation pila.

Para convertir una plantilla AWS SAM en AWS CloudFormation, puede usar el sam validate --debug comando AWS SAM CLI. Es posible que tenga que configurar lint como false en su archivo samconfig.toml antes de ejecutar este comando.

Para convertirla en una AWS CloudFormation pila, implemente la plantilla AWS SAM mediante la CLI de AWS SAM. A continuación, migre los recursos a partir de la pila implementada.

Migración a partir de los recursos implementados

Para migrar desde AWS los recursos implementados, ofrezca la --from-scan opción. También debe proporcionar la opción --stack-name requerida. A continuación, se muestra un ejemplo:

$ cdk migrate --from-scan --stack-name "myCloudFormationStack"

La CLI de AWS CDK hará lo siguiente:

  1. Escanee su cuenta en busca de detalles de recursos y propiedades: la CLI de AWS CDK utiliza el generador iAC para escanear su cuenta y recopilar detalles.

  2. Generar una AWS CloudFormation plantilla: después de escanear, la CLI de AWS CDK utiliza el generador IaC para crear una plantilla. AWS CloudFormation

  3. Inicialice una nueva aplicación de CDK y migre su plantilla: la CLI de AWS CDK cdk init se ejecuta para inicializar una AWS nueva aplicación de CDK y AWS CloudFormation migra la plantilla a la aplicación de CDK como una sola pila.

Utilice filtros

De forma predeterminada, la CLI de AWS CDK escaneará todo el AWS entorno y migrará los recursos hasta el límite máximo de cuota del generador IaC. Puede proporcionar filtros con la CLI de AWS CDK para especificar un criterio según el cual los recursos se migran de su cuenta a la nueva aplicación de CDK. Para obtener más información, consulte --filter .

Búsqueda de recursos con el generador IaC

En función del número de recursos en la cuenta, la búsqueda puede tardar unos minutos. Aparecerá una barra de progreso durante el proceso de búsqueda.

Tipos de recursos compatibles

La CLI de AWS CDK migrará los recursos compatibles con el generador de IaC. Para obtener una lista completa, consulte la compatibilidad con los tipos de recursos en la Guía del AWS CloudFormation usuario.

Resolución de propiedades de solo escritura

Algunos recursos compatibles contienen propiedades de solo escritura. Estas propiedades se pueden escribir para configurar la propiedad, pero el generador IaC no las puede leer ni AWS CloudFormation para obtener el valor. Por ejemplo, una propiedad utilizada para especificar la contraseña de una base de datos puede ser de solo escritura por motivos de seguridad.

Al analizar los recursos durante la migración, el generador IaC detectará los recursos que puedan contener propiedades de solo escritura y los clasificará de acuerdo con cualquiera de los siguientes tipos:

  • MUTUALLY_EXCLUSIVE_PROPERTIES: se trata de propiedades de solo escritura para un recurso específico que son intercambiables y tienen un propósito similar. Se requiere una de las propiedades que se excluyen mutuamente para configurar el recurso. Por ejemplo, las propiedades S3Bucket, ImageUri y ZipFile para un recurso AWS::Lambda::Function son propiedades de solo escritura que se excluyen mutuamente. Puede usar cualquiera de ellas para especificar los activos de su función, pero debe usar una.

  • MUTUALLY_EXCLUSIVE_TYPES: se trata de propiedades obligatorias de solo escritura que aceptan varios tipos de configuración. Por ejemplo, la propiedad Body de un recurso AWS::ApiGateway::RestApi acepta un tipo de objeto o cadena.

  • UNSUPPORTED_PROPERTIES— Se trata de propiedades de solo escritura que no se incluyen en las otras dos categorías. Son propiedades opcionales u obligatorias que aceptan una matriz de objetos.

Para obtener más información sobre las propiedades de solo escritura y cómo las gestiona el generador de IaC al buscar recursos desplegados y crear AWS CloudFormation plantillas, consulte el generador de IaC y las propiedades de solo escritura en la Guía del usuario. AWS CloudFormation

Después de la migración, debe especificar los valores de las propiedades de solo escritura en la nueva aplicación de CDK. La CLI de AWS CDK añadirá una sección de advertencias al ReadMe archivo del proyecto de CDK para documentar cualquier propiedad de solo escritura que haya sido identificada por el generador IaC. A continuación, se muestra un ejemplo:

# Welcome to your CDK TypeScript project
...
## Warnings
### Write-only properties
Write-only properties are resource property values that can be written to but can't be read by AWS CloudFormation or CDK Migrate. For more information, see [IaC generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html).

Write-only properties discovered during migration are organized here by resource ID and categorized by write-only property type. Resolve write-only properties by providing property values in your CDK app. For guidance, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly).
### MyLambdaFunction
- **UNSUPPORTED_PROPERTIES**:
  - SnapStart/ApplyOn: Applying SnapStart setting on function resource type.Possible values: [PublishedVersions, None]
This property can be replaced with other types
  - Code/S3ObjectVersion: For versioned objects, the version of the deployment package object to use.
This property can be replaced with other exclusive properties
- **MUTUALLY_EXCLUSIVE_PROPERTIES**:
  - Code/S3Bucket: An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
This property can be replaced with other exclusive properties
  - Code/S3Key: The Amazon S3 key of the deployment package.
This property can be replaced with other exclusive properties

  • Las advertencias se organizan con encabezados que identifican el ID lógico del recurso al que están asociadas.

  • Las advertencias se clasifican por tipo. Estos tipos provienen directamente del generador IaC.

Para resolver las propiedades de solo escritura

  1. Identifique las propiedades de solo escritura para resolverlas en la sección Advertencias del archivo ReadMe de su proyecto de CDK. Aquí puede tomar nota de los recursos de su aplicación de CDK que pueden contener propiedades de solo escritura e identificar los tipos de propiedades de solo escritura que se descubrieron.

    1. Para elloMUTUALLY_EXCLUSIVE_PROPERTIES, determine qué propiedad que se excluyen mutuamente configurar en su aplicación de AWS CDK.

    2. Para MUTUALLY_EXCLUSIVE_TYPES, determine qué tipo aceptado utilizará para configurar la propiedad.

    3. Para UNSUPPORTED_PROPERTIES, determine si la propiedad es opcional u obligatoria. A continuación, configúrela según sea necesario.

  2. Utilice las instrucciones del generador IaC y las propiedades de solo escritura para consultar el significado de los tipos de advertencia.

  3. En su aplicación de CDK, los valores de las propiedades de solo escritura que se deben resolver también se especificarán en la sección Props de su aplicación. Introduzca aquí los valores correctos. Para obtener instrucciones y descripciones de las propiedades, puede consultar la referencia de la API de AWS CDK.

    A continuación, se muestra un ejemplo de la sección Props en una aplicación de CDK migrada con dos propiedades de solo escritura que resolver:

    export interface MyTestAppStackProps extends cdk.StackProps {
  /**
   * The Amazon S3 key of the deployment package.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Keym8P82: string;
  /**
   * An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Bucketzidw8: string;
}

    Una vez que haya resuelto todos los valores de las propiedades de solo escritura, estará listo para prepararse para la implementación.

El archivo migrate.json

La CLI de AWS CDK crea un migrate.json archivo en el proyecto de AWS CDK durante la migración. Este archivo contiene información de referencia sobre los recursos implementados. Al implementar la aplicación de CDK por primera vez, la AWS CLI de CDK usa este archivo para hacer referencia a los recursos implementados, asocia los recursos a la nueva AWS CloudFormation pila y elimina el archivo.

Administración e implementación de su aplicación de CDK

Al migrar a la AWS CDK, es posible que la nueva aplicación de CDK no esté lista para su implementación inmediata. En este tema, se describen las medidas que se deben tener en cuenta al administrar e implementar su nueva aplicación de CDK.

Preparación para la implementación

Antes de la implementación, debe preparar la aplicación de CDK.

Sintetice su aplicación

Usa el cdk synth comando para sintetizar la pila de tu aplicación de CDK en una plantilla. AWS CloudFormation

Si migraste desde una AWS CloudFormation pila o plantilla implementada, puedes comparar la plantilla sintetizada con la plantilla migrada para verificar los valores de los recursos y las propiedades.

Para obtener más informacióncdk synth, consulte Sintetizar pilas.

Realiza una diferencia

Si migraste desde una AWS CloudFormation pila implementada, puedes usar el comando cdk diff para compararla con la pila de tu nueva aplicación de CDK.

Para obtener más información sobre cdk diff, consulte Comparar pilas.

Inicie su entorno

Si va a realizar una implementación desde un AWS entorno por primera vez, úsela cdk bootstrap para preparar su entorno. Para obtener más información, consulte AWS CDK bootstrapping.

Implemente la aplicación de CDK

Al implementar una aplicación de CDK, la AWS CLI de CDK utiliza el AWS CloudFormation servicio para aprovisionar sus recursos. Los recursos se agrupan en una sola pila en la aplicación CDK y se implementan como una sola pila. AWS CloudFormation

Según el lugar desde el que haya migrado, puede realizar la implementación para crear una AWS CloudFormation pila nueva o actualizar una pila existente AWS CloudFormation .

Implemente para crear una AWS CloudFormation pila nueva

Si migró desde los recursos implementados, la CLI de AWS CDK creará automáticamente una nueva AWS CloudFormation pila en el momento de la implementación. Los recursos desplegados se incluirán en la nueva AWS CloudFormation pila.

Si migró desde una AWS CloudFormation plantilla local que nunca se implementó, la CLI de AWS CDK creará automáticamente una nueva AWS CloudFormation pila en el momento de la implementación.

Si migró desde una AWS CloudFormation pila implementada o una AWS CloudFormation plantilla local que se implementó anteriormente, puede realizar la implementación para crear una nueva AWS CloudFormation pila. Para crear una nueva pila, haga lo siguiente:

  • Implemente en un AWS entorno nuevo. Consiste en utilizar una AWS cuenta diferente o realizar la implementación en una AWS región diferente.

  • Si quieres implementar una pila nueva en el mismo AWS entorno de la pila o plantilla migrada, debes modificar el nombre de la pila en tu aplicación de CDK por un nuevo valor. También debe modificar toda la lógica IDs de los recursos de su aplicación de CDK. A continuación, puede realizar la implementación en el mismo entorno para crear una pila y recursos nuevos.

Implemente para actualizar una pila existente AWS CloudFormation

Si migró desde una AWS CloudFormation pila implementada o una AWS CloudFormation plantilla local que se implementó anteriormente, puede realizar la implementación para actualizar la AWS CloudFormation pila existente.

Compruebe que el nombre de la pila de su aplicación de CDK coincida con el nombre de la AWS CloudFormation pila implementada e impleméntela en el mismo AWS entorno.