Personalización del arranque del AWS CDK - AWS Kit Cloud Development Kit (AWS CDK) v2
Utilice la CLI de CDK para personalizar el arranqueModificar la plantilla de arranque predeterminadaRespete el contrato de arranque

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.

Personalización del arranque del AWS CDK

Puede personalizar el arranque del AWS Cloud Development Kit (AWS CDK) mediante la interfaz de línea de comandos del AWS CDK (CLI de AWS CDK) o modificando e implementando la plantilla de arranque de AWS CloudFormation.

Para obtener una introducción al arranque, consulte Arranque de AWS CDK.

Utilice la CLI de CDK para personalizar el arranque

A continuación, se muestran algunos ejemplos de cómo puede personalizar el arranque mediante la CLI de CDK. Para obtener una lista de todas las opciones cdk bootstrap, consulte arranque de CDK.

Anule el nombre del bucket de Amazon S

Utilice la opción --bootstrap-bucket-name para anular el nombre del bucket de Amazon S3 predeterminado. Esto puede requerir que modifique la síntesis de plantillas. Consulte Personalizar la síntesis de pilas de CDK para obtener más información.

Modifique las claves de cifrado del lado del servidor del bucket de Amazon S

De forma predeterminada, el bucket de Amazon S3 de la pila de arranque está configurado para usar claves administradas de AWS para el cifrado del servidor. Para usar una clave administrada por el cliente existente, utilice la opción --bootstrap-kms-key-id y proporcione un valor para que la clave del AWS Key Management Service (AWS KMS) la utilice. Si desea tener un mayor control sobre la clave de cifrado, proporcione una --bootstrap-customer-key para que utilice una clave administrada por el cliente.

Adjunte políticas administradas al rol de implementación que asuma AWS CloudFormation

De forma predeterminada, las pilas se implementan con todos los permisos de administrador mediante la política AdministratorAccess. Para usar sus propias políticas administradas, utilice la opción --cloudformation-execution-policies y proporcione los ARN de las políticas administradas para asociarlos al rol de implementación.

Para proporcionar varias políticas, páselas en una sola cadena, separadas por comas:

$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"

Para evitar errores en la implementación, asegúrese de que las políticas que especifique sean suficientes para cualquier implementación que vaya a realizar en el entorno que se arranca.

Cambie el calificador que se agrega a los nombres de los recursos de la pila de arranque

De forma predeterminada, el calificador hnb659fds se agrega al ID físico de los recursos de la pila de arranque. Para cambiar este valor, use la opción --qualifier.

Esta modificación resulta útil cuando se aprovisionan varias pilas de arranque en el mismo entorno para evitar conflictos de nombres.

El calificador se cambia para aislar los nombres entre las pruebas automatizadas del propio CDK. A menos que pueda reducir con mucha precisión los permisos de IAM otorgados al rol de ejecución de CloudFormation, tener dos pilas de arranque diferentes en una sola cuenta no brinda ninguna ventaja de aislamiento de permisos. Por lo tanto, no suele ser necesario cambiar este valor.

Cuando cambia el calificador, la aplicación CDK debe pasar el valor modificado al sintetizador de pilas. Consulte Personalizar la síntesis de pilas de CDK para obtener más información.

Agregue etiquetas a la pila de arranque

Utilice la opción --tags en el formato de KEY=VALUE para agregar etiquetas de CloudFormation a su pila de arranque.

Especifique otras cuentas de AWS que se puedan implementar en el entorno que se arranca

Utilice la opción --trust para proporcionar cuentas de AWS adicionales que tengan permiso para implementarse en el entorno que se arranca. De forma predeterminada, siempre se confiará en la cuenta que ejecuta el arranque.

Esta opción resulta útil cuando se arranca un entorno en el que se implementará una Pipeline del CDK de otro entorno.

Cuando utilice esta opción, también debe proporcionar las --cloudformation-execution-policies.

Para agregar cuentas de confianza a una pila de arranque existente, debe especificar todas las cuentas en las que puede confiar, incluidas las que haya proporcionado anteriormente. Si solo proporciona cuentas nuevas en las que confiar, se eliminarán las cuentas de confianza anteriores.

A continuación, se muestra un ejemplo de confianza de dos cuentas:

$ cdk bootstrap aws://123456789012/us-west-2 --trust 234567890123 --trust 987654321098 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess
 ⏳  Bootstrapping environment aws://123456789012/us-west-2...
Trusted accounts for deployment: 234567890123, 987654321098
Trusted accounts for lookup: (none)
Execution policies: arn:aws:iam::aws:policy/AdministratorAccess
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://123456789012/us-west-2 bootstrapped.
Especifique otras cuentas de AWS adicionales que puedan buscar información en el entorno que se arranca

Utilice la opción --trust-for-lookup para especificar las cuentas de AWS que están autorizadas para buscar información contextual del entorno que se arranca. Esta opción resulta útil para dar permiso a las cuentas para sintetizar las pilas que se van a implementar en el entorno, sin concederles realmente permiso para implementar esas pilas directamente.

Habilite la protección de la terminación para la pila de arranque

Si se elimina una pila de arranque, también se eliminarán los recursos de AWS que se aprovisionaron originalmente en el entorno. Tras el arranque del entorno, recomendamos que no elimine ni vuelva a crear la pila de arranque del entorno, a menos que lo haga de forma intencionada. En su lugar, intente actualizar la pila de arranque a una nueva versión ejecutando de nuevo el comando cdk bootstrap.

Utilice la opción --termination-protection para administrar la configuración de la protección de terminación de la pila de arranque. Es posible evitar que una pila de arranque y sus recursos se eliminen de manera accidental; para ello, habilite la protección de terminación. Esto es particularmente importante si utiliza Pipelines del CDK, ya que no hay ninguna opción de recuperación general en caso de que elimine accidentalmente la pila de arranque.

Tras activar la protección contra la terminación, puede utilizar la AWS CLI o la consola de AWS CloudFormation para realizar la verificación.

Para habilitar la protección contra la terminación

  1. Ejecute el siguiente comando para habilitar la protección de terminación en una pila de arranque nueva o existente:

    $ cdk bootstrap --termination-protection

  2. Utilice la AWS CLI o la consola de CloudFormation verificarlo. A continuación se muestra un ejemplo del uso de la AWS CLI. Si modificó el nombre de la pila de arranque, sustituya el CDKToolkit por el nombre de la pila:

    $ aws cloudformation describe-stacks --stack-name <CDKToolkit> --query "Stacks[0].EnableTerminationProtection"
true

Modificar la plantilla de arranque predeterminada

Cuando necesite una mayor personalización de la que la CLI de CDK pueda proporcionar, puede modificar la plantilla de arranque según sea necesario. A continuación, implemente la plantilla para arrancar su entorno.

Para modificar e implementar la plantilla de arranque predeterminada

  1. Obtenga la plantilla de arranque predeterminada mediante la opción --show-template. De forma predeterminada, la CLI de CDK mostrará la plantilla en la ventana de su terminal. Puede modificar el comando de la CLI de CDK para guardar la plantilla en su máquina local. A continuación, se muestra un ejemplo:

    $ cdk bootstrap --show-template > <my-bootstrap-template.yaml>

  2. Modifique la plantilla de arranque según sea necesario. Todos los cambios que realice deben respetar la plantilla de contrato de arranque. Para obtener más información sobre la plantilla de contrato de arranque, consulte Seguimiento el contrato de arranque.

    Para asegurarse de que nadie que ejecute cdk bootstrap cuando utilice la plantilla predeterminada sobrescriba sus personalizaciones accidentalmente más adelante, cambie el valor predeterminado del parámetro BootstrapVariant de la plantilla. La CLI de CDK solo permitirá sobrescribir la pila de arranque mediante plantillas que tengan la misma BootstrapVariant y una versión igual o superior a la de la plantilla implementada actualmente.

  3. Implemente la plantilla modificada mediante el método de implementación de AWS CloudFormation de su preferencia. A continuación, se muestra un ejemplo que utiliza la CLI de CDK:

    $ cdk bootstrap --template <my-bootstrap-template.yaml>

Respete el contrato de arranque

Para que las aplicaciones del CDK se implementen correctamente, las plantillas de CloudFormation generadas durante la síntesis deben especificar correctamente los recursos creados durante el arranque. Estos recursos se denominan comúnmente recursos de arranque. El arranque crea recursos en su entorno de AWS que el AWS CDK utiliza para llevar a cabo implementaciones y administrar los activos de las aplicaciones. La síntesis produce plantillas de CloudFormation a partir de cada pila de CDK de la aplicación. Estas plantillas no solo definen los recursos de AWS que se aprovisionarán a partir de la aplicación. También especifican los recursos de arranque que se van a utilizar durante la implementación.

Durante la síntesis, la CLI de CDK no sabe específicamente cómo se arrancó el entorno de AWS. En su lugar, la CLI de CDK produce plantillas de CloudFormation basadas en el sintetizador que configure. Por lo tanto, es posible que al momento de personalizar el arranque deba personalizar la síntesis. Consulte Personalizar la síntesis de pilas de CDK para obtener instrucciones sobre cómo personalizar la síntesis. El objetivo es garantizar que las plantillas sintetizadas de CloudFormation sean compatibles con el entorno de arranque. Esta compatibilidad se conoce como contrato de arranque.

El método más sencillo para personalizar la síntesis de pilas consiste en modificar la clase DefaultStackSynthesizer de la instancia Stack. Si necesita una personalización más allá de la que puede ofrecer esta clase, puede escribir su propio sintetizador como una clase que implemente el código IStackSynthesizer (que quizás derive del DefaultStackSynthesizer).

Cuando personalice el arranque, respete la plantilla del contrato de arranque para que siga siendo compatible con DefaultStackSynthesizer. Si modifica el arranque más allá de la plantilla del contrato de arranque, deberá escribir su propio sintetizador.

Control de versiones

La plantilla de arranque debe contener un recurso para crear un parámetro de Amazon EC2 Systems Manager (SSM) con un nombre reconocido y un resultado que refleje la versión de la plantilla:

Resources:
  CdkBootstrapVersion:
    Type: AWS::SSM::Parameter
    Properties:
      Type: String
      Name:
        Fn::Sub: '/cdk-bootstrap/${Qualifier}/version'
      Value: 4
Outputs:
  BootstrapVersion:
    Value:
      Fn::GetAtt: [CdkBootstrapVersion, Value]

Roles

El DefaultStackSynthesizer requiere cinco roles de IAM para cinco propósitos diferentes. Si no utiliza los roles predeterminados, debe especificar los ARN de su rol de IAM dentro del objeto DefaultStackSynthesizer. Los roles son los siguientes:

  • Al rol de implementación lo asumen la CLI de CDK y AWS CodePipeline para la implementación en un entorno. Su AssumeRolePolicy controla quién puede llevar a cabo la implementación en el entorno. En la plantilla, puede ver los permisos que necesita este rol.

  • Al rol de búsqueda lo asume la CLI de CDK para llevar a cabo búsquedas de contexto en un entorno. Su AssumeRolePolicy controla quién puede llevar a cabo la implementación en el entorno. Los permisos que necesita este rol se pueden ver en la plantilla.

  • Al rol de publicación de archivos y al rol de publicación de imágenes lo asumen la CLI de CDK y los proyectos de AWS CodeBuild para publicar activos en un entorno. Se utilizan para escribir en el bucket de Amazon S3 y en el repositorio de Amazon ECR, respectivamente. Estos roles requieren acceso de escritura a estos recursos.

  • El rol de ejecución de AWSCloudFormation se transfiere a AWS CloudFormation para llevar a cabo implementación real. Sus permisos son aquellos con los que se ejecutará la implementación. Los permisos se transfieren a la pila como un parámetro que enumera los ARN de las políticas administradas.

Salidas

La CLI de CDK requiere que existan las siguientes salidas de CloudFormation en la pila de arranque:

  • BucketName: el nombre del bucket del activo de archivo.

  • BucketDomainName: el bucket del activo de archivo en formato de nombre de dominio.

  • BootstrapVersion: la versión actual de la pila de arranque.

Historial de plantillas

La plantilla de arranque cuenta con control de versiones y evoluciona con el tiempo junto con el AWS CDK. 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. Para obtener más información, consulte el historial de versiones de la plantilla de arranque.