Esta es la guía para AWS CDK desarrolladores de la versión 2. 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.
| 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.
Temas
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 aplicación de CDK que incluye una sola pila que contiene los recursos migrados.
- Pilas implementadas AWS CloudFormation
-
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 aplicación 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. El AWS CDK CLI creará una nueva aplicación de CDK que contenga una sola pila con sus recursos.
Tras la migración, puede administrar, modificar e implementar su aplicación de CDK para AWS CloudFormation aprovisionar o actualizar sus recursos.
Beneficios de CDK Migrate
Históricamente, la migración de recursos a una AWS CDK ha sido un proceso manual que requiere tiempo y experiencia, AWS CloudFormation e AWS CDK incluso empezar. 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 utilizarla AWS CDK para desarrollar y gestionar aplicaciones nuevas y existentes. AWS
Consideraciones
Consideraciones generales
- Comparación de CDK Migrate con CDK Import
-
El comando
cdk importpuede 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 decdk importpara 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 Importe recursos existentes a una pila.El
cdk migratecomando 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, el AWS CDK CLIcdk importse utiliza para importar sus recursos a la nueva aplicación CDK. El AWS CDK CLI también genera construcciones de L1 para cada recurso por usted. Te recomendamos que locdk migrateutilices al importar desde una fuente de migración compatible a una nueva AWS CDK aplicación. - CDK Migrate crea solo constructos de nivel 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 puedes migrar una AWS CloudFormation pila a una única 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. 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 Tipo de recurso compatible en la Guía del usuario de AWS CloudFormation .
-
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, verifica que el nombre de la pila en la nueva aplicación de CDK coincida 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 utiliza funciones intrínsecas, AWS CDK CLI intentará migrar tu lógica a la aplicación CDK con la
Fnclase. Para obtener más información, consulte class Fn en la Referencia de la API de AWS Cloud Development Kit (AWS CDK) .
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 Empezando con la AWS CDK.
Comience a usar CDK Migrate
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
-
Use
--languagepara especificar el lenguaje de programación de la nueva aplicación de CDK. - 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
--accounty--regionconcdk migratepara proporcionar otros valores. - Directorio de salida de su nuevo proyecto de CDK
-
De forma predeterminada, el AWS CDK CLI creará un nuevo proyecto de CDK en su directorio de trabajo y utilizará el valor que proporcione
--stack-namepara asignar un nombre a la carpeta del proyecto. Si actualmente existe una carpeta con el mismo nombre, el AWS CDK CLI sobrescribirá esa carpeta.Puede especificar una ruta de salida diferente para la nueva carpeta del proyecto de CDK con la opción
--output-path. - 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:
-
Recupera la AWS CloudFormation plantilla de tu pila desplegada.
-
Ejecute
cdk initpara iniciar una nueva aplicación de CDK -
Cree una pila dentro de la aplicación CDK que contenga la AWS CloudFormation pila migrada.
Al migrar desde una AWS CloudFormation pila implementada, el 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 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 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 Administración e implementación de su aplicación de 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 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:
-
Recupera tu AWS CloudFormation plantilla local.
-
Ejecute
cdk initpara iniciar una nueva aplicación de CDK -
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 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 el 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:
-
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.
-
Genere una AWS CloudFormation plantilla: después de escanear, el AWS CDK CLI utiliza el generador iAC para crear una AWS CloudFormation plantilla.
-
Inicialice una nueva aplicación de CDK y migre su plantilla: la AWS CDK CLI se ejecuta
cdk initpara inicializar una nueva AWS CDK aplicación y migra la AWS CloudFormation plantilla a la aplicación CDK como una sola pila.
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 aplicación 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 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 propiedadesS3Bucket,ImageUriyZipFilepara un recursoAWS::Lambda::Functionson 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 propiedadBodyde un recursoAWS::ApiGateway::RestApiacepta 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. El AWS CDK CLI añ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 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
-
Identifique las propiedades de solo escritura para resolverlas en la sección Advertencias del archivo
ReadMede 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.-
Para
MUTUALLY_EXCLUSIVE_PROPERTIES, determine qué propiedad que se excluye mutuamente desea configurar en su aplicación de AWS CDK . -
Para
MUTUALLY_EXCLUSIVE_TYPES, determine qué tipo aceptado utilizará para configurar la propiedad. -
Para
UNSUPPORTED_PROPERTIES, determine si la propiedad es opcional u obligatoria. A continuación, configúrela según sea necesario.
-
-
Utilice las instrucciones del generador IaC y las propiedades de solo escritura para consultar el significado de los tipos de advertencia.
-
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
Propsde 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
Propsen 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
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 la aplicación CDK por primera vez, el AWS CDK CLI utiliza 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 AWS CDK, es posible que la nueva aplicación 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.
- Sintetizar la aplicación
-
Use el comando
cdk synthpara sintetizar la pila de su aplicación de CDK en una plantilla de AWS CloudFormation .Si migró desde una AWS CloudFormation pila o plantilla implementada, puede 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 aplicación de CDK.
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 bootstrappara preparar el entorno. Para obtener más información, consulte AWS CDK arranque.
Implemente la aplicación de CDK
Al implementar una aplicación de CDK, la AWS CDK CLI utiliza el AWS CloudFormation servicio para aprovisionar sus recursos. Los recursos se agrupan en una sola pila en la aplicación de CDK y se implementan como una sola pila de AWS CloudFormation .
Según el lugar desde el que haya realizado la migración, puede realizar la implementación 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ó, la 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 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 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.
