Migración de la AWS CDK versión 1 a la versión 2 AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
Nuevos requisitos previosActualización desde la AWS CDK versión 2 Developer PreviewMigración de la versión 1 a la versión 2 del CDK AWS CDKProbar la aplicación migrada antes de implementarlaSolución de problemas¿Cómo encontrar pilas de la versión 1

Esta es la guía para AWS CDK desarrolladores de la versión 2. La versión anterior del CDK v1 entró en mantenimiento el 1 de junio de 2022 y dejó de ofrecer soporte el 1 de junio de 2023.

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

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

La versión 2 de AWS Cloud Development Kit (AWS CDK) está diseñada para facilitar la escritura de la 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 del AWS CDK.

sugerencia

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

Los principales cambios de la versión 1 a la versión 2 de CDK son los siguientes. AWS CDK

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

    Las construcciones L1 (CFNxxxx), que representan los recursos exactos disponibles, siempre se consideran estables y, por lo tanto AWS CloudFormation, se incluyen en ellas. aws-cdk-lib

  • Los módulos experimentales, en los que seguimos trabajando con la comunidad para desarrollar nuevas construcciones de nivel 2 o nivel 3, no están incluidos. aws-cdk-lib En cambio, se distribuyen como paquetes individuales. Los paquetes experimentales se nombran con un alpha sufijo y un número de versión semántico. El número de versión semántica coincide con la primera versión de la biblioteca AWS Construct con la que son compatibles, también con un sufijo. alpha Las construcciones pasan a aws-cdk-lib ser designadas estables, lo que permite que la biblioteca de construcciones principal siga un estricto control de versiones semántico.

    La estabilidad se especifica a nivel de servicio. Por ejemplo, si empezamos a crear una o más construcciones de L2 para Amazon AppFlow, que al momento de escribir este artículo solo tiene construcciones de L1, aparecen primero en un módulo denominado. @aws-cdk/aws-appflow-alpha Luego, pasan a un aws-cdk-lib momento en el que consideramos que los nuevos diseños satisfacen las necesidades fundamentales de los clientes.

    Una vez que un módulo se ha designado estable y se ha incorporado a élaws-cdk-lib, se añaden nuevas API mediante la convención «BetAN» que se describe en el siguiente bullet.

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

  • En el caso de los módulos estables a los que se añade una nueva funcionalidad, las API nuevas (ya se trate de construcciones completamente nuevas o de métodos o propiedades nuevas de una construcción existente) reciben un Beta1 sufijo mientras se está trabajando en ellas. (Seguido de Beta2Beta3, y así sucesivamente cuando sea necesario realizar cambios importantes). Cuando la API se designa 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 añadimos un método nuevo grantPower() a una construcción, inicialmente aparecerá comograntPowerBeta1(). Si se necesitan cambios importantes (por ejemplo, un nuevo parámetro o propiedad obligatorio), se asignará un nombre grantPowerBeta2() a la siguiente versión del método y así sucesivamente. Una vez finalizado el trabajo y finalizada la API, se añade el método grantPower() (sin sufijo) y los métodos betAN quedan obsoletos.

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

  • La Construct clase se ha extraído de AWS CDK una biblioteca independiente, junto con los tipos relacionados. Esto se hace para apoyar los esfuerzos por aplicar el modelo de programación de Construct a otros dominios. Si está escribiendo sus propias construcciones o utiliza API relacionadas, debe declarar el constructs módulo como una dependencia y realizar cambios menores en las importaciones. Si utilizas funciones avanzadas, como conectarte al ciclo de vida de la aplicación CDK, es posible que necesites realizar más cambios. Para obtener más información, consulta la RFC.

  • Las propiedades, métodos y tipos obsoletos de la AWS CDK versión 1.x y su biblioteca Construct se han eliminado por completo de la API de CDK v2. En la mayoría de los lenguajes compatibles, estas API generan advertencias en la versión 1.x, por lo que es posible que ya hayas migrado a las API de reemplazo. Encontrará una lista completa de las API obsoletas de la versión 1.x de CDK en. GitHub

  • El comportamiento que estaba restringido por indicadores de características en la versión AWS CDK 1.x está activado de forma predeterminada en la versión CDK v2. Los indicadores de características anteriores ya no son necesarios y, en la mayoría de los casos, no son compatibles. Algunas todavía están disponibles para que puedas volver al comportamiento de la versión CDK v1 en circunstancias muy específicas. Para obtener más información, consulte Actualizar los indicadores de funciones.

  • Con CDK v2, los entornos en los que se despliega deben arrancarse con la moderna pila de bootstrap. La pila de bootstrap antigua (la predeterminada en la versión 1) ya no es compatible. Además, CDK v2 requiere una nueva versión de la pila moderna. Para actualizar sus entornos existentes, vuelva a iniciarlos. Ya no es necesario establecer ningún indicador de función o variable de entorno para utilizar la pila de bootstrap moderna.

importante

La plantilla bootstrap moderna concede de forma efectiva los permisos implícitos --cloudformation-execution-policies a cualquier AWS cuenta de la --trust lista. De forma predeterminada, esto extiende los permisos de lectura y escritura a cualquier recurso de la cuenta de arranque. 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 AWS CDK versión 2 son los mismos que los de la AWS CDK versión 1.x. Los requisitos adicionales se enumeran aquí.

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

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

Actualización desde la AWS CDK versión 2 Developer Preview

Si utilizas la versión preliminar para desarrolladores de CDK v2, tu proyecto depende de una versión Release Candidate de AWS CDK, por ejemplo. 2.0.0-rc1 Actualízalas a los módulos instalados en tu proyecto y2.0.0, a continuación, actualiza los módulos instalados en tu proyecto.

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

Tras actualizar las dependencias, actualice el kit de herramientas del CDK a la versión de lanzamiento. npm update -g aws-cdk

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

Para migrar su aplicación a la AWS CDK versión 2, primero actualice las marcas de funciones. cdk.json A continuación, actualiza las dependencias e importaciones de la aplicación según sea necesario para el lenguaje de programación en el que está escrita.

¿Se está actualizando a una versión reciente

Estamos viendo que varios clientes se están actualizando de una versión antigua de la versión AWS CDK 1 a la versión más reciente de la versión 2 en un solo paso. Si bien es cierto que es posible hacerlo, estarías actualizando después de 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 las fuentes de cualquier cambio inesperado, le recomendamos que separe estos dos pasos: primero actualice a la última versión v1 y, a continuación, realice el cambio a la v2.

Actualizar los indicadores de funciones

Elimine los siguientes indicadores de características de la versión 1, cdk.json si existen, ya que están todos activos de forma predeterminada en la AWS CDK versión 2. Si su efecto anterior es importante para su infraestructura, tendrá que realizar cambios en el código fuente. Consulte la lista de banderas 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 algunos indicadores de características de la versión 1 para false volver a comportamientos específicos de la versión AWS CDK 1; consulte Volviendo al comportamiento de la versión 1 o consulte la lista GitHub para obtener una referencia completa.

Para ambos tipos de indicadores, utilice el cdk diff comando para inspeccionar los cambios en la plantilla sintetizada y comprobar si los cambios en alguno de estos indicadores afectan a su infraestructura.

Compatibilidad con el kit de herramientas CDK

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

Si necesita crear proyectos de CDK tanto de la versión 1 como de la versión 2, no instale el CDK Toolkit v2 de forma global. (Quítelo si ya lo tiene instalado:.) npm remove -g aws-cdk Para invocar el kit de herramientas del CDK, utilícelo npx para ejecutar la versión 1 o la versión 2 del kit de herramientas del 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 cdk1 comandos cdk y para invocar la versión deseada del kit de herramientas del 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

Actualiza las dependencias de tu aplicación y, a continuación, instala los nuevos paquetes. Por último, actualiza las importaciones en tu código.

TypeScript
Aplicaciones

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

Las construcciones experimentales se proporcionan en paquetes separados y con versiones independientes con nombres que terminan en alpha y un número de versión alfabético. El número de versión alfa corresponde a la primera versión aws-cdk-lib con la que son compatibles. En este caso, hemos fijado la versión aws-codestar 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"
  }
}
Construye bibliotecas

Para crear bibliotecas, establezca la versión más baja aws-cdk-lib que necesite para su aplicación (aquí la 2.0.0) y actualícela de la package.json 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 publiques una biblioteca compatible con la versión 2, deberías introducir un cambio importante en el número de versión de tu biblioteca, ya que se trata de un cambio radical para los usuarios de la biblioteca. No es posible admitir tanto la versión 1 como la versión 2 de CDK con una sola biblioteca. Para seguir dando soporte a los clientes que aún utilizan la versión 1, puede mantener la versión anterior en paralelo o crear un paquete nuevo para la versión 2.

Tú decides cuánto tiempo quieres seguir ofreciendo soporte a los clientes de la AWS CDK versión 1. Puede seguir el ejemplo del ciclo de vida del propio CDK v1, que entró en mantenimiento el 1 de junio de 2022 y estará operativo el 1 de end-of-life junio de 2023. Para obtener más información, consulte la Política de AWS CDK mantenimiento.

Tanto bibliotecas como aplicaciones

Instale las nuevas dependencias ejecutando npm install oyarn install.

Cambie sus importaciones para importar Construct desde el nuevo constructs módulo, los tipos principales, como App y Stack desde el nivel superioraws-cdk-lib, y los módulos estables de Construct Library para los servicios que utilice desde los espacios de nombres de abajo. 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 de la siguiente package.json manera. Elimine las dependencias de los módulos estables individuales de estilo v1 y establezca la versión más baja aws-cdk-lib que necesite para su aplicación (aquí la versión 2.0.0).

Las construcciones experimentales se proporcionan en paquetes separados y con versiones independientes con nombres que terminan en alpha y un número de versión alfabético. El número de versión alfa corresponde a la primera versión aws-cdk-lib con la que son compatibles. En este caso, hemos fijado la versión aws-codestar 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 nuevas dependencias ejecutando o. npm install yarn install

Cambia las importaciones de tu aplicación para hacer lo siguiente:

  • Importa Construct desde el nuevo constructs módulo

  • Importe los tipos principales, como App yStack, desde el nivel superior de aws-cdk-lib

  • Importe los módulos de AWS Construct Library desde los espacios de nombres de 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 la install_requires definición de la siguiente setup.py manera. Elimine las dependencias de los módulos estables individuales de estilo v1.

Las construcciones experimentales se proporcionan en paquetes separados y con versiones independientes con nombres que terminan en alpha y un número de versión alfabético. El número de versión alfa corresponde a la primera versión aws-cdk-lib con la que son compatibles. En este caso, hemos fijado la versión aws-codestar 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 AWS CDK módulos que ya estén instalados en el entorno virtual de su aplicación utilizando. pip uninstall A continuación, instale las nuevas dependencias conpython -m pip install -r requirements.txt.

Cambia las importaciones de tu aplicación para hacer lo siguiente:

  • Importa Construct desde el nuevo constructs módulo

  • Importe los tipos principales, como App yStack, desde el nivel superior de aws_cdk

  • Importe los módulos de AWS Construct Library desde los espacios de nombres de 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

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

Las construcciones experimentales se proporcionan en paquetes separados y versionados de forma independiente con nombres que terminan en alpha y un número de versión alfabético. El número de versión alfa corresponde a la primera versión aws-cdk-lib con la que son compatibles. En este caso, hemos fijado la versión aws-codestar 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>

Instala las nuevas dependencias ejecutándolas. mvn package

Cambie el código para hacer lo siguiente:

  • Importa Construct desde la nueva software.constructs biblioteca

  • Importa las clases principales, como Stack y App desde software.amazon.awscdk

  • Importe construcciones de servicios desde 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 CDK de C# es editar el archivo manualmente. .csproj Elimine todas las referencias de Amazon.CDK.* paquetes estables y sustitúyalas por referencias a los Amazon.CDK.Lib paquetes y. Constructs

Las construcciones experimentales se proporcionan en paquetes separados y con versiones independientes con nombres que terminan en alpha y un número de versión alfabético. El número de versión alfa corresponde a la primera versión aws-cdk-lib con la que son compatibles. En este caso, hemos fijado la versión aws-codestar 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" />

Instala las nuevas dependencias ejecutándolas. dotnet restore

Cambie las importaciones en sus archivos fuente 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 este error go get para actualizar sus dependencias a la última versión y actualizar el .mod archivo de su proyecto.

Probar la aplicación migrada antes de implementarla

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

Los cambios esperados incluyen, pero no se limitan a:

  • Cambios en el CDKMetadata recurso.

  • Se han actualizado los hashes de los activos.

  • Cambios relacionados con el nuevo estilo de síntesis de pilas. Se aplica si tu aplicación utilizaba el sintetizador de pilas antiguo de la versión 1. (El CDK v2 no es compatible con el sintetizador de pilas anterior).

  • La adición de una regla. CheckBootstrapVersion

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

  1. Actualiza tu aplicación a la versión más reciente, la versión 1.x

  2. Elimina los indicadores de funciones

  3. Revisa tu código según sea necesario

  4. Implementación

  5. Actualice a la versión 2

nota

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

Cuando esté listo para implementar las pilas en su aplicación, considere implementar primero una copia para poder probarla. La forma más sencilla de hacerlo es implementarla en una región diferente. Sin embargo, también puedes cambiar los ID de tus pilas. Tras la prueba, asegúrate de destruir la copia de prueba con cdk destroy ella.

Solución de problemas

TypeScript 'from' expectedo ';' expected error en las importaciones

Actualice a TypeScript 3.8 o una versión posterior.

Ejecute 'cdk bootstrap'

Si ve un error como el 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 La versión 2 requiere una pila de arranque actualizada y, además, todas las implementaciones de la versión 2 requieren recursos de arranque. (Con la versión 1, puede implementar pilas sencillas sin necesidad de arrancar). Para ver todos los detalles, consulte Bootstrapping (Proceso de arranque).

¿Cómo encontrar pilas de la versión 1

Al migrar su aplicación de CDK de la versión 1 a la versión 2, es posible que desee identificar las AWS CloudFormation pilas implementadas que se crearon con la versión 1. 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.