Migre los recursos y AWS CloudFormation plantillas existentes a la AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
Cómo funciona la migraciónVentajas de Migrate CDKConsideracionesRequisitos previosComience a usar Migrate CDKMigre desde una AWS CloudFormation pilaMigre desde una AWS CloudFormation plantillaMigración a partir de los recursos implementadosAdministra e implementa tu aplicación CDK

Esta es la guía para AWS CDK desarrolladores de la versión 2. La CDK versión anterior entró en mantenimiento el 1 de junio de 2022 y finalizó el 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 la 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 desplegados, 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 migratecomando 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.

El AWS CDK CLI utiliza el servicio de generador 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 usuario de AWS CloudFormation .

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

Pilas AWS CloudFormation implementadas

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

AWS CloudFormation Plantillas locales

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

Tras la migración, puedes administrar, modificar e implementar tu CDK aplicación para AWS CloudFormation aprovisionar o actualizar tus recursos.

Ventajas de Migrate CDK

Históricamente, la migración de recursos AWS CDK ha sido un proceso manual que requiere tiempo y experiencia e incluso AWS CDK empezar. AWS CloudFormation Con CDK Migrate, el AWS CDK CLI 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 el AWS CDK para desarrollar y gestionar aplicaciones nuevas y existentes AWS.

Consideraciones

Consideraciones generales

CDKMigrar o CDK importar

El cdk import comando puede importar los recursos implementados a una CDK aplicación nueva o existente. Durante la importación, tendrá que definirse manualmente cada recurso como un constructo de nivel 1 en la aplicación. Se recomienda usarlo cdk import para importar uno o más recursos a la vez a una CDK aplicación nueva o existente. Para obtener más información, consulte Importe 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 CDK aplicación. Durante la migración, el AWS CDK CLI cdk importse utiliza para importar tus recursos a la nueva CDK aplicación. El AWS CDK CLI también genera construcciones de L1 para cada recurso por usted. Te recomendamos que lo cdk migrate utilices al importar desde una fuente de migración compatible a una nueva AWS CDK aplicación.

CDKMigrate solo crea construcciones de nivel 1

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

CDKMigrate crea CDK aplicaciones que contienen una sola pila

La CDK aplicación 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 CDK aplicación.

Al migrar AWS CloudFormation pilas, solo puedes 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 CDK aplicación. Tras la migración, puede especificar los valores de los activos para incluirlos en la CDK aplicación.

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 Tipo de recurso compatible en la Guía del usuario de AWS CloudFormation .

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

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

  • Implemente la CDK aplicación con la misma AWS cuenta y Región de AWS el recurso migrado.

Consideraciones a la hora de migrar desde una plantilla AWS CloudFormation

CDKMigrate 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 CDK CLI intentará migrar tu lógica a la CDK aplicación con la Fn clase. Para obtener más información, consulte la clase Fn en la AWS Cloud Development Kit (AWS CDK) APIReferencia.

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

Limitaciones en los análisis

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 Consideraciones en la Guía del usuario de AWS CloudFormation .

Requisitos previos

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

Comience a usar Migrate CDK

Para empezar, ejecute el AWS CDK CLI cdk migratecomando 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 de las opciones que puede utilizar con cdk migrate con descripciones, 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. Utilice esta opción para especificar un nombre para la pila que se creará en la AWS CDK aplicación tras 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 CDK aplicación.

AWS cuenta y Región de AWS

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

Directorio de salida de su nuevo proyecto CDK

De forma predeterminada, el AWS CDK CLI creará un nuevo CDK proyecto 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, AWS CDK CLI sobrescribirá esa carpeta.

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

Orígenes de las migraciones

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 y Región de AWS.

  • --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"

El AWS CDK CLI hará lo siguiente:

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

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

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

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

Tras la migración, puedes gestionar y modificar la CDK aplicación 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 IDs actualizarán los recursos con una lógica coincidente. Para obtener más información sobre la implementación, consulte Administra e implementa tu aplicación CDK.

Migre desde una AWS CloudFormation plantilla

CDKMigrate permite migrar desde AWS CloudFormation plantillas formateadas en JSON o. 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"

El AWS CDK CLI hará lo siguiente:

  1. Recupera tu AWS CloudFormation plantilla local.

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

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

Tras la migración, puedes gestionar y modificar tu CDK aplicación 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, puedes 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 la AWS SAM CLI comando sam validate --debug 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, despliega la AWS SAM plantilla mediante AWS SAM CLI. A continuación, migre desde la pila implementada.

Migración a partir de los recursos implementados

Para migrar desde AWS los recursos desplegados, 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"

El AWS CDK CLI hará lo siguiente:

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

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

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

Utilice filtros

De forma predeterminada, el 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 con AWS CDK CLI para especificar un criterio según el cual los recursos se migrarán de su cuenta a la nueva CDK aplicación. 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 admitidos

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

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

Tras la migración, debe especificar los valores de las propiedades de solo escritura en la nueva aplicación. CDK El AWS CDK CLI añadirá una sección de advertencias al ReadMe archivo del CDK proyecto 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 de su proyecto. CDK ReadMe Aquí, puedes tomar nota de los recursos de tu CDK aplicación que pueden contener propiedades de solo escritura e identificar los tipos de propiedades de solo escritura que se descubrieron.

    1. Para MUTUALLY_EXCLUSIVE_PROPERTIES, determine qué propiedad que se excluye mutuamente desea 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 tu CDK aplicación, 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 Introduzca aquí los valores correctos. Para obtener descripciones y orientación sobre las propiedades, puedes consultar la AWS CDK API Referencia.

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

    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

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

Administra e implementa tu aplicación CDK

Al migrar a AWS CDK, es posible que la nueva CDK aplicación 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 la nueva aplicación. CDK

Preparación para la implementación

Antes de implementarla, debes preparar CDK la aplicación.

Sintetizar la aplicación

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

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 Sintetice las pilas.

Ejecute diff

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

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

Arranque su entorno

Si es la primera vez que realiza la implementación desde un AWS entorno, úselo cdk bootstrap para preparar el entorno. Para obtener más información, consulte Arranque de AWS CDK.

Implemente su CDK aplicación

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

Según el lugar desde el que hayas migrado, puedes desplegarlos para crear una AWS CloudFormation pila nueva o actualizar una AWS CloudFormation pila existente.

Implemente para crear una AWS CloudFormation pila nueva

Si migró desde los recursos desplegados, el AWS CDK CLI 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ó, 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 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 diferente Región de AWS.

  • 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 CDK aplicación por un nuevo valor. También debes modificar toda la lógica IDs de los recursos de tu CDK aplicación. A continuación, puede realizar la implementación en el mismo entorno para crear una pila y recursos nuevos.

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.

Comprueba que el nombre de la pila de tu CDK aplicación coincida con el nombre de la AWS CloudFormation pila implementada y despliégala en el mismo AWS entorno.