Migre los recursos y AWS CloudFormation plantillas existentes a AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
Cómo funciona la migraciónVentajas de CDK MigrateConsideracionesRequisitos previosComience a utilizar CDK MigrateMigre desde una AWS CloudFormation pilaMigre desde una AWS CloudFormation plantillaMigre desde los recursos desplegadosAdministre e implemente su aplicación CDK

Esta es la guía para AWS CDK desarrolladores de la versión 2. La versión anterior del CDK v1 entró en mantenimiento el 1 de junio de 2022 y dejó de ofrecer soporte 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 a AWS CDK

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

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

Cómo funciona la migración

Utilice el AWS CDK CLI cdk migrate comando 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 (Cuenta de AWS y Región de AWS) que no estén asociados a una AWS CloudFormation pila.

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

Tras recopilar los detalles de los recursos, AWS CDK CLI 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 AWS CDK aplicación. AWS CDK CLIRecuperará la AWS CloudFormation plantilla de tu 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. AWS CDK CLICreará una nueva aplicación de CDK que contendrá una sola pila con tus recursos.

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

Ventajas de CDK Migrate

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

Consideraciones

Consideraciones generales

CDK Migrate frente a CDK Import

El cdk import comando puede importar los recursos implementados a una aplicación de CDK nueva o existente. Al importar, cada recurso tendrá que definirse manualmente como una construcción de nivel 1 en la aplicación. Te recomendamos que lo cdk import utilices para importar uno o más recursos a la vez a una aplicación CDK nueva o existente. Para obtener más información, consulte Importación de recursos existentes en 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, se AWS CDK CLI utiliza cdk import para importar tus recursos a la nueva aplicación de CDK. AWS CDK CLITambién genera estructuras de nivel 1 para cada recurso. Te recomendamos que lo cdk migrate utilices al importar desde una fuente de migración compatible a una nueva AWS CDK aplicación.

CDK Migrate crea únicamente construcciones de capa 1

La aplicación CDK recién creada incluirá únicamente las construcciones de L1. Puede agregar construcciones 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 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 pila a una única AWS CloudFormation pila en la nueva aplicación CDK.

Migración de activos

Los activos del proyecto, como el AWS Lambda código, no se migrarán directamente a la nueva aplicación CDK. Tras la migración, puede especificar los valores de los activos para incluirlos en la aplicación 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.

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

  • Si está migrando desde una AWS CloudFormation pila, compruebe que el nombre de la pila de la nueva aplicación de CDK coincide con la pila. AWS CloudFormation

  • Implemente la aplicación CDK con la misma AWS cuenta y el recurso Región de AWS 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 usa funciones intrínsecas, AWS CDK CLI intentará migrar tu lógica a la aplicación CDK con la clase. Fn Para obtener más información, consulta la clase Fn en la referencia de la AWS Cloud Development Kit (AWS CDK) API.

Consideraciones a la hora de migrar desde recursos implementados

Limitaciones de escaneo

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

Requisitos previos

Antes de usar el cdk migrate comando, haga lo siguiente:

  1. Establezca la autenticación con AWS. Para ver instrucciones, consulte Paso 2: Configurar el acceso mediante programación.

  2. Instalar o actualizar la AWS CDK CLI Para obtener las instrucciones de instalación, consulte Paso 3: Instala el AWS CDKCLI.

Comience a utilizar CDK Migrate

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

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

A continuación se muestran algunas opciones importantes que puede que desee 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 AWS CDK aplicación 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

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

AWS cuenta y Región de AWS

AWS CDK CLIRecupera la AWS cuenta y la Región de AWS información de las fuentes predeterminadas. Para obtener más información, consulte Paso 2: Configurar el acceso mediante programación. Puede utilizar --account cualquier --region opción cdk migrate para proporcionar otros valores.

Directorio de salida de su nuevo proyecto de CDK

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

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

Fuente de migración

Proporcione una opción para especificar la fuente desde la que está migrando.

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

  • --from-scan— Migre desde los recursos desplegados en una AWS cuenta y Región de AWS.

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

En función de la fuente de migración, puede proporcionar opciones adicionales para personalizar el cdk migrate comando.

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"

AWS CDK CLIHará lo siguiente:

  1. Recupera la AWS CloudFormation plantilla de tu pila desplegada.

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

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

Al migrar desde una AWS CloudFormation pila implementada, AWS CDK CLI intenta hacer coincidir los ID lógicos de los recursos implementados y el nombre de la AWS CloudFormation pila implementada con los recursos migrados y la pila de la nueva aplicación de CDK.

Tras 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 la AWS CloudFormation pila debido al nombre de la AWS CloudFormation pila coincidente. Se actualizarán los recursos con identificadores lógicos coincidentes. Para obtener más información sobre la implementación, consulteAdministre e implemente su aplicación CDK.

Migre desde una AWS CloudFormation plantilla

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 --stack-name opción requerida. A continuación, se muestra un ejemplo:

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

AWS CDK CLIHará lo siguiente:

  1. Recupera tu AWS CloudFormation plantilla local.

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

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

Tras 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 AWS SAM plantilla

Para migrar desde una plantilla AWS Serverless Application Model (AWS SAM), primero debes convertirla en una AWS CloudFormation plantilla o implementarla para crear una AWS CloudFormation pila.

Para convertir una AWS SAM plantilla en AWS CloudFormation, puedes usar el AWS SAM CLI sam validate --debug comando. Puede que tenga que lint configurarlo false en su samconfig.toml archivo antes de ejecutar este comando.

Para convertirla en una AWS CloudFormation pila, despliegue la AWS SAM plantilla mediante AWS SAM CLI. A continuación, migre desde la pila implementada.

Migre desde los recursos desplegados

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

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

AWS CDK CLIHará lo siguiente:

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

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

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

Usa filtros

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

Escaneo de recursos con el generador iAC

Según la cantidad de recursos de su cuenta, el escaneo puede tardar unos minutos. Aparecerá una barra de progreso durante el proceso de digitalización.

Tipos de recursos admitidos

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

Resuelva las propiedades de solo escritura

Algunos recursos compatibles contienen propiedades de solo escritura. Se puede escribir en estas propiedades 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á en 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 S3BucketImageUri, y de un AWS::Lambda::Function recurso son ZipFile 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 Body propiedad de un AWS::ApiGateway::RestApi recurso 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 o propiedades 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

Tras la migración, debe especificar los valores de las propiedades de solo escritura en la nueva aplicación CDK. AWS CDK CLIAñadirá una sección de advertencias al ReadMe archivo del proyecto 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 bajo encabezados que identifican el identificador lógico del recurso al que están asociadas.

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

Para resolver las propiedades de solo escritura

  1. Identifique las propiedades de solo escritura que desee resolver en la sección Advertencias del archivo de su proyecto de CDK. ReadMe 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. Por ejemploMUTUALLY_EXCLUSIVE_PROPERTIES, determine qué propiedad que se excluyen mutuamente configurar en su aplicación. AWS CDK

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

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

  2. Utilice las instrucciones del generador de IaC y las propiedades de solo escritura para hacer referencia al significado de los tipos de advertencia.

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

    A continuación, se muestra un ejemplo de la Props sección de 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

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

Administre e implemente su aplicación CDK

Al migrar a 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 implementarla, debe preparar la aplicación 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ón acerca de la cdk synth, consulte Sintetizando pilas.

Realice 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. Comparación de 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 Bootstrapping (Proceso de arranque).

Implemente su aplicación CDK

Cuando implementa una aplicación de CDK, AWS CDK CLI 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 desplegados, AWS CDK CLI se 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 migraste desde una AWS CloudFormation plantilla local que nunca se implementó, se AWS CDK CLI 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 AWS CloudFormation pila nueva. Para crear una pila nueva, haga lo siguiente:

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

  • Si quieres implementar una pila nueva en el mismo AWS entorno que 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 todos los ID lógicos 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 nueva y nuevos recursos.

Implemente para actualizar una AWS CloudFormation pila existente

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.