Migración de la versión 1 de AWS CDK a la versión 2 de AWS CDK - AWS Kit Cloud Development Kit (AWS CDK) v2
Nuevos requisitos previosActualización de AWS CDK v2 Developer PreviewMigración de la versión 1 de AWS CDK a la versión 2 de CDKPrueba de la aplicación migrada antes de implementarlaSolución de problemasBúsqueda de pilas con v1

Esta es la guía para desarrolladores de AWS CDK v2. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Migración de la versión 1 de AWS CDK a la versión 2 de AWS CDK

La versión 2 de AWS Cloud Development Kit (AWS CDK) está diseñada para facilitar la creación de infraestructura como código en su lenguaje de programación preferido. En este tema, se describen los cambios entre la versión 1 y la versión 2 de AWS CDK.

sugerencia

Para identificar las pilas implementadas con la versión 1 de AWS CDK, recurra a la utilidad awscdk-v1-stack-finder.

Estas son las principales diferencias entre la versión 1 de AWS CDK y la versión 2 de CDK.

  • La versión 2 de AWS CDK consolida las partes estables de la Biblioteca de constructos de AWS, incluida la biblioteca básica, en un solo paquete, aws-cdk-lib. Los desarrolladores ya no necesitan instalar más paquetes para los servicios de AWS individuales que utilizan. Este enfoque de un solo paquete también significa que no es necesario sincronizar las versiones de los distintos paquetes de la biblioteca de CDK.

    Los constructos de nivel 1 (CFNxxxx), que representan los recursos exactos disponibles en AWS CloudFormation, siempre se consideran estables y, por lo tanto, se incluyen en aws-cdk-lib.

  • Los módulos experimentales, en los que seguimos trabajando con la comunidad para desarrollar constructos nuevos de nivel 2 o nivel 3, no se incluyen en aws-cdk-lib. En cambio, se distribuyen como paquetes individuales. Los paquetes experimentales reciben un nombre con un sufijo alpha y un número de versión semántica. El número de versión semántica coincide con la primera versión de la Biblioteca de constructos de AWS con la que es compatible, también con un sufijo alpha. Los constructos pasan a aws-cdk-lib una vez que se los ha calificado como estables, lo que permite que la Biblioteca de constructos principal siga un estricto control de versiones semánticas.

    La estabilidad se especifica por servicio. Por ejemplo, si empezamos a crear uno o más constructos de nivel 2 para Amazon AppFlow que, aquí solo tiene constructos de nivel 1, aparecen primero en un módulo denominado @aws-cdk/aws-appflow-alpha. Luego, pasan a aws-cdk-lib cuando consideramos que los nuevos constructos satisfacen las necesidades fundamentales de los clientes.

    Una vez que se haya calificado como estable a un módulo y se haya incorporado a aws-cdk-lib, se agregan nuevas API con la convención “BetaN” que se describe en la siguiente viñeta.

    Se publica una nueva versión de cada módulo experimental con cada lanzamiento del AWS CDK. Sin embargo, en su mayor parte, no es necesario mantenerlos sincronizados. Puede actualizar aws-cdk-lib o el módulo experimental cuando quiera. La excepción es que, cuando dos o más módulos experimentales relacionados dependen uno del otro, deben tener la misma versión.

  • En el caso de los módulos estables a los que se agrega una nueva funcionalidad, las API nuevas (ya se trate de constructos completamente nuevos o de métodos o propiedades nuevos de un constructo existente) reciben un sufijo Beta1 mientras se está trabajando. (Se agrega Beta2, Beta3 y así sucesivamente cuando sea necesario realizar cambios importantes). Cuando la API se califica como estable, se agrega una versión de la API sin el sufijo. Todos los métodos, excepto el más reciente (ya sea beta o final), quedarán obsoletos.

    Por ejemplo, si agregamos un método nuevo grantPower() a un constructo, inicialmente aparecerá como grantPowerBeta1(). Si se necesitan cambios importantes (por ejemplo, nuevos parámetros o propiedades obligatorios), se asignará el nombre grantPowerBeta2() a la siguiente versión del método y así sucesivamente. Una vez finalizado el trabajo y la API, se agrega el método grantPower() (sin sufijo), y los métodos BetaN quedan obsoletos.

    Todas las API beta se conservan en la Biblioteca de constructos hasta la próxima versión principal (3.0) y sus firmas no cambiarán. Si las utiliza, verá advertencias de obsolescencia, por lo que debería pasar a la versión final de la API lo antes posible. Sin embargo, ninguna versión futura de AWS CDK 2.x interrumpirá su aplicación.

  • La clase Construct se ha extraído del AWS CDK y trasladado a una biblioteca independiente, junto con los tipos relacionados. Esto se hace para apoyar los esfuerzos por aplicar el Modelo de programación de constructos en otros dominios. Si está escribiendo sus propios constructos o usando API relacionadas, debe declarar el módulo constructs como una dependencia y realizar cambios menores en las importaciones. Si utiliza características avanzadas, como conectarse al ciclo de vida de la aplicación de CDK, es posible que deba realizar más cambios. Para obtener más información, consulte RFC.

  • Las propiedades, los métodos y los tipos obsoletos en AWS CDK v1.x y su Biblioteca de constructos se han eliminado por completo de la API de CDK v2. En la mayoría de los lenguajes admitidos, estas API generan advertencias en v1.x, por lo que es posible que ya haya migrado a las API de reemplazo. En GitHub, se encuentra una lista completa de las API obsoletas en CDK v1.x.

  • El comportamiento que estaba restringido por marcas de características en AWS CDK v1.x ahora está habilitado de forma predeterminada en la versión 2 CDK. Las marcas de características anteriores ya no son necesarias y, en la mayoría de los casos, no se admiten. Algunas todavía están disponibles para que pueda volver al comportamiento de CDK v1 en circunstancias muy específicas. Para obtener más información, consulte Actualización de las marcas de características.

  • Con CDK v2, los entornos en los que realice las implementaciones deben arrancarse con la pila de inicio moderna. La pila de arranque antigua (la predeterminada en v1) ya no cuenta con soporte. Además, CDK v2 requiere una versión nueva de la pila moderna. Para actualizar los entornos existentes, vuelva a arrancarlos. Ya no es necesario establecer ninguna marca de características ni variable de entorno para utilizar la pila de arranque moderna.

importante

La plantilla de arranque moderna otorga de manera efectiva los permisos implícitos de --cloudformation-execution-policies a cualquier cuenta de AWS en la lista --trust. De forma predeterminada, esto extiende los permisos de lectura y escritura a cualquier recurso de la cuenta iniciada. Asegúrese de configurar la pila de arranque con políticas y cuentas de confianza con las que se sienta cómodo.

Nuevos requisitos previos

La mayoría de los requisitos de la versión 2 de AWS CDK son los mismos que los de AWS CDK v1.x. Aquí se enumeran los requisitos adicionales.

  • Para los desarrolladores que usan TypeScript, se requiere TypeScript 3.8 o una versión posterior.

  • Se necesita una nueva versión del kit de herramientas de CDK para utilizarla con CDK v2. Ahora que CDK v2 está disponible de forma general, v2 es la versión predeterminada al instalar el kit de herramientas de CDK. Es compatible con los proyectos de CDK v1, por lo que no es necesario mantener instalada la versión anterior a menos que desee crear proyectos de CDK v1. Para realizar la actualización, ejecute npm install -g aws-cdk.

Actualización de AWS CDK v2 Developer Preview

Si utiliza CDK v2 Developer Preview, su proyecto tiene dependencias con una versión Release Candidate del AWS CDK, como 2.0.0-rc1. Actualícelas a 2.0.0 y, a continuación, actualice los módulos instalados en su proyecto.

ejemplo
TypeScript

npm install o yarn install

JavaScript

npm install o yarn install

Python
python -m pip install -r requirements.txt
Java
mvn package
C#
dotnet restore
Go
go get

Después de actualizar las dependencias, ejecute npm update -g aws-cdk para actualizar el kit de herramientas de CDK a la versión de lanzamiento.

Migración de la versión 1 de AWS CDK a la versión 2 de CDK

Para migrar su aplicación a la versión 2 de AWS CDK, primero actualice las marcas de características en cdk.json. A continuación, actualice las dependencias y las importaciones de la aplicación según sea necesario para el lenguaje de programación en el que estén escritas.

Actualización a una versión 1 reciente

Observamos que varios clientes pasan de una versión antigua de versión 1 AWS CDK a la versión más reciente de v2 en un solo paso. Si bien es cierto que es posible hacerlo, se estarían incorporando varios años de cambios (aunque, lamentablemente, no todos hayan tenido la misma cantidad de pruebas de evolución que tenemos en la actualidad), además de actualizar versiones con nuevos valores predeterminados y una organización de código diferente.

Para disfrutar de una experiencia de actualización más segura y diagnosticar más fácilmente los orígenes de cualquier cambio inesperado, le recomendamos que separe estos dos pasos: primero pase a la última versión v1 y, a continuación, realice el cambio a v2.

Actualización de las marcas de características

Elimine las siguientes marcas de características la versión 1 de cdk.json, si existen, ya que todas están activas de forma predeterminada en la versión 2 de AWS CDK. Si su efecto anterior es importante para su infraestructura, tendrá que realizar cambios en el código fuente. Consulte la lista de marcas en GitHub para obtener más información.

  • @aws-cdk/core:enableStackNameDuplicates

  • aws-cdk:enableDiffNoFail

  • @aws-cdk/aws-ecr-assets:dockerIgnoreSupport

  • @aws-cdk/aws-secretsmanager:parseOwnedSecretName

  • @aws-cdk/aws-kms:defaultKeyPolicies

  • @aws-cdk/aws-s3:grantWriteWithoutAcl

  • @aws-cdk/aws-efs:defaultEncryptionAtRest

Se pueden configurar algunas marcas de características v1 como false para volver a comportamientos específicos de la versión 1 de AWS CDK; consulte Revertir al comportamiento de la versión 1 o la lista en GitHub para obtener una referencia completa.

Para ambos tipos de marcas, use el comando cdk diff para inspeccionar los cambios en la plantilla sintetizada y ver si los cambios a alguna de estas marcas afectan a su infraestructura.

Compatibilidad con el kit de herramientas de CDK

CDK v2 requiere la versión 2 o una posterior del kit de herramientas de CDK. Esta versión es compatible con versiones anteriores de las aplicaciones de CDK v1. Por lo tanto, puede usar una única versión del kit de herramientas de CDK instalada globalmente en todos sus proyectos de AWS CDK, tanto si utilizan v1 como v2. Una excepción es que el kit de herramientas de CDK v2 solo crea proyectos de CDK v2.

Si necesita crear proyectos de CDK tanto de v1 como de v2, no instale el kit de herramientas de CDK v2 de forma global. (Elimínelo si ya lo tiene instalado: npm remove -g aws-cdk). Para invocar el kit de herramientas de CDK, utilice npx para ejecutar v1 o v2 del kit de herramientas de CDK según lo desee.

npx aws-cdk@1.x init app --language typescript
npx aws-cdk@2.x init app --language typescript
sugerencia

Configure los alias de la línea de comandos para poder usar los comandos cdk y cdk1 para invocar la versión deseada del kit de herramientas de CDK.

macOS/Linux
alias cdk1="npx aws-cdk@1.x"
alias cdk="npx aws-cdk@2.x"
Windows
doskey cdk1=npx aws-cdk@1.x $*
doskey cdk=npx aws-cdk@2.x $*

Actualización de las dependencias y las importaciones

Actualice las dependencias de su aplicación y, a continuación, instale los paquetes nuevos. Por último, actualice las importaciones en su código.

ejemplo
TypeScript
Aplicaciones

En el caso de las aplicaciones de CDK, actualice package.json de la siguiente manera. Elimine las dependencias de los módulos estables individuales de tipo v1 y establezca la versión más baja de aws-cdk-lib que necesite para su aplicación (aquí la versión 2.0.0).

Los constructos experimentales se proporcionan en paquetes separados y con versiones independientes, con nombres que terminan en alpha y un número de versión alfa. El número de versión alfa corresponde a la primera versión de aws-cdk-lib con la que son compatibles. En este caso, hemos fijado aws-codestar en la versión 2.0.0-alpha.1.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}
Bibliotecas de constructos

Para las bibliotecas de constructos, establezca la versión más baja de aws-cdk-lib que necesite para su aplicación (aquí la versión 2.0.0) y actualice package.json de la siguiente manera.

Tenga en cuenta que aws-cdk-lib aparece tanto como una dependencia entre pares como una dependencia de desarrollo.

{
  "peerDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0",
    "typescript": "~3.9.0"
  }
}
nota

Cuando publique una biblioteca compatible con v2, debería introducir un cambio importante en el número de versión de su biblioteca, ya que se trata de un cambio importante para los usuarios de la biblioteca. No es posible ofrecer soporte tanto para v1 como para v2 de CDK con una sola biblioteca. Para seguir ofreciendo soporte a los clientes que continúan usando v1, puede mantener la versión anterior en paralelo o crear un paquete nuevo para v2.

Usted debe decidir cuánto tiempo quiere seguir ofreciendo soporte a los clientes con la versión 1 de AWS CDK. Puede seguir la indicación del ciclo de vida del propio CDK v1, que pasó a la etapa de mantenimiento el 1.° de junio de 2022 y llegará al final de su vida útil el 1.° de junio de 2023. Para obtener más información, consulte Política de mantenimiento de AWS CDK.

Tanto bibliotecas como aplicaciones

Instale las dependencias nuevas ejecutando npm install o yarn install.

Cambie sus importaciones para importar Construct a partir del nuevo módulo constructs; los tipos básicos, como App y Stack a partir del nivel superior de aws-cdk-lib; y los módulos estables de la Biblioteca de constructos para los servicios que utilice a partir de los espacios de nombres en aws-cdk-lib.

import { Construct } from 'constructs';
import { App, Stack } from 'aws-cdk-lib';                 // core constructs
import { aws_s3 as s3 } from 'aws-cdk-lib';               // stable module
import * as codestar from '@aws-cdk/aws-codestar-alpha';  // experimental module
JavaScript

Actualice package.json de la siguiente manera. Elimine las dependencias de los módulos estables individuales de tipo v1 y establezca la versión más baja de aws-cdk-lib que necesite para su aplicación (aquí la versión 2.0.0).

Los constructos experimentales se proporcionan en paquetes separados y con versiones independientes, con nombres que terminan en alpha y un número de versión alfa. El número de versión alfa corresponde a la primera versión de aws-cdk-lib con la que son compatibles. En este caso, hemos fijado aws-codestar en la versión 2.0.0-alpha.1.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}

Instale las dependencias nuevas ejecutando npm install o yarn install.

Cambie las importaciones de la aplicación para hacer lo siguiente:

  • Importe Construct a partir del nuevo módulo constructs

  • Importe los tipos básicos, como App y Stack, a partir del nivel superior de aws-cdk-lib

  • Importe los módulos de la Biblioteca de constructos de AWS a partir de los espacios de nombres en aws-cdk-lib 

const { Construct } = require('constructs');
const { App, Stack } = require('aws-cdk-lib');              // core constructs
const s3 = require('aws-cdk-lib').aws_s3;                   // stable module
const codestar = require('@aws-cdk/aws-codestar-alpha');    // experimental module
Python

Actualice requirements.txt o la definición de install_requires en setup.py de la siguiente manera. Elimine las dependencias de los módulos estables individuales de estilo v1.

Los constructos experimentales se proporcionan en paquetes separados y con versiones independientes, con nombres que terminan en alpha y un número de versión alfa. El número de versión alfa corresponde a la primera versión de aws-cdk-lib con la que son compatibles. En este caso, hemos fijado aws-codestar en la versión 2.0.0alpha1.

install_requires=[
     "aws-cdk-lib>=2.0.0",
     "constructs>=10.0.0",
     "aws-cdk.aws-codestar-alpha>=2.0.0alpha1",
     # ...
],
sugerencia

Desinstale cualquier otra versión de los módulos de AWS CDK que ya estén instalados en el entorno virtual de su aplicación con pip uninstall. A continuación, instale las dependencias nuevas con python -m pip install -r requirements.txt.

Cambie las importaciones de la aplicación para hacer lo siguiente:

  • Importe Construct a partir del nuevo módulo constructs

  • Importe los tipos básicos, como App y Stack, a partir del nivel superior de aws_cdk

  • Importe los módulos de la Biblioteca de constructos de AWS a partir de los espacios de nombres en aws_cdk 

from constructs import Construct
from aws_cdk import App, Stack                    # core constructs
from aws_cdk import aws_s3 as s3                  # stable module
import aws_cdk.aws_codestar_alpha as codestar     # experimental module

# ...

class MyConstruct(Construct):
    # ...

class MyStack(Stack):
    # ...

s3.Bucket(...)
Java

En pom.xml, elimine todas las dependencias software.amazon.awscdk de los módulos estables y sustitúyalas por las dependencias en software.constructs (para Construct) y software.amazon.awscdk.

Los constructos experimentales se proporcionan en paquetes separados y con versiones independientes, con nombres que terminan en alpha y un número de versión alfa. El número de versión alfa corresponde a la primera versión de aws-cdk-lib con la que son compatibles. En este caso, hemos fijado aws-codestar en la versión 2.0.0-alpha.1.

<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>aws-cdk-lib</artifactId>
    <version>2.0.0</version>
</dependency><dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>code-star-alpha</artifactId>
    <version>2.0.0-alpha.1</version>
</dependency>
<dependency>
    <groupId>software.constructs</groupId>
    <artifactId>constructs</artifactId>
    <version>10.0.0</version>
</dependency>

Instale las dependencias nuevas ejecutando mvn package.

Cambie el código para hacer lo siguiente:

  • Importe Construct a partir de la nueva biblioteca software.constructs

  • Importe las clases básicas, como Stack y App, a partir de software.amazon.awscdk

  • Importe constructos de servicios a partir de software.amazon.awscdk.services 

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.App;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.codestar.alpha.GitHubRepository;
C#

La forma más sencilla de actualizar las dependencias de una aplicación de CDK C# es editar el archivo .csproj manualmente. Elimine todas las referencias a los paquetes Amazon.CDK.* estables y sustitúyalas por referencias a los paquetes Amazon.CDK.Lib y Constructs.

Los constructos experimentales se proporcionan en paquetes separados y con versiones independientes, con nombres que terminan en alpha y un número de versión alfa. El número de versión alfa corresponde a la primera versión de aws-cdk-lib con la que son compatibles. En este caso, hemos fijado aws-codestar en la versión 2.0.0-alpha.1.

<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0" />
<PackageReference Include="Amazon.CDK.AWS.Codestar.Alpha" Version="2.0.0-alpha.1" />
<PackageReference Include="Constructs" Version="10.0.0" />

Instale las dependencias nuevas ejecutando dotnet restore.

Cambie las importaciones en los archivos de origen de la siguiente manera.

using Constructs;                   // for Construct class
using Amazon.CDK;                   // for core classes like App and Stack
using Amazon.CDK.AWS.S3;            // for stable constructs like Bucket
using Amazon.CDK.Codestar.Alpha;    // for experimental constructs
Go

Ejecute go get para actualizar sus dependencias a la última versión y el archivo .mod de su proyecto.

Prueba de la aplicación migrada antes de implementarla

Antes de implementar sus pilas, use cdk diff para revisar si hay cambios inesperados en los recursos. No se esperan los cambios en los ID lógicos (que provoquen la sustitución de recursos).

Estos son algunos de los cambios esperados:

  • Cambios en el recurso CDKMetadata.

  • Actualización de los hashes de los activos.

  • Cambios relacionados con el nuevo estilo de síntesis de pilas. Se aplica si su aplicación utilizaba el sintetizador de pilas antiguo de v1.

  • La adición de una regla CheckBootstrapVersion.

Por lo general, los cambios inesperados no se deben a la actualización a la versión 2 de AWS CDK en sí misma. En general, son el resultado de un comportamiento obsoleto que había sido modificado anteriormente con las marcas de características. Esto es un síntoma de una actualización desde una versión de CDK anterior a la versión 1.85.x. Vería los mismos cambios al pasar al lanzamiento más reciente de v1.x. En general, se puede resolver el error con la siguiente operación:

  1. Actualice su aplicación al lanzamiento más reciente de v1.x

  2. Elimine las marcas de características

  3. Revise su código según sea necesario

  4. Implementación

  5. Realice la actualización a v2

nota

Si la aplicación actualizada no se puede implementar después de la actualización en dos etapas, notifique el problema.

Cuando esté listo para implementar las pilas en su aplicación, considere la posibilidad de implementar primero una copia para poder probarla. La manera más sencilla de hacerlo es implementarla en una región diferente. Sin embargo, también puede cambiar los ID de sus pilas. Después de la prueba, asegúrese de destruir la copia de prueba con cdk destroy.

Solución de problemas

Error 'from' expected o ';' expected de TypeScript en las importaciones

Realice la actualización a TypeScript 3.8 o una versión posterior.

Ejecute “cdk bootstrap'

Si ve un error similar al siguiente:

❌  MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
    at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)

AWS CDK v2 requiere una pila de arranque actualizada y, además, todas las implementaciones de la versión 2 requieren recursos de inicio. (Con v1, puede implementar pilas sencillas sin el arranque). Para obtener información completa, consulte Arranque de AWS CDK.

Búsqueda de pilas con v1

Al migrar su aplicación de CDK de v1 a v2, es posible que desee identificar las pilas de AWS CloudFormation implementadas que se crearon con v1. Para ello, ejecute el siguiente comando:

npx awscdk-v1-stack-finder

Para obtener información sobre el uso, consulte el archivo README awscdk-v1-stack-finder.