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

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.

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 (AWS CDKCLI) 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 del CDK para personalizar el arranque

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

Anule el nombre del bucket de Amazon S3

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. Para obtener más información, consulte Personalice la síntesis de pilas de CDK.

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

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 lado 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 a la función 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 a la función 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. Para obtener más información, consulte Personalice la síntesis de pilas de CDK.

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 más Cuentas de AWS 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 que puedan buscar información en el entorno que se arranca

Utilice la opción --trust-for-lookup para especificar 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.

Después de activar la protección de terminación, puede usar la AWS CLI o la consola de AWS CloudFormation para verificarlo.

Para habilitar la protección de 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 mediante 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 del 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 del CDK mostrará la plantilla en la ventana de su terminal. Puede modificar el comando de la CLI del 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 Respete 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 del 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 del AWS CloudFormation de su preferencia. A continuación, se muestra un ejemplo que utiliza la CLI del 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 del CDK no sabe específicamente cómo se ha arrancó el entorno de AWS. En su lugar, la CLI del 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. Para obtener instrucciones sobre cómo personalizar la síntesis, consulte Personalice la síntesis de pilas de CDK. 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 del 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 del 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 del 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 AWS CloudFormation 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 del 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 Historial de versiones de la plantilla de arranque.