Esta es la guía para AWS CDK desarrolladores de la versión 2. La CDK versión anterior entró en mantenimiento el 1 de junio de 2022 y finalizó el 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.

Mejores prácticas para desarrollar e implementar una infraestructura de nube con AWS CDK

Con él AWS CDK, los desarrolladores o administradores pueden definir su infraestructura de nube mediante un lenguaje de programación compatible. CDKlas aplicaciones deben organizarse en unidades lógicas, como API bases de datos y recursos de monitoreo, y, opcionalmente, tener una canalización para las implementaciones automatizadas. Las unidades lógicas deben implementarse como construcciones que incluyan las siguientes:

Las pilas definen el modelo de despliegue de estas unidades lógicas. Para obtener una introducción más detallada a los conceptos en los que se basaCDK, consulteCómo empezar con el AWS CDK.

Esto AWS CDK refleja una cuidadosa consideración de las necesidades de nuestros clientes y equipos internos y de los patrones de falla que suelen surgir durante el despliegue y el mantenimiento continuo de aplicaciones en la nube complejas. Descubrimos que los fallos suelen estar relacionados con «out-of-band» cambios en una aplicación que no se han probado completamente, como los cambios de configuración. Por lo tanto, lo desarrollamos en AWS CDK torno a un modelo en el que toda la aplicación se define en código, no solo la lógica empresarial, sino también la infraestructura y la configuración. De esta forma, los cambios propuestos pueden revisarse detenidamente, probarse exhaustivamente en entornos que se asemejen en mayor o menor medida a los de producción y revertirse por completo si algo sale mal.

En el momento de la implementación, AWS CDK sintetiza un conjunto de nubes que contiene lo siguiente:

Con élCDK, cada confirmación de la rama principal de control de versiones de la aplicación puede representar una versión completa, coherente y desplegable de la aplicación. De este modo, la aplicación se puede implementar automáticamente cada vez que se realice un cambio.

La filosofía en la que se basa nos AWS CDK lleva a nuestras mejores prácticas recomendadas, que hemos dividido en cuatro amplias categorías.

Prácticas recomendadas de organizaciones

En las etapas iniciales de AWS CDK la adopción, es importante considerar cómo configurar su organización para el éxito. Una buena práctica es contar con un equipo de expertos que se encargue de formar y guiar al resto de la empresa a medida que vaya adoptándolaCDK. El tamaño de este equipo puede variar, desde una o dos personas en una empresa pequeña hasta un centro de excelencia en la nube completo (CCoE) en una empresa más grande. Este equipo es responsable de establecer normas y políticas para la infraestructura de nube de su empresa, y también de formar y asesorar a los desarrolladores.

CCoEPodrían proporcionar orientación sobre los lenguajes de programación que se deben usar para la infraestructura de nube. Los detalles varían de una organización a otra, pero una buena política ayuda a garantizar que los desarrolladores puedan entender y mantener la infraestructura de nube de la empresa.

CCoETambién crea una «landing zone» que define las unidades organizativas en las que se encuentran AWS. Una landing zone es un AWS entorno multicuenta preconfigurado, seguro, escalable y basado en planes de mejores prácticas. Para unir los servicios que componen tu landing zone, puedes usar AWS Control Tower, que configura y administra todo tu sistema de cuentas múltiples desde una única interfaz de usuario.

Los equipos de desarrollo deberían poder usar sus propias cuentas para realizar pruebas e implementar nuevos recursos en estas cuentas según sea necesario. Los desarrolladores individuales pueden tratar estos recursos como extensiones de su propia estación de trabajo de desarrollo. Con CDKPipelines, las AWS CDK aplicaciones se pueden implementar a través de una cuenta de CI/CD en entornos de prueba, integración y producción (cada uno aislado en su propia AWS región o cuenta). Para ello, se fusiona el código de los desarrolladores en el repositorio canónico de la organización.

Mejores prácticas de codificación

En esta sección se presentan las prácticas recomendadas para organizar el AWS CDK código. El siguiente diagrama muestra la relación entre un equipo y los repositorios de código, los paquetes, las aplicaciones y las bibliotecas de construcción de ese equipo.

Comience de forma sencilla y añada complejidad solo cuando la necesite

El principio rector de la mayoría de nuestras mejores prácticas es mantener las cosas lo más sencillas posible, pero no más sencillas. Añada complejidad solo cuando sus requisitos exijan una solución más complicada. Con ella AWS CDK, puede refactorizar el código según sea necesario para adaptarlo a los nuevos requisitos. No es necesario que diseñe por adelantado todos los escenarios posibles.

Alinéese con el marco de AWS Well-Architected

El AWS Well-Architected Framework define un componente como el código, la configuración AWS y los recursos que, en conjunto, cumplen con un requisito. El componente suele ser la unidad de responsabilidad técnica y está desacoplado de otros componentes. El término carga de trabajo se usa para identificar un grupo de componentes que, en conjunto, proporcionan valor de negocio. La carga de trabajo suele ser el nivel de detalle sobre el que hablan los líderes tecnológicos y comerciales.

Una AWS CDK aplicación se asigna a un componente según lo definido por el AWS Well-Architected Framework. AWS CDK las aplicaciones son un mecanismo para codificar y ofrecer las mejores prácticas de aplicaciones en la nube de Well-Architected. También puede crear y compartir componentes como bibliotecas de códigos reutilizables a través de repositorios de artefactos, como. AWS CodeArtifact

Cada aplicación comienza con un único paquete en un único repositorio

Un solo paquete es el punto de entrada de tu AWS CDK aplicación. Aquí, usted define cómo y dónde implementar las diferentes unidades lógicas de su aplicación. También debe definir la canalización de CI/CD para implementar la aplicación. Las estructuras de la aplicación definen las unidades lógicas de la solución.

Utilice paquetes adicionales para las construcciones que utilice en más de una aplicación. (Las construcciones compartidas también deben tener su propio ciclo de vida y estrategia de pruebas). Las dependencias entre los paquetes del mismo repositorio se gestionan mediante las herramientas de compilación de su repositorio.

Si bien es posible, no recomendamos colocar varias aplicaciones en el mismo repositorio, especialmente cuando se utilizan canalizaciones de despliegue automatizadas. De este modo, se aumenta el «radio de expansión» de los cambios durante el despliegue. Cuando hay varias aplicaciones en un repositorio, los cambios en una aplicación desencadenan el despliegue de las demás (incluso si las demás no han cambiado). Además, una interrupción en una aplicación impide que se desplieguen las demás.

Mueva el código a los repositorios en función del ciclo de vida del código o de la propiedad del equipo

Cuando los paquetes comiencen a usarse en varias aplicaciones, muévalos a su propio repositorio. De esta forma, los sistemas de creación de aplicaciones que los utilizan pueden hacer referencia a los paquetes y también se pueden actualizar en cadencias independientes de los ciclos de vida de las aplicaciones. Sin embargo, al principio podría tener sentido colocar todas las construcciones compartidas en un repositorio.

Además, mueva los paquetes a su propio repositorio cuando diferentes equipos estén trabajando en ellos. Esto ayuda a reforzar el control de acceso.

Para consumir paquetes más allá de los límites del repositorio, necesitas un repositorio de paquetes privadoNPM, similar a Maven Central PyPi, pero interno en tu organización. También necesitas un proceso de publicación que compile, pruebe y publique el paquete en el repositorio de paquetes privado. CodeArtifactpuede alojar paquetes para los lenguajes de programación más populares.

Las dependencias de los paquetes del repositorio de paquetes las gestiona el administrador de paquetes de su idioma, por ejemplo, NPM para TypeScript JavaScript las aplicaciones. El administrador de paquetes ayuda a garantizar que las compilaciones sean repetibles. Para ello, graba las versiones específicas de cada paquete del que depende tu aplicación. También le permite actualizar esas dependencias de forma controlada.

Los paquetes compartidos necesitan una estrategia de prueba diferente. En el caso de una sola aplicación, podría bastar con desplegarla en un entorno de pruebas y confirmar que sigue funcionando. Sin embargo, los paquetes compartidos deben probarse independientemente de la aplicación que los consuma, como si se estuvieran lanzando al público. (Es posible que su organización opte por lanzar al público algunos paquetes compartidos).

Tenga en cuenta que una construcción puede ser arbitrariamente simple o compleja. A Bucket es una construcción, pero también CameraShopWebsite podría ser una construcción.

La infraestructura y el código de ejecución se encuentran en el mismo paquete

Además de generar AWS CloudFormation plantillas para implementar la infraestructura, AWS CDK también incluye activos de tiempo de ejecución, como funciones Lambda e imágenes de Docker, y los implementa junto con su infraestructura. Esto permite combinar el código que define la infraestructura y el código que implementa la lógica de tiempo de ejecución en una sola construcción. Hacer esto es una buena práctica. No es necesario que estos dos tipos de código se encuentren en repositorios separados o incluso en paquetes separados.

Para desarrollar los dos tipos de código juntos, puedes usar una construcción independiente que describa por completo una parte de la funcionalidad, incluidas su infraestructura y lógica. Con una construcción independiente, puedes probar los dos tipos de código de forma aislada, compartir y reutilizar el código en todos los proyectos y versionar todo el código de forma sincronizada.

Diseñe las mejores prácticas

Esta sección contiene las mejores prácticas para desarrollar construcciones. Las construcciones son módulos reutilizables y componibles que encapsulan los recursos. Son los componentes básicos de las aplicaciones. AWS CDK

Modele con componentes fijos e impleméntelo con pilas

Las pilas son la unidad de despliegue: todos los elementos de una pila se despliegan juntos. Por lo tanto, cuando cree las unidades lógicas de nivel superior de su aplicación a partir de varios AWS recursos, represente cada unidad lógica como un Construct, no como un. Stack Utilice las pilas únicamente para describir cómo deben componerse y conectarse las estructuras en los distintos escenarios de implementación.

Por ejemplo, si una de sus unidades lógicas es un sitio web, las construcciones que lo componen (como un bucket de Amazon S3, API Gateway, funciones de Lambda o tablas de RDS Amazon) deben estar compuestas en una única construcción de alto nivel. Luego, esa construcción se debe instanciar en una o más pilas para su implementación.

Al utilizar componentes constructivos para la construcción y pilas para la implementación, usted mejora el potencial de reutilización de su infraestructura y obtiene más flexibilidad a la hora de implementarla.

Configure con propiedades y métodos, no con variables de entorno

Las búsquedas de variables de entorno dentro de las construcciones y las pilas son un antipatrón común. Tanto las construcciones como las pilas deben aceptar un objeto de propiedades para permitir una completa configurabilidad en el código. De lo contrario, se crea una dependencia de la máquina en la que se ejecutará el código, lo que crea aún más información de configuración de la que hay que hacer un seguimiento y administrar.

En general, las búsquedas de variables de entorno deben limitarse al nivel superior de una AWS CDK aplicación. También deberían usarse para transmitir la información necesaria para ejecutarse en un entorno de desarrollo. Para obtener más información, consulte Entornos para AWS CDK.

Realice pruebas unitarias de su infraestructura

Para ejecutar de forma coherente un conjunto completo de pruebas unitarias en el momento de la compilación en todos los entornos, evite las búsquedas en la red durante la síntesis y modele todas las etapas de producción en código. (Estas prácticas recomendadas se describen más adelante). Si una sola confirmación siempre da como resultado la misma plantilla generada, puedes confiar en las pruebas unitarias que escribas para confirmar que las plantillas generadas tienen el aspecto esperado. Para obtener más información, consulte AWS CDK Aplicaciones de prueba.

No cambies el ID lógico de los recursos con estado

Si se cambia el identificador lógico de un recurso, el recurso se sustituirá por uno nuevo en la siguiente implementación. En el caso de recursos con estado, como bases de datos y depósitos de S3, o infraestructuras persistentes, como AmazonVPC, esto rara vez es lo que se busca. Ten cuidado con cualquier refactorización del AWS CDK código que pueda provocar un cambio en el ID. Escribe pruebas unitarias que confirmen que la lógica IDs de tus recursos con estado permanece estática. El identificador lógico se deriva del id que especifiques al crear una instancia del componente fijo y de la posición del componente fijo en el árbol de componentes fijos. Para obtener más información, consulte Lógico IDs.

Los componentes fijos no son suficientes para garantizar la conformidad

Muchos clientes empresariales diseñan sus propios contenedores para las construcciones de nivel 2 (las construcciones «seleccionadas» que representan AWS recursos individuales e incorporan prácticas recomendadas y predeterminadas). Estos contenedores aplican las mejores prácticas de seguridad, como el cifrado estático y políticas específicas. IAM Por ejemplo, puede crear una MyCompanyBucket que luego utilice en sus aplicaciones en lugar de la Bucket construcción habitual de Amazon S3. Este patrón es útil para dar a conocer directrices de seguridad en una fase temprana del ciclo de vida del desarrollo del software, pero no debe basarse en él como único medio de aplicación.

En su lugar, utilice AWS funciones como las políticas de control de servicios y los límites de permisos para reforzar las barreras de seguridad a nivel de la organización. Utilice Aspectos y AWS CDK herramientas como CloudFormation Guard para hacer afirmaciones sobre las propiedades de seguridad de los elementos de la infraestructura antes del despliegue. Úselo AWS CDK para lo que mejor sabe hacer.

Por último, tenga en cuenta que escribir sus propias construcciones «L2+» puede impedir que sus desarrolladores aprovechen AWS CDK paquetes como AWS Solutions Constructs o construcciones de terceros de Construct Hub. Por lo general, estos paquetes se basan en AWS CDK construcciones estándar y no podrán usar las construcciones de su contenedor.

Mejores prácticas de aplicación

En esta sección, analizamos cómo escribir sus AWS CDK aplicaciones, combinando construcciones para definir cómo están conectados sus AWS recursos.

Tome decisiones en el momento de la síntesis

Si bien AWS CloudFormation le permite tomar decisiones en el momento de la implementación (utilizando Conditions{ Fn::If }, yParameters) y AWS CDK le da cierto acceso a estos mecanismos, le recomendamos que no los utilice. Los tipos de valores que puede utilizar y los tipos de operaciones que puede realizar con ellos son limitados en comparación con lo que está disponible en un lenguaje de programación de uso general.

En su lugar, intente tomar todas las decisiones, como qué construcción crear una instancia, en la AWS CDK aplicación utilizando las if instrucciones del lenguaje de programación y otras funciones. Por ejemplo, una CDK expresión común, que consiste en repetir una lista e instanciar una construcción con valores de cada elemento de la lista, simplemente no es posible utilizar expresiones. AWS CloudFormation

AWS CloudFormation Tómatelo como un detalle de implementación que se AWS CDK utiliza para despliegues sólidos en la nube, no como un objetivo lingüístico. No estás escribiendo AWS CloudFormation plantillas en TypeScript Python, estás escribiendo CDK código que resulta que se usa CloudFormation para la implementación.

Usa nombres de recursos generados, no nombres físicos

Los nombres son un recurso precioso. Cada nombre solo se puede usar una vez. Por lo tanto, si codificas el nombre de una tabla o un nombre de bucket en tu infraestructura y aplicación, no podrás implementar esa infraestructura dos veces en la misma cuenta. (El nombre del que hablamos aquí es el nombre especificado, por ejemplo, por la bucketName propiedad de una construcción de bucket de Amazon S3).

Lo que es peor, no puede realizar cambios en el recurso que requieran su reemplazo. Si una propiedad solo se puede establecer en el momento de la creación del recurso, como una tabla KeySchema de Amazon DynamoDB, entonces esa propiedad es inmutable. Para cambiar esta propiedad se requiere un recurso nuevo. Sin embargo, el nuevo recurso debe tener el mismo nombre para que sea un verdadero sustituto. Sin embargo, no puede tener el mismo nombre mientras el recurso existente siga usando ese nombre.

Un mejor enfoque es especificar el menor número de nombres posible. Si omite los nombres de los recursos, se los AWS CDK generará automáticamente de forma que no le causen problemas. Supongamos que tiene una tabla como recurso. A continuación, puede pasar el nombre de la tabla generada como una variable de entorno a su AWS Lambda función. En su AWS CDK aplicación, puede hacer referencia al nombre de la tabla comotable.tableName. Como alternativa, puedes generar un archivo de configuración en tu EC2 instancia de Amazon al iniciarla o escribir el nombre real de la tabla en el almacén de AWS Systems Manager parámetros para que la aplicación pueda leerlo desde allí.

Si el lugar donde lo necesitas es en otra AWS CDK pila, es aún más sencillo. Suponiendo que una pila define el recurso y otra pila necesita usarlo, se aplica lo siguiente:

Defina las políticas de eliminación y retención de registros

Los AWS CDK intentos de evitar que pierda datos mediante políticas que conservan todo lo que usted crea de forma predeterminada. Por ejemplo, la política de eliminación predeterminada de los recursos que contienen datos (como los depósitos de Amazon S3 y las tablas de bases de datos) consiste en no eliminar el recurso cuando se elimina de la pila. En su lugar, el recurso queda huérfano de la pila. Del mismo modo, el valor predeterminado CDK es conservar todos los registros para siempre. En los entornos de producción, estos valores predeterminados pueden traducirse rápidamente en el almacenamiento de grandes cantidades de datos que en realidad no se necesitan y en la correspondiente AWS factura.

Considere detenidamente cuáles desea que sean estas políticas para cada recurso de producción y especifíquelas en consecuencia. Utilícelas Aspectos y AWS CDK para validar las políticas de eliminación y registro de su pila.

Separe la aplicación en varias pilas según lo exijan los requisitos de implementación

No existe una regla estricta sobre el número de pilas que necesita su aplicación. Por lo general, terminarás basando la decisión en tus patrones de implementación. Ten en cuenta las siguientes pautas:

Comprométete cdk.context.json a evitar un comportamiento no determinista

El determinismo es clave para el éxito de las implementaciones. AWS CDK Básicamente, una AWS CDK aplicación debería tener el mismo resultado siempre que se implemente en un entorno determinado.

Como tu AWS CDK aplicación está escrita en un lenguaje de programación de uso general, puede ejecutar código arbitrario, usar bibliotecas arbitrarias y realizar llamadas de red arbitrarias. Por ejemplo, puedes usar an AWS SDK para recuperar cierta información de tu AWS cuenta mientras sintetizas tu aplicación. Ten en cuenta que, si lo haces, tendrás que configurar las credenciales con más requisitos, aumentará la latencia y correrás la posibilidad, por pequeña que sea, de que se produzca un error cada vez que la ejecutes. cdk synth

No modifique nunca su AWS cuenta ni sus recursos durante la síntesis. Sintetizar una aplicación no debería tener efectos secundarios. Los cambios en la infraestructura solo deberían producirse en la fase de implementación, una vez que se haya AWS CloudFormation generado la plantilla. De esta forma, si hay algún problema, se AWS CloudFormation puede revertir automáticamente el cambio. Para realizar cambios que no se puedan realizar fácilmente dentro del AWS CDK marco, usa recursos personalizados para ejecutar código arbitrario en el momento de la implementación.

Incluso las llamadas estrictamente de solo lectura no son necesariamente seguras. Tenga en cuenta lo que ocurre si cambia el valor devuelto por una llamada de red. ¿En qué parte de su infraestructura afectará eso? ¿Qué pasará con los recursos ya desplegados? Los siguientes son dos ejemplos de situaciones en las que un cambio repentino en los valores podría provocar un problema.

Estas situaciones pueden ser perniciosas porque el AWS cambio radical puede producirse después de meses o años de implementaciones satisfactorias. De repente, sus despliegues están fallando «sin motivo alguno» y hace tiempo que olvidó lo que hizo y por qué.

Afortunadamente, AWS CDK incluye un mecanismo denominado proveedores de contexto para registrar una instantánea de valores no deterministas. Esto permite que las futuras operaciones de síntesis produzcan exactamente la misma plantilla que cuando se desplegaron por primera vez. Los únicos cambios en la nueva plantilla son los cambios que haya realizado en el código. Cuando utilizas el .fromLookup() método de una construcción, el resultado de la llamada se almacena en cdk.context.json caché. Deberías confirmarlo con el control de versiones junto con el resto del código para asegurarte de que en las futuras ejecuciones de tu CDK aplicación se utilice el mismo valor. El CDK kit de herramientas incluye comandos para administrar la caché de contexto, de modo que puedas actualizar entradas específicas cuando lo necesites. Para obtener más información, consulte Los valores de contexto y el AWS CDK.

Si necesita algún valor (de AWS o de otro lugar) para el que no haya un proveedor de CDK contexto nativo, le recomendamos que escriba un script independiente. El script debe recuperar el valor y escribirlo en un archivo y, a continuación, leerlo en CDK la aplicación. Ejecuta el script solo cuando desees actualizar el valor almacenado, no como parte de tu proceso de compilación habitual.

Deje que AWS CDK administren las funciones y los grupos de seguridad

Con los AWS CDK grant() prácticos métodos de la biblioteca de construcción, puede crear AWS Identity and Access Management funciones que concedan acceso a un recurso a otro mediante permisos con un alcance mínimo. Por ejemplo, considere una línea como la siguiente:

amzn-s3-demo-bucket.grantRead(myLambda)

Esta línea única añade una política al rol de la función Lambda (que también se crea para usted). Esa función y sus políticas son más de una docena de líneas CloudFormation que no es necesario escribir. Solo AWS CDK concede los permisos mínimos necesarios para que la función lea el contenido del bucket.

Si se requiere que los desarrolladores utilicen siempre funciones predefinidas creadas por un equipo de seguridad, la AWS CDK codificación se vuelve mucho más complicada. Sus equipos podrían perder mucha flexibilidad a la hora de diseñar sus aplicaciones. Una mejor alternativa es utilizar políticas de control de servicios y límites de permisos para garantizar que los desarrolladores se mantengan dentro de las barreras.

Modele todas las etapas de producción en código

En AWS CloudFormation los escenarios tradicionales, el objetivo es producir un único artefacto parametrizado para que pueda implementarse en varios entornos de destino después de aplicar los valores de configuración específicos de esos entornos. En elCDK, puede y debe crear esa configuración en su código fuente. Cree una pila para su entorno de producción y cree una pila independiente para cada una de las demás etapas. A continuación, coloque los valores de configuración de cada pila en el código. Utilice servicios como Secrets Manager y Systems Manager Parameter Store para valores confidenciales que no desee registrar en el control de código fuente, utilizando los nombres o ARNs de esos recursos.

Al sintetizar la aplicación, el ensamblaje de nube creado en la cdk.out carpeta contiene una plantilla independiente para cada entorno. Toda la compilación es determinista. No hay out-of-band cambios en tu solicitud, y cualquier confirmación determinada siempre arroja exactamente la misma AWS CloudFormation plantilla y los activos correspondientes. Esto hace que las pruebas unitarias sean mucho más fiables.

Mídelo todo

Lograr el objetivo de un despliegue continuo y completo, sin intervención humana, requiere un alto nivel de automatización. Esa automatización solo es posible con una gran cantidad de monitoreo. Para medir todos los aspectos de los recursos desplegados, cree métricas, alarmas y paneles de control. No se limite a medir aspectos como el CPU uso y el espacio en disco. Registre también las métricas de su empresa y utilícelas para automatizar las decisiones de implementación, como las reversiones. La mayoría de las construcciones de nivel 2 incluyen métodos AWS CDK prácticos que ayudan a crear métricas, como el metricUserErrors() método de la clase Dynamodb.Table.