Esta es la segunda versión de la Guía para desarrolladores de AWS CDK. 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.

Arranque su entorno para utilizarlo con AWS CDK

Arranque su entorno de AWS para prepararlo para las implementaciones de pilas de AWS Cloud Development Kit (AWS CDK).

Cómo arrancar su entorno

Puede utilizar la interfaz de línea de comandos de AWS CDK (la CLI de AWS CDK) o la herramienta de implementación de AWS CloudFormation que prefiera para arrancar su entorno.

Utilice la CLI de CDK

Puede usar el comando cdk bootstrap de la CLI de CDK para arrancar su entorno. Este es el método que recomendamos si no necesita realizar modificaciones importantes en el arranque.

Para obtener más información sobre el comando cdk bootstrap y las opciones de admitidas, consulte cdk bootstrap.

Utilización de cualquier herramienta de AWS CloudFormation

Puede copiar la plantilla de arranque del repositorio de GitHub aws-cdk u obtenerla con el comando cdk bootstrap --show-template. A continuación, utilice cualquier herramienta de AWS CloudFormation para implementar la plantilla en su entorno.

Con este método, puede utilizar StackSets de AWS CloudFormation o AWS Control Tower. También puede utilizar la consola de AWS CloudFormation o la AWS Command Line Interface (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-template para recuperar y guardar la plantilla de arranque en su máquina local:

macOS/Linux

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

Windows

En Windows, se debe utilizar PowerShell para conservar la codificación de la plantilla.

powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml"

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 una plantilla:

macOS/Linux

aws cloudformation create-stack \
  --stack-name CDKToolkit \
  --template-body file://path/to/bootstrap-template.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-west-1

Windows

aws cloudformation create-stack ^
  --stack-name CDKToolkit ^
  --template-body file://path/to/bootstrap-template.yaml ^
  --capabilities CAPABILITY_NAMED_IAM ^
  --region us-west-1

Para obtener información sobre el uso de CloudFormation StackSets para arrancar varios entornos, consulte Bootstrapping multiple Cuentas de AWS for AWS CDK using CloudFormation StackSets en el AWS Cloud Operations & Migrations Blog.

Cuando arrancar su entorno

Debe iniciar cada entorno de AWS 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)

Actualización de la pila de arranque

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 Historial de versiones de la plantilla de arranque.

Recursos predeterminados creados durante el arranque

Roles de IAM creados durante el arranque

De forma predeterminada, el arranque aprovisiona los siguientes roles de AWS Identity and Access Management (IAM) en el entorno:

ID de recursos creados durante el arranque

Al implementar la plantilla de arranque predeterminada, los ID físicos de los recursos de arranque se crean con la siguiente estructura: cdk-qualifier-description-account-ID-Region.

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 arrancar un entorno de AWS, la identidad de IAM que realice el arranque debe disponer al menos de 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:

Para obtener más información sobre la personalización del proceso de arranque, consulte Personalización del arranque del AWS CDK.

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.

Proteja su pila de arranque para que no se elimine

Si se elimina una pila de arranque, también se eliminarán los recursos de AWS que se aprovisionaron originalmente en el entorno para respaldar las implementaciones del 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 bootstrap de nuevo.

Para evitar que se elimine accidentalmente la pila de arranque, le recomendamos que proporcione la opción --termination-protection junto con el comando cdk bootstrap para 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 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.

Esta sección contiene una lista de los cambios realizados en cada versión.

Actualización de una plantilla de arranque de heredada a una moderna

La v1 de AWS CDK admitía dos plantillas de arranque, heredada y moderna. CDK v2 solo admite la plantilla moderna. Como referencia, estas son las diferencias de alto nivel entre estas dos plantillas.

* 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 AWS CDK del entorno al menos una vez antes de eliminar el bucket heredado.

Abordar los resultados de Security Hub

Si utiliza AWS Security Hub, es posible que vea un informe con los resultados 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. Revisamos estas configuraciones de recursos específicas con AWS Security y estamos seguros de que no constituyen un problema de seguridad.

[KMS.2] Los directores de IAM no deberían tener políticas integradas de IAM que permitan realizar acciones de descifrado en todas las claves de KMS

El rol de despliegue (DeploymentActionRole) otorga permiso para leer datos cifrados, lo cual es necesario para las implementaciones entre cuentas con CDK Pipelines. Las políticas de este rol no otorgan permisos a todos los datos. Solo concede permiso para leer datos cifrados de Amazon S3 y AWS KMS y solo cuando esos recursos lo permiten a través de su política de claves o de bucket.

A continuación, se incluye un fragmento de estas dos instrucciones sobre el rol de implementación de la plantilla de arranque:

DeploymentActionRole:
    Type: AWS::IAM::Role
    Properties:
      ...
      Policies:
        - PolicyDocument:
            Statement:
              ...
              - Sid: PipelineCrossAccountArtifactsBucket
                Effect: Allow
                Action:
                  - s3:GetObject*
                  - s3:GetBucket*
                  - s3:List*
                  - s3:Abort*
                  - s3:DeleteObject*
                  - s3:PutObject*
                Resource: "*"
                Condition:
                  StringNotEquals:
                    s3:ResourceAccount:
                      Ref: AWS::AccountId
              - Sid: PipelineCrossAccountArtifactsKey
                Effect: Allow
                Action:
                  - kms:Decrypt
                  - kms:DescribeKey
                  - kms:Encrypt
                  - kms:ReEncrypt*
                  - kms:GenerateDataKey*
                Resource: "*"
                Condition:
                  StringEquals:
                    kms:ViaService:
                      Fn::Sub: s3.${AWS::Region}.amazonaws.com
              ...

¿Por qué Security Hub marca esto?

Las políticas contienen un Resource: * combinado con una cláusula Condition. Security Hub marca el comodín *. Este comodín se utiliza porque, en el momento en que se inicia la cuenta, la clave AWS KMS creada por CDK Pipelines para el bucket de artefactos de CodePipeline aún no existe y, por lo tanto, ARN no puede hacer referencia a ella en la plantilla de arranque. Además, Security Hub no tiene en cuenta la cláusula Condition al hacer esta marca. Esta Condition limita Resource: * a las solicitudes realizadas desde la misma Cuenta de AWS de la clave AWS KMS. Estas solicitudes deben provenir de Amazon S3 en la misma Región de AWS que la clave AWS KMS.

¿Tengo que corregir este resultado?

Mientras no haya modificado la clave AWS KMS de la plantilla de arranque para que sea demasiado permisiva, el rol de implementación no permitirá más acceso del que necesita. Por lo tanto, no es necesario corregir este resultado.

¿Qué sucede si quiero corregir este resultado?

La forma de solucionar este resultado dependerá de si utilizará o no CDK Pipelines para las implementaciones entre cuentas.

Consideraciones

Dado que el arranque aprovisiona recursos en su entorno, puede incurrir en cargos de AWS si esos recursos se utilizan con el AWS CDK.