Este es el AWS Guía para desarrolladores de 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 existentes y AWS CloudFormation plantillas al AWS CDK
| |
| --- |
| La función CDK Migrate está en versión preliminar para AWS CDK y está sujeta a cambios. |
Usa el AWS Kit de desarrollo en la nube (AWS CDK) Interfaz de línea de comandos (AWS CDK (CLI) para migrar (implementada) AWS recursos, implementados AWS CloudFormation pilas y locales AWS CloudFormation plantillas para AWS CDK.
## Cómo funciona la migración
Usa el AWS CDK CLI `cdk migrate` comando para migrar desde las siguientes fuentes:
+ Desplegado AWS recursos.
+ Desplegado AWS CloudFormation pilas.
+ Local AWS CloudFormation plantillas.
**Desplegado AWS recursos**
Puede migrar desplegado AWS recursos de un entorno específico (AWS cuenta y AWS Región) que no están asociadas a un AWS CloudFormation pila.
El AWS La CLI del CDK utiliza la *Generador iAC* servicio para buscar recursos en su AWS entorno para recopilar detalles sobre los recursos. Para obtener más información sobre el generador iAC, consulte [Generar plantillas para los recursos existentes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html) en el * AWS CloudFormation Guía del usuario*.
Tras recopilar los detalles de los recursos, el AWS La CLI de CDK crea una nueva aplicación de CDK que incluye una única pila que contiene los recursos migrados.
**Implementado AWS CloudFormation pilas**
Puede migrar una sola AWS CloudFormation apilar en una nueva AWS aplicación CDK. La AWS La CLI del CDK recuperará el AWS CloudFormation plantilla de su pila y creará una nueva aplicación CDK. La aplicación CDK constará de una sola pila que contendrá la versión migrada AWS CloudFormation pila.
**Local AWS CloudFormation plantillas**
Puede migrar desde un local AWS CloudFormation plantilla. Las plantillas locales pueden contener recursos implementados o no. El AWS La CLI de CDK creará una nueva aplicación de CDK que contendrá una sola pila con sus recursos.
Tras la migración, puede administrar, modificar e implementar su aplicación CDK en AWS CloudFormation para aprovisionar o actualizar sus recursos.
## Beneficios de CDK Migrate
Migración de recursos a AWS Históricamente, el CDK ha sido un proceso manual que requiere tiempo y experiencia con AWS CloudFormation y AWS CDK incluso para empezar. Con CDK Migrate, AWS La CLI de CDK le facilita la mayor parte del esfuerzo de migración en una fracción del tiempo. CDK Migrate le ayudará a empezar a utilizar rápidamente la AWS CDK para desarrollar y administrar aplicaciones nuevas y existentes en 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 [Importe recursos existentes a una pila](cli.md#cli-import).
El `cdk migrate` el comando migra desde los recursos desplegados, desplegado AWS CloudFormation pilas o locales AWS CloudFormation plantillas en una nueva aplicación de CDK. Durante la migración, el AWS La CLI del CDK utiliza `cdk import` para importar sus recursos a la nueva aplicación CDK. El AWS La CLI del CDK también genera para usted construcciones L1 para cada recurso. Se recomienda usar `cdk migrate` al importar desde una fuente de migración compatible a una nueva AWS aplicación CDK.
**CDK Migrate solo crea construcciones L1**
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 apílelas en una sola pila en la nueva aplicación CDK.
**Migración de activos**
Activos del proyecto, como AWS El código Lambda no migrará directamente a la nueva aplicación del 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 [Soporte de tipos de recursos](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html) en el * AWS CloudFormation Guía del 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 está migrando desde un AWS CloudFormation compruebe que el nombre de la pila en la nueva aplicación CDK coincida con 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 un AWS CloudFormation modelo
**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 un AWS CloudFormation plantilla que usa funciones intrínsecas, la AWS La CLI de CDK intentará migrar su lógica a la aplicación CDK con el `Fn` clase. Para obtener más información, consulte [clase Fn](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Fn.html) en el * AWS Kit de desarrollo en la nube (AWS Referencia de API (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 [Consideraciones](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC.html#generate-template-considerations) en el * AWS CloudFormation Guía del usuario*.
## Requisitos previos
Antes de usar el `cdk migrate` comando, complete todos los pasos de configuración en [Empezando con el AWS CDK](getting-started.md).
## Comience a usar CDK Migrate
Para empezar, ejecuta el AWS CDK CLI `cdk migrate` comando desde un directorio de su elección. 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](ref-cli-cdk-migrate.md).
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 AWS Aplicación CDK después de la migración. El nombre de la pila también se utilizará como el nombre de su 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 AWS La CLI del CDK recupera AWS cuenta y AWS Información regional de fuentes predeterminadas. Para obtener más información, consulte [Entornos para AWS CDK](environments.md). 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, el AWS La CLI de CDK creará un nuevo proyecto de CDK en su directorio de trabajo y utilizará el valor que usted proporcione `--stack-name` para asignar un nombre a la carpeta del proyecto. Si existe actualmente una carpeta con el mismo nombre, AWS La CLI del 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`.
**Origen de migración**
Elija una opción para especificar el origen desde el que está realizando la migración.
+ `--from-path` — Migrar desde un local AWS CloudFormation plantilla.
+ `--from-scan` — Migrar desde los recursos desplegados en un AWS cuenta y AWS Región.
+ `--from-stack` — Migrar desde un 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 un AWS CloudFormation pila
Para migrar desde un lugar implementado AWS CloudFormation pila, proporcione el `--from-stack` opción. Proporcione el nombre de su equipo desplegado AWS CloudFormation apilar con `--stack-name`. A continuación, se muestra un ejemplo:
```
$ cdk migrate --from-stack --stack-name "myCloudFormationStack"
```
El AWS La CLI del CDK hará lo siguiente:
1. Recupere el AWS CloudFormation plantilla de la pila desplegada.
1. Ejecutar `cdk init` para iniciar una nueva aplicación de CDK
1. Cree una pila dentro de la aplicación CDK que contenga su archivo migrado AWS CloudFormation pila.
Al migrar desde un entorno implementado AWS CloudFormation pila, la AWS La CLI del CDK intenta hacer coincidir los ID lógicos de los recursos implementados con los implementados AWS CloudFormation el nombre de la pila con los recursos migrados y la pila en la nueva aplicación 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 AWS CloudFormation actualización de la pila debido a la coincidencia AWS CloudFormation nombre de la pila. Se actualizarán los recursos con ID lógicos coincidentes. Para obtener más información sobre la implementación, consulte [Administración e implementación de su aplicación de CDK](#migrate-manage).
## Migre desde un AWS CloudFormation modelo
CDK Migrate admite la migración desde AWS CloudFormation plantillas formateadas en `JSON` o `YAML`.
Para migrar desde un local AWS CloudFormation plantilla, utilice `--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 La CLI del CDK hará lo siguiente:
1. Recupere su local AWS CloudFormation plantilla.
1. Ejecutar `cdk init` para iniciar una nueva aplicación de CDK
1. Cree una pila dentro de la aplicación CDK que contenga su archivo migrado AWS CloudFormation plantilla.
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:
+ **Actualiza un AWS CloudFormation pila** — Si el local AWS CloudFormation la plantilla se implementó anteriormente, puede actualizar la implementada AWS CloudFormation pila.
+ **Implemente un nuevo AWS CloudFormation pila** — Si el local AWS CloudFormation la plantilla 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 un AWS SAM template (Plantilla de SAM)
Para migrar desde un AWS Modelo de aplicación sin servidor (AWS plantilla SAM), primero debe convertirla en una AWS CloudFormation plantilla o implementación para crear una AWS CloudFormation pila.
Para convertir un AWS Plantilla SAM para AWS CloudFormation, puedes usar la AWS MISMO CLIP `sam validate --debug` comando. Es posible que tenga que configurar `lint` como `false` en su archivo `samconfig.toml` antes de ejecutar este comando.
Para convertir en un AWS CloudFormation apile, implemente el AWS plantilla SAM utilizando el AWS MISMO CLIP. A continuación, migre los recursos a partir de la pila implementada.
## Migración a partir de los recursos implementados
Para migrar desde una ubicación implementada AWS recursos, proporcione el `--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 La CLI del CDK hará lo siguiente:
1. **Escanee su cuenta para obtener detalles sobre los recursos y las propiedades** — El AWS La CLI del CDK utiliza el generador iAC para escanear su cuenta y recopilar detalles.
1. **Genere un AWS CloudFormation modelo** — Tras escanear, el AWS La CLI del CDK utiliza el generador IaC para crear un AWS CloudFormation plantilla.
1. **Inicialice una nueva aplicación de CDK y migre la plantilla** — El AWS Se ejecuta la CLI del CDK `cdk init` para inicializar una nueva AWS aplicación CDK y migra su AWS CloudFormation plantilla a la aplicación CDK como una sola pila.
### Utilice filtros
De forma predeterminada, el AWS La CLI del CDK escaneará todo AWS entorno y migra los recursos hasta el límite máximo de cuota del generador IaC. Puede proporcionar filtros con el AWS La CLI del CDK permite especificar los criterios para la migración de los recursos de tu cuenta a la nueva aplicación del 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**
Los AWS La CLI del CDK migrará los recursos compatibles con el generador de IaC. Para obtener una lista completa, consulte [Soporte de tipos de recursos](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html) en el * AWS CloudFormation Guía del 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 de 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 sobre cómo las administra el generador IaC al buscar los recursos implementados y al crear AWS CloudFormation plantillas, consulte [generador de iAC y propiedades de solo escritura](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html) en el * AWS CloudFormation Guía del usuario*.
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 La CLI del CDK agregará un **Advertencias** sección del proyecto CDK `ReadMe` archivo 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 `MUTUALLY_EXCLUSIVE_PROPERTIES`, determine qué propiedad mutuamente excluyente desea configurar en su AWS aplicación CDK.
1. Para `MUTUALLY_EXCLUSIVE_TYPES`, determine qué tipo aceptado utilizará para configurar la propiedad.
1. Para `UNSUPPORTED_PROPERTIES`, determine si la propiedad es opcional u obligatoria. A continuación, configúrela según sea necesario.
1. Utilice las instrucciones del [generador IaC y las propiedades de solo escritura](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html) para consultar el significado de los tipos de advertencia.
1. 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](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html).
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 AWS La CLI del CDK crea un `migrate.json` archivo en su AWS proyecto CDK 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 La CLI del CDK usa este archivo para hacer referencia a los recursos implementados y los asocia con los nuevos AWS CloudFormation apila 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 de inmediato. 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.
**Sintetiza tu aplicación**
Usa el `cdk synth` comando para sintetizar la pila de tu aplicación CDK en un AWS CloudFormation plantilla.
Si ha migrado desde una versión implementada AWS CloudFormation pila o plantilla, 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 sobre `cdk synth`, consulte [Sintetizar pilas](cli.md#cli-synth).
**Realice una diferencia**
Si ha migrado desde una empresa implementada AWS CloudFormation puedes usar el comando cdk diff para compararlo con la pila de tu nueva aplicación de CDK.
Para obtener más información sobre cdk diff, consulte [Comparar pilas](cli.md#cli-diff).
**Arranca tu entorno**
Si está realizando la implementación desde un AWS entorno por primera vez, utilice `cdk bootstrap` para preparar su entorno. Para obtener más información, consulte [Arranque de AWS CDK](bootstrapping.md).
### Implemente la aplicación de CDK
Al implementar una aplicación CDK, AWS La CLI del CDK utiliza la 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 AWS CloudFormation pila.
Según el lugar desde el que haya migrado, puede realizar la implementación para crear una nueva AWS CloudFormation apilar o actualizar una existente AWS CloudFormation pila.
**Implemente para crear una nueva AWS CloudFormation pila**
Si ha migrado desde los recursos desplegados, el AWS La CLI del CDK creará automáticamente una nueva AWS CloudFormation pila en el momento de la implementación. Los recursos desplegados se incluirán en el nuevo AWS CloudFormation pila.
Si migraste desde un local AWS CloudFormation plantilla que nunca se implementó, AWS La CLI del CDK creará automáticamente una nueva AWS CloudFormation pila en el momento de la implementación.
Si migró desde una empresa implementada AWS CloudFormation de pila o local AWS CloudFormation plantilla que se implementó anteriormente, puede implementarla para crear una nueva AWS CloudFormation pila. Para crear una nueva pila, haga lo siguiente:
+ Implemente en una nueva AWS entorno. Consiste en utilizar un AWS cuenta o desplegarla en una diferente AWS región.
+ Si desea implementar una nueva pila en la misma AWS en el entorno de la pila o plantilla migrada, debes modificar el nombre de la pila en tu aplicación CDK por un valor nuevo. También debe modificar todos los ID lógicos de los recursos en 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 existente AWS CloudFormation pila**
Si ha migrado desde una empresa implementada AWS CloudFormation de pila o local AWS CloudFormation plantilla que se implementó anteriormente, puede implementarla para actualizar la existente AWS CloudFormation pila.
Verifique que el nombre de la pila de su aplicación CDK coincida con el nombre de la pila de la implementada AWS CloudFormation apile e implemente de la misma manera AWS entorno.