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 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 de 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 un solo paquete 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 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 sufijoalpha
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 AWS Construct con la que son compatibles, y también incluye un sufijo.alpha
Los constructos pasan aaws-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 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 aaws-cdk-lib
cuando consideramos que los nuevos constructos satisfacen las necesidades fundamentales de los clientes.Una vez que un módulo ha sido designado estable e incorporado
aws-cdk-lib
, APIs se añaden nuevos módulos utilizando 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 añade una nueva funcionalidad, los nuevos APIs (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 ellos. (Se agregaBeta2
,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á comograntPowerBeta1()
. Si se necesitan cambios importantes (por ejemplo, nuevos parámetros o propiedades obligatorios), se asignará el nombregrantPowerBeta2()
a la siguiente versión del método y así sucesivamente. Una vez finalizado el trabajo y la API, se agrega el métodograntPower()
(sin sufijo), y los métodos BetaN quedan obsoletos.Todas las versiones beta APIs permanecerán en la biblioteca Construct hasta el lanzamiento de la próxima versión principal (3.0) y sus características 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 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 constructos en otros dominios. Si escribes tus propias construcciones o utilizas componentes relacionados APIs, debes declarar elconstructs
módulo como una dependencia y realizar pequeños cambios 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, métodos y tipos obsoletos de la AWS CDK versión 1.x y su biblioteca de construcciones se han eliminado por completo de la API de CDK v2. En la mayoría de los lenguajes compatibles, aparecen advertencias en la APIs versión 1.x, por lo que es posible que ya hayas migrado a la versión de reemplazo. APIs Encontrará una lista completa de los productos obsoletos de
la versión 1.x de CDK APIs 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 el CDK v2. 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 bootstrap moderna concede de forma efectiva los permisos implícitos --cloudformation-execution-policies
a cualquier AWS cuenta de 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 para la AWS CDK versión 2 son los mismos que para la AWS CDK versión 1.x. Aquí se enumeran los requisitos adicionales.
-
Para TypeScript los desarrolladores, se requiere la TypeScript versión 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 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ícelas a 2.0.0
y, a continuación, actualice los módulos instalados en su proyecto.
npm install
o yarn install
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 a la AWS CDK versión 2 del CDK
Para migrar su aplicación a la AWS CDK versión 2, primero actualice las marcas de funciones. 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
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, 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 de la versión 1, cdk.json
si existen, ya que todas están activas 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. Consulta la lista de banderas activadas GitHub
-
@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 Restablecer al comportamiento de la v1 o consulte la lista 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 de 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 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
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.
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.
Tú decides cuánto tiempo quieres seguir prestando asistencia 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 AWS CDK
Maintenance Policy
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
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 cambios en la lógica IDs (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 AWS CDK versión 2 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:
-
Actualice su aplicación al lanzamiento más reciente de v1.x
-
Elimine las marcas de características
-
Revise su código según sea necesario
-
Implementación
-
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 puedes cambiar IDs las pilas. Después de la prueba, asegúrese de destruir la copia de prueba con cdk destroy.
Solución de problemas
TypeScript 'from' expected
o ';' expected
error en las importaciones
Actualice 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 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 v1, puede implementar pilas sencillas sin el arranque). Para ver todos los detalles, consulte AWS CDK arranque.
Búsqueda de pilas con v1
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