Esta es la segunda versión de la Guía para desarrolladores de AWS CDK. 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.
Control de versiones de AWS CDK
Este tema ofrece información de referencia acerca de cómo AWS Cloud Development Kit (AWS CDK) gestiona el control de versiones.
Los números de versiones constan de tres partes numéricas de la versión: major.minor.patch, y siga en general los principios del control de versiones semánticas
Las versiones secundarias y los parches son compatibles con versiones anteriores. El código escrito en una versión anterior con la misma versión principal se puede actualizar a una versión más reciente dentro de la misma versión principal. Continuará con el compilado y la ejecución, lo que dará un resultado funcionalmente equivalente. En algunos casos de uso avanzados, será necesario realizar pequeños cambios en el código, tal y como se indica en el siguiente tema.
Compatibilidad con el kit de herramientas de AWS CDK
Cada versión de la biblioteca de constructos de AWS (aws-cdk-lib) es compatible con las versiones de la CLI del kit de herraminetas (aws-cdk-cli) y la biblioteca del kit de herramientas (@aws-cdk/toolkit-lib) del AWS CDK que estaban vigentes en el momento del lanzamiento de la biblioteca de constructos de AWS. También es compatible con cualquier versión más reciente del kit de herramientas de AWS CDK. Cada versión de la biblioteca de constructos de AWS mantiene esta compatibilidad hasta la fecha de fin de vida útil de la biblioteca. Por lo tanto, siempre que utilice una versión compatible de la biblioteca de constructos de AWS, siempre es seguro actualizar su versión del kit de herramientas de AWS CDK.
Es posible que cada versión de la biblioteca de constructos de AWS también funcione con versiones del kit de herramientas de AWS CDK anteriores a la versión actual en el momento del lanzamiento de la biblioteca de constructos de AWS. Sin embargo, esto no se garantiza. La compatibilidad depende de la versión del esquema de ensamblaje en la nube de la biblioteca de constructos de AWS. El AWS CDK genera un ensamblaje en la nube durante la síntesis y el kit de herramientas de AWS CDK lo consume para su implementación. El esquema que define el formato del ensamblaje en la nube está estrictamente especificado y versionado. Por lo tanto, una versión anterior del kit de herramientas del AWS CDK tendría que ser compatible con la versión del esquema de ensamblaje en la nube de la biblioteca de constructos de AWS para que fuera compatible.
Cuando la versión de ensamblaje en la nube requerida por la biblioteca de constructos de AWS no es compatible con la versión compatible con el kit de herramientas de AWS CDK, recibirá un mensaje de error como el siguiente:
Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0. Please upgrade your CLI in order to interact with this app.
Para resolver este error, actualice el kit de herramientas de AWS CDK a una versión compatible con la versión de ensamblaje en la nube requerida o a la última versión disponible. Por lo general, no se recomienda la alternativa (degradar los módulos de la biblioteca de constructos de AWS que utiliza la aplicación).
nota
Para obtener más información sobre las combinaciones exactas de versiones que funcionan juntas, consulte la tabla de compatibilidad
Control de versiones de la Biblioteca de constructos de AWS
Los módulos de la Biblioteca de constructos de AWS pasan por varias etapas a medida que se desarrollan desde el concepto hasta la API madura. Las diferentes etapas ofrecen diversos grados de estabilidad de la API en las versiones posteriores de AWS CDK.
Excepto en los casos en los que se aplican las advertencias descritas en el siguiente tema, las API de la biblioteca principal de construcctos de AWS (aws-cdk-lib) son estables y, en líneas generales, la biblioteca sigue los principios de control de versiones semántico. La biblioteca incluye constructos de AWS CloudFormation (nivel 1) para todos los servicios de AWS, que se generan automáticamente a partir de los esquemas de los proveedores de recursos de CloudFormation y, en ocasiones, pueden incluir actualizaciones incompatibles con versiones anteriores. También incluye constructos de nivel superior (nivel 2 y nivel 3) y las principales clases de CDK, como App y Stack, que son todas estables. Las API no se eliminarán de este paquete (aunque es posible que estén en desuso) hasta la próxima versión principal de CDK. Cuando se requiera un cambio importante en una API estable, se agregará una API completamente nueva.
Las nuevas API que se desarrollen para un servicio ya incorporado en aws-cdk-lib se identifican mediante un sufijo Beta<N>, en donde N comienza en 1 y se incrementa con cada cambio importante que se realice en la nueva API. Beta<N> Las API nunca se eliminan, solo quedan en desuso, por lo que la aplicación actual sigue funcionando con las versiones más recientes de la aws-cdk-lib. Cuando la API se considera estable, se agrega una nueva API sin el sufijo Beta<N>.
Cuando las API de nivel superior (L2 o L3) comienzan a desarrollarse para un servicio de AWS que antes solo tenía API de L1, esas API se distribuyen inicialmente en un paquete independiente. El nombre de dicho paquete tiene el sufijo “Alpha” y su versión coincide con la primera versión de la aws-cdk-lib que es compatible con una subversión de alpha. Cuando el módulo admite los casos de uso previstos, se agregan sus API a la aws-cdk-lib.
Aclaraciones sobre el versionado semántico de la biblioteca de constructos de AWS
Si bien la biblioteca de constructos de AWS sigue en líneas generales los principios del control de versiones semántico, hay algunas advertencias importantes específicas de nuestra implementación. En general, la biblioteca de constructos de AWS mantiene la estabilidad para los consumidores de API, pero a veces añade cargas adicionales a los autores de las compilaciones para permitir la necesaria evolución del marco.
-
Cambios que afectan a la seguridad
Para cumplir con los requisitos de seguridad, es posible que tengamos que cambiar las API de formas incompatibles con versiones anteriores o eliminarlas por completo. Esto evita que se utilicen las API afectadas y obliga a actualizar las implementaciones.
-
Las características se describen por intención
Nuestro objetivo es minimizar los cambios inesperados, pero preferimos la intención antes que la estabilidad de la implementación. La biblioteca de constructos de AWS no garantiza que las construcciones siempre se sinteticen exactamente en la misma plantilla de CloudFormation ni que utilicen exactamente el mismo conjunto de recursos. Esto se aplica especialmente a los constructos de nivel superior, en las que a menudo se puede lograr el mismo objetivo de diferentes maneras.
-
Implementación de interfaces y clases abstractas
Las interfaces y las clases abstractas de la biblioteca de constructos de AWS son estables para los consumidores, pero no para los implementadores. Esto significa que puede confiar en que las interfaces le proporcionarán
s3.IBucketal menos la misma funcionalidad que en el momento (versión de la biblioteca de constructos de AWS) en que comenzó a consumir la interfaz o la clase abstracta. Sin embargo, de forma periódica, se añadirán nuevos miembros (abstractos) a las interfaces y clases abstractas. Para cualquiera que los implemente, esto supone una carga de implementación adicional que debe tenerse en cuenta a la hora de realizar la actualización, ya que la implementación no estaría implementando los miembros nuevos todavía. Tratar estrictamente las adiciones a las interfaces y clases abstractas para los implementadores como cambios importantes limitaría indebidamente la capacidad de evolución de la biblioteca de constructos de AWS. En la mayoría de los casos, los implementadores deberían preferir extender clases concretas comos3.Bucket. -
Constructos de nivel 1, código generado y otras API marcadas como externas
Algunas partes de la biblioteca de constructos de AWS se generan a partir de fuentes de datos que provienen directamente de los servicios de AWS. Para mantener estas API alineadas con la realidad, el código generado puede contener cambios incompatibles con las versiones anteriores. La mayoría de las veces, las fuentes de datos se actualizan para reflejar de forma correcta la realidad y corregir la representación incorrecta. El IntelliSense de su IDE mostrará las API externas con la anotación
@stability — external. -
Enlaces específicos de idioma
En un número muy limitado de situaciones, los enlaces de idiomas pueden contener cambios incompatibles con versiones anteriores. Se deben a cambios tipográficos iniciales que son compatibles con versiones anteriores en otros idiomas admitidos. Se permiten estos cambios de tipos, ya que de lo contrario se limitaría de forma considerable la capacidad de evolución de la biblioteca.
En la siguiente lista, se describen todas las instancias conocidas:
-
Golang: cambiar de un sector mecanografiado a cualquier sector: una lista de un solo tipo se convierte en una lista de varios tipos (tipos de unión en TypeScript). En
Go, se escriben como una porción de cualquiera (*[]any). Debido a las reglas de asignación de escritura de Go, cambiar de*[]stringano es una conversión automática. Por lo tanto, esta ampliación de tipos requiere un cambio en el código de consumo. Consulte Cómo trabajar con cualquier porción para ver las estrategias.
-
Estabilidad de la vinculación de lenguajes
Con el tiempo, podríamos agregar soporte a AWS CDK para otros lenguajes de programación. Si bien la API descrita en todos los lenguajes es la misma, la forma en que se expresa varía según el lenguaje y puede cambiar a medida que evolucione la compatibilidad del lenguaje. Por este motivo, los enlaces de leguaje se tratan como experimentales durante un tiempo hasta que se considere que están listos para su uso en producción.
| Idioma | Stability |
|---|---|
|
TypeScript |
Stable |
|
JavaScript |
Stable |
|
Python |
Stable |
|
Java |
Stable |
|
C#/.NET |
Stable |
|
Go |
Stable |
