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.
Inicie su entorno para usarlo con el CDK AWS
Inicie su AWS entorno para prepararlo para las implementaciones de pilas del AWS Cloud Development Kit (AWS CDK).
-
Para obtener una introducción a los entornos, consulte Entornos del CDK. AWS
-
Para obtener una introducción al arranque, consulte Arranque de AWS CDK.
Cómo arrancar su entorno
Puede utilizar la interfaz de línea de comandos AWS CDK (AWS CDK CLI) o la herramienta de AWS CloudFormation implementación que prefiera para arrancar su entorno.
- Use la CLI de CDK
-
Puede usar el comando
cdk bootstrapde la CLI de CDK para arrancar su entorno. Este es el método que recomendamos si no necesita realizar modificaciones importantes en el arranque.- Inicie el sistema desde cualquier directorio de trabajo
-
Para arrancar desde cualquier directorio de trabajo, proporcione el entorno de arranque como un argumento de la línea de comandos. A continuación, se muestra un ejemplo:
$ cdk bootstrap <aws://123456789012/us-east-1>sugerencia
Si no tiene su número de AWS cuenta, puede obtenerlo desde la consola de AWS administración. También puede usar el siguiente comando AWS CLI para mostrar la información de su cuenta predeterminada, incluido su número de cuenta:
$ aws sts get-caller-identitySi ha nombrado perfiles en sus
credentialsarchivos AWSconfigy, utilice la--profileopción para recuperar la información de la cuenta de un perfil específico. A continuación, se muestra un ejemplo:$ aws sts get-caller-identity --profile <prod>Para mostrar la región predeterminada, utilice el comando
aws configure get:$ aws configure get region $ aws configure get region --profile <prod>Al proporcionar un argumento, el prefijo
aws://es opcional. Lo siguiente es válido:$ cdk bootstrap <123456789012/us-east-1>Para arrancar varios entornos al mismo tiempo, proporcione varios argumentos:
$ cdk bootstrap <aws://123456789012/us-east-1> <aws://123456789012/us-east-2> - Inicie el programa desde el directorio principal de un proyecto de CDK
-
Puede ejecutar
cdk bootstrapdesde el directorio principal de un proyecto de CDK que contenga un archivocdk.json. Si no proporciona un entorno como argumento, la CLI de CDK obtendrá la información del entorno de las fuentes predeterminadas, como sus archivosconfigycredentialso cualquier información del entorno especificada para la pila de CDK.Al arrancar desde el directorio principal de un proyecto de CDK, los entornos proporcionados a partir de los argumentos de la línea de comandos tienen prioridad sobre otras fuentes.
Para arrancar un entorno especificado en sus archivos
configycredentials, utilice la opción--profile:$ cdk bootstrap --profile <prod>Para obtener más información sobre el comando
cdk bootstrapy las opciones admitidas, consulte cdk bootstrap.
- Utilice cualquier herramienta AWS CloudFormation
-
Puede copiar la plantilla de arranque
del aws-cdk-cli GitHub repositorio u obtenerla con el cdk bootstrap --show-templatecomando. A continuación, utilice cualquier AWS CloudFormation herramienta para implementar la plantilla en su entorno.Con este método, puedes usar nuestra AWS CloudFormation StackSets Torre AWS de Control. También puede utilizar la AWS CloudFormation consola o la interfaz de línea de AWS comandos (AWS CLI). Puede realizar modificaciones en la plantilla antes de implementarla. Este método puede ser más flexible y adecuado para implementaciones a gran escala.
El siguiente es un ejemplo del uso de la opción
--show-templatepara recuperar y guardar la plantilla de arranque en su máquina local:ejemplo
nota
Si aparecen avisos de CDK en el resultado de la AWS CloudFormation plantilla, proporcione la
--no-noticesopción junto con el comando.Para implementar esta plantilla mediante la CLI de CDK, puede ejecutar lo siguiente:
$ cdk bootstrap --template <bootstrap-template.yaml>El siguiente es un ejemplo del uso de la AWS CLI para implementar la plantilla:
ejemplo
Para obtener información sobre cómo iniciar varios entornos, consulte Cómo iniciar varias AWS cuentas para CloudFormation StackSets utilizarlas en AWS CDK en el blog sobre operaciones y migraciones CloudFormation StackSets
en la AWS nube.
Cuando arrancar su entorno
Debe iniciar cada AWS entorno antes de implementarlo en el entorno. Recomendamos arrancar de forma proactiva cada entorno que desee utilizar. Puede hacerlo antes de planificar la implementación efectiva de las aplicaciones CDK en el entorno. Al arrancar sus entornos de forma proactiva, evita posibles problemas futuros, como conflictos de nombres de bucket de Amazon S3 o la implementación de aplicaciones CDK en entornos que no se iniciaron.
Está bien arrancar un entorno más de una vez. Si un entorno ya se inició, la pila de arranque se actualizará si es necesario. De lo contrario, no pasará nada.
Si intenta implementar una pila de CDK en un entorno que no arrancó, verá un error como el siguiente:
$ cdk deploy ✨ Synthesis time: 2.02s ❌ Deployment failed: Error: BootstrapExampleStack: 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)
- Actualice su pila de bootstrap
-
De forma periódica, el equipo de CDK actualizará la plantilla de arranque a una versión nueva. Cuando esto sucede, le recomendamos que actualice la pila de arranque. Si no personalizó el proceso de arranque, puede actualizar su pila de arranque con los mismos pasos que siguió para arrancar su entorno originalmente. Para obtener más información, consulte el historial de versiones de la plantilla de arranque.
Recursos predeterminados creados durante el arranque
- Funciones de IAM creadas durante el arranque
-
De forma predeterminada, el bootstrapping aprovisiona las siguientes funciones de AWS Identity and Access Management (IAM) en su entorno:
-
CloudFormationExecutionRole -
DeploymentActionRole -
FilePublishingRole -
ImagePublishingRole -
LookupRole
-
CloudFormationExecutionRole -
Esta función de IAM es una función de CloudFormation servicio que otorga CloudFormation permiso para realizar despliegues de pilas en su nombre. Esta función te da CloudFormation permiso para realizar llamadas a la AWS API en tu cuenta, incluida la implementación de pilas.
Al usar un rol de servicio, los permisos proporcionados para el rol de servicio determinan qué acciones se pueden realizar en tus CloudFormation recursos. Sin esta función de servicio, las credenciales de seguridad que proporcione con la CLI de CDK determinarían lo que CloudFormation está permitido hacer.
-
DeploymentActionRole -
Este rol de IAM concede permiso para realizar implementaciones en su entorno. La CLI de CDK lo asume durante las implementaciones.
Al usar un rol para las implementaciones, puede realizar implementaciones entre cuentas, ya que el rol lo pueden asumir AWS las identidades de una cuenta diferente.
-
FilePublishingRole -
Este rol de IAM concede permiso para realizar acciones contra el bucket de Amazon Simple Storage Service (Amazon S3) que arrancó, incluidas la carga y eliminación de activos. La CLI de CDK lo asume durante las implementaciones.
-
ImagePublishingRole -
Este rol de IAM concede permiso para realizar acciones contra el repositorio Amazon Elastic Container Registry (Amazon ECR) que arrancó. La CLI de CDK lo asume durante las implementaciones.
-
LookupRole -
Esta función de IAM otorga
readOnlypermiso para buscar valores de contexto en el entorno. AWS La CLI de CDK lo asume al realizar tareas como la síntesis de plantillas y las implementaciones.
-
- Recurso IDs creado durante el arranque
-
Al implementar la plantilla de arranque predeterminada, los recursos físicos IDs para el arranque se crean utilizando la siguiente estructura:.
cdk-<qualifier>-<description>-<account-ID>-<Region>-
Calificador: un valor de cadena único de nueve caracteres de
hnb659fds. El valor real no tiene importancia. -
Descripción: una descripción corta del recurso. Por ejemplo,
container-assets. -
ID de cuenta: el ID de AWS cuenta del entorno.
-
Región: la AWS región del entorno.
El siguiente es un ejemplo de ID físico del bucket transitorio de Amazon S3 creado durante el arranque:
cdk-hnb659fds-assets-012345678910-us-west-1. -
Permisos que se deben utilizar al arrancar el entorno
Al iniciar un AWS entorno, la identidad de IAM que realiza el arranque debe tener al menos los siguientes permisos:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:*", "ecr:*", "ssm:*", "s3:*", "iam:*" ], "Resource": "*" } ] }
Con el tiempo, la pila de arranque, incluidos los recursos que se crean y los permisos que requieren, puede cambiar. Con cambios futuros, es posible que tenga que modificar los permisos necesarios para arrancar un entorno.
Personalice el arranque
Si la plantilla de arranque predeterminada no se ajusta a sus necesidades, puede personalizar el arranque de recursos a su entorno de las siguientes maneras:
-
Utilizar las opciones de línea de comandos con el comando
cdk bootstrap: este método es el mejor para realizar cambios pequeños y específicos que se admiten mediante las opciones de la línea de comandos. -
Modificar la plantilla de arranque predeterminada e implementarla: este método es el mejor para realizar cambios complejos o si desea tener un control total sobre la configuración de los recursos aprovisionados durante el arranque.
Proceso de arranque con CDK Pipelines
Si utiliza CDK Pipelines para realizar la implementación en el entorno de otra cuenta y recibe un mensaje como el siguiente:
Policy contains a statement with one or more invalid principals
Este mensaje de error significa que los roles de IAM adecuados no existen en el otro entorno. La causa más probable es que el entorno no arrancó. Arranque el entorno e inténtelo de nuevo.
- Cómo proteger su pila de bootstrap para que no se elimine
-
Si se elimina una pila de bootstrap, también se eliminarán los AWS recursos que se aprovisionaron originalmente en el entorno para respaldar las implementaciones de CDK. Esto hará que la canalización deje de funcionar. Si esto sucede, no existe una solución general para la recuperación.
Una vez que se arranque el entorno, no elimine ni vuelva a crear la pila de arranque del entorno. En su lugar, intente actualizar la pila de arranque a una nueva versión ejecutando el comando
cdk bootstrapde nuevo.Para evitar que se elimine accidentalmente la pila de arranque, le recomendamos que proporcione la opción
--termination-protectionjunto con el comandocdk bootstrappara habilitar la protección contra la terminación. Puede habilitar la protección contra la terminación en pilas de arranque nuevas o existentes. Para obtener instrucciones sobre cómo habilitar la protección de terminación, consulte Enable termination protection for the bootstrap stack.
Historial de versiones de la plantilla de arranque
La plantilla de bootstrap está versionada y evoluciona con el tiempo con la propia CDK. AWS Si proporciona su propia plantilla de arranque, manténgala actualizada mediante la plantilla canónica predeterminada. Querrá asegurarse de que su plantilla siga funcionando con todas las características del CDK.
nota
Las versiones anteriores de la plantilla de arranque creaban una clave AWS KMS en cada entorno de arranque de forma predeterminada. Para evitar que se le cobre por la clave KMS, reinicie el arranque de estos entornos con --no-bootstrap-customer-key. El valor predeterminado actual es sin una clave KMS, lo que ayuda a evitar estos cargos.
Esta sección contiene una lista de los cambios realizados en cada versión.
| Versión de plantilla | AWS Versión CDK | Cambios |
|---|---|---|
|
1 |
1.40.0 |
Versión inicial de la plantilla con el bucket, la clave, el repositorio y los roles. |
|
2 |
1.45.0 |
Se dividió el rol del publicador de activos en roles independientes del publicador de archivos e imágenes. |
|
3 |
1.46.0 |
Se agregó la opción de exportación de |
|
4 |
1.61.0 |
AWS Los permisos de KMS ahora están implícitos a través de Amazon S3 y ya no son necesarios |
|
5 |
1.87.0 |
El rol de implementación puede leer el parámetro SSM. |
|
6 |
1.108.0 |
Se agregó un rol de búsqueda independiente del rol de implementación. |
|
6 |
1.109,0 |
Se adjuntó una etiqueta |
|
7 |
1.110,0 |
El rol de implementación ya no puede leer directamente los buckets de la cuenta de destino. (Sin embargo, este rol es, en efecto, el de administrador y, de todos modos, siempre puede usar sus AWS CloudFormation permisos para hacer que el bucket sea legible). |
|
8 |
1.114.0 |
El rol de búsqueda tiene permisos completos de solo lectura para el entorno de destino y también tiene una etiqueta de |
|
9 |
2.1.0 |
Corrige el rechazo de las cargas de activos de Amazon S3 por parte del SCP de cifrado al que se hace referencia comúnmente. |
|
10 |
2.4.0 |
Amazon ECR ahora ScanOnPush está activado de forma predeterminada. |
|
11 |
2.18.0 |
Agrega una política que permite a Lambda extraer datos de los repositorios de Amazon ECR para sobrevivir al reinicio del arranque. |
|
12 |
2.20.0 |
Agrega soporte para experimentos de |
|
13 |
2.25.0 |
Hace que las imágenes del contenedor de los repositorios de Amazon ECR creados en el arranque sean inmutables. |
|
14 |
2.34.0 |
Desactiva de forma predeterminada el escaneo de imágenes de Amazon ECR en el nivel del repositorio para permitir el arranque de regiones que no admiten el escaneo de imágenes. |
|
15 |
2.60,0 |
Las claves KMS no se pueden etiquetar. |
|
16 |
2.69,0 |
Aborda el resultado de Security HubKMS.2. |
|
17 |
2.72.0 |
Aborda el resultado de Security Hub ECR.3. |
|
18 |
2.80,0 |
Se revirtieron los cambios realizados en la versión 16, ya que no funcionan en todas las particiones y no se recomiendan. |
|
19 |
2.106.1 |
Se han revertido los cambios realizados en la versión 18, en los que se eliminaba la AccessControl propiedad de la plantilla. (#27964 |
|
20 |
2.119.0 |
Añada |
|
21 |
2.149.0 |
Se agregó una condición al rol de publicación de archivos. |
|
22 |
2.160,0 |
Se agregaron permisos de |
|
23 |
2.161,0 |
Se agregaron permisos de |
|
24 |
2.165.0 |
Cambie el periodo de días durante el que se conservarán los objetos no actuales del bucket de arranque, de 365 a 30 días. Dado que el nuevo comando |
|
25 |
2.165,0 |
Agregue soporte al bucket de arranque para eliminar las cargas de varias partes incompletas. Las cargas de varias partes incompletas se eliminarán después de 1 día. Para obtener más información sobre este cambio, consulte |
|
26 |
2.1002.0 |
Agregue al recurso dos políticas relacionadas con la eliminación ( |
|
27 |
2.1003.0 |
Agregue una nueva política de recursos de Amazon ECR para conceder a Amazon EMR sin servidor permisos específicos para recuperar imágenes de contenedores. Para obtener más información sobre este cambio, consulte |
|
28 |
2.1015,0 |
Añada permisos para realizar acciones de refactorización de pilas a la función de implementación y TagSession permisos a todas las funciones. Para obtener más información sobre este cambio, consulte |
|
29 |
2.1026,0 |
Todas las AssumeRole llamadas que proporcionen un se ExternalId rechazarán de forma predeterminada, a menos que estén deshabilitadas. Para obtener más información sobre este cambio, consulta |
|
30 |
2.1034.0 |
Añada permisos para describir los eventos de la pila a la función de despliegue para poder mostrar con precisión los errores de validación CloudFormation temprana. Para obtener más información sobre este cambio, consulte [#bootstrapping -template] == Actualización de una plantilla bootstrap antigua a una moderna La versión 1 del AWS CDK admitía dos plantillas de arranque: la antigua y la moderna. CDK v2 solo admite la plantilla moderna. Como referencia, estas son las diferencias de alto nivel entre estas dos plantillas. [cols="1h,1,1", options="header "] |
| Característica | Legacy (solo en la versión 1) | Moderna (en la versión 1 y en la versión 2)
|Implementaciones entre cuentas |No permitidas |Permitidas
|AWS CloudFormation Permisos |Se implementa con los permisos del usuario actual (determinados por el AWS perfil, las variables de entorno, etc.) |Se despliega con los permisos especificados cuando se aprovisionó la pila de arranque (por ejemplo, mediante el uso) --trust
|Control de versiones |Solo hay disponible una versión de la pila de bootstrap |La pila de Bootstrap está versionada; se pueden añadir nuevos recursos en futuras versiones y AWS las aplicaciones de CDK pueden requerir una versión mínima
|Recursos* |Amazon S3 bucket a|
-
Bucket de Amazon S3
-
AWS Clave KMS
-
Roles de IAM
-
Repositorio de Amazon ECR
-
Parámetro SSM para el control de versiones
| Clave AWS KMS |Funciones de IAM |Repositorio Amazon ECR
|Denominación de recursos |Generado automáticamente |Determinístico
|Cifrado de buckets |Clave predeterminada | Clave administrada de forma predeterminada.AWS Se puede personalizar para utilizar una clave administrada por el cliente.
|
* Agregaremos recursos adicionales a la plantilla de arranque según sea necesario. Un entorno que arrancó con la plantilla heredada debe actualizarse para utilizar la plantilla moderna de CDK v2 mediante el reinicio del arranque. Vuelva a implementar todas las aplicaciones de AWS CDK en el entorno al menos una vez antes de eliminar el depósito antiguo. [#bootstrapping -securityhub] == Abordar los hallazgos del Security Hub Si utiliza AWS Security Hub, es posible que vea información sobre algunos de los recursos creados por el proceso de arranque de AWS CDK. Los resultados de Security Hub le ayudan a encontrar configuraciones de recursos que debe comprobar para garantizar su precisión y seguridad. Hemos revisado estas configuraciones de recursos específicas con AWS Security y estamos seguros de que no constituyen un problema de seguridad. [# bootstrapping-securityhub-kms 2] [KMS.2] Los directores de IAM no deberían tener políticas integradas de IAM que permitan acciones de descifrado en todas las claves de KMS:: + La función de despliegue ( cdk bootstrap Si aún no lo hizo, cree e implemente la Pipeline de CDK. Para obtener instrucciones, consulte Integración y entrega continuas (CI/CD) mediante CDK Pipelines. Obtenga el ARN de la clave AWS KMS del depósito de CodePipeline artefactos. Este recurso se crea durante la creación de la canalización. Obtenga una copia de la plantilla de arranque de CDK para modificarla. El siguiente es un ejemplo del uso de la CLI de AWS CDK: + [source, bash, subs="verbatim, attributes "] ---- $ cdk bootstrap --show-template bootstrap-template.yaml ----. Modifique la plantilla sustituyendo Resource:
la PipelineCrossAccountArtifactsKey declaración por su valor de ARN. Implemente la plantilla para actualizar su pila de arranque. A continuación se muestra un ejemplo con la CLI de CDK: + [source, bash, subs="verbatim, attributes "] ---- $ cdk bootstrap aws: //account-id/region --template bootstrap-template.yaml ---- + |
