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.
AWS Control de versiones de CDK
En este tema se proporciona información de referencia sobre cómo el 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.
AWS Compatibilidad con CDK Toolkit
Cada versión de la biblioteca AWS Construct principal (aws-cdk-lib) es compatible con las versiones CLI (aws-cdk-cli) y Toolkit Library (@aws-cdk/toolkit-lib) del AWS CDK Toolkit que estaban vigentes en el momento del lanzamiento de la biblioteca AWS Construct. También es compatible con cualquier versión más reciente del kit de herramientas del AWS CDK. Cada versión de la biblioteca AWS Construct 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 AWS Construct Library, siempre es seguro actualizar su versión del AWS CDK Toolkit.
Es posible que cada versión de la biblioteca AWS Construct también funcione con versiones del AWS CDK Toolkit anteriores a la versión actual en el momento del lanzamiento de la biblioteca AWS Construct. Sin embargo, esto no se garantiza. La compatibilidad depende de la versión del esquema de ensamblaje en la nube de la biblioteca AWS Construct. La AWS CDK genera un ensamblaje de nubes durante la síntesis y el kit de herramientas de la 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 AWS Construct para que fuera compatible.
Cuando la versión de ensamblaje en nube requerida por la biblioteca AWS Construct no es compatible con la versión compatible con el kit de herramientas del 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 del AWS CDK a una versión compatible con la versión de Cloud Assembly requerida o a la última versión disponible. Por lo general, no se recomienda la alternativa (degradar los módulos de AWS Construct Library que usa tu aplicación).
nota
Para obtener más información sobre las combinaciones exactas de versiones que funcionan juntas, consulta la tabla de compatibilidad
AWS Construya el control de versiones de la biblioteca
Los módulos de la biblioteca AWS Construct pasan por varias etapas a medida que se desarrollan desde el concepto hasta la API madura. Las distintas etapas ofrecen distintos grados de estabilidad de la API en las versiones posteriores de la AWS CDK.
Excepto en los casos en los que se aplican las advertencias descritas en el siguiente tema, APIs en la biblioteca principal de AWS Construct (aws-cdk-lib) son estables y, en líneas generales, la biblioteca sigue los principios del control de versiones semántico. La biblioteca incluye construcciones AWS CloudFormation (L1) para todos los AWS servicios, que se generan automáticamente a partir de los esquemas de los proveedores de CloudFormation recursos y, en ocasiones, pueden incluir actualizaciones incompatibles con versiones anteriores. También incluye construcciones de nivel superior (L2 y L3) y las clases principales de CDK, como y, que son todas estables. App Stack APIs no se eliminarán de este paquete (aunque podrían quedar en desuso) hasta la próxima versión principal del CDK. Cuando se requiera un cambio importante en una API estable, se agregará una API completamente nueva.
Las novedades en APIs fase de desarrollo para un servicio ya incorporado aws-cdk-lib se identifican mediante un Beta<N> sufijo, que N comienza en 1 y se incrementa con cada cambio importante que se realice en la nueva API. Beta<N> APIs nunca se eliminan, solo están en desuso, por lo que tu aplicación actual sigue funcionando con las versiones más recientes de. aws-cdk-lib Cuando la API se considera estable, se agrega una nueva API sin el sufijo Beta<N>.
Cuando se APIs empieza a desarrollar un nivel superior (L2 o L3) para un AWS servicio que anteriormente solo tenía el nivel 1 APIs, estos APIs 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 añaden los suyos APIs . aws-cdk-lib
AWS Aclaraciones sobre el versionado semántico de Construct Library
Si bien la biblioteca AWS Construct sigue en líneas generales los principios de control de versiones semántico, hay algunas advertencias importantes específicas de nuestra implementación. En general, la biblioteca AWS Construct 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 nuestros requisitos de seguridad, es posible que tengamos que APIs cambiarlos de formas incompatibles con versiones anteriores o eliminarlos por completo. Esto evita que se utilicen los afectados APIs 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 AWS Construct no garantiza que las construcciones se sinteticen siempre siguiendo exactamente la misma CloudFormation plantilla 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 AWS Construct son estables para los consumidores, pero no para los implementadores. Esto significa que puede confiar en que las interfaces proporcionan
s3.IBucketal menos la misma funcionalidad que en el momento (versión de AWS Construct Library) 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 Construct. AWS En la mayoría de los casos, los implementadores deberían preferir extender clases concretas comos3.Bucket. -
Construcciones de nivel 1, código generado y otros elementos marcados como externos APIs
Algunas partes de la biblioteca AWS Construct se generan a partir de fuentes de datos que provienen directamente de AWS los servicios. Para mantenerlos APIs alineados con la realidad, el código generado puede contener cambios incompatibles con 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. Los IDE IntelliSense se mostrarán de forma externa APIs con la
@stability — externalanotación. -
Solo programas semánticamente correctos
Nos aseguramos de que los programas correctos sigan funcionando con las versiones más recientes. No se incluyen los programas que son formalmente incorrectos pero que funcionan debido a los detalles de implementación. Por ejemplo, si su programa se basa en las reglas TypeScript de escritura estructural
para pasar tipos de objetos inesperados, o si lo sintetiza correctamente pero produce una CloudFormation plantilla que no se puede implementar, podemos introducir cambios que provoquen que estos programas fallen sin considerarlos cambios importantes. -
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 uno cualquiera: una lista de un solo tipo se convierte en una lista de varios tipos (en los tipos de unión). 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 añadir soporte a la AWS CDK para lenguajes de programación adicionales. 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 |
