View a markdown version of this page

implementación de CDK - AWS Kit de desarrollo en la nube (AWS (CDK) v2
De usoArgumentosOpcionesEjemplos

Esta es la guía para desarrolladores del 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.

implementación de CDK

Implemente una o más pilas de AWS CDK en su AWS entorno.

Durante la implementación, la CLI del CDK generará indicadores de progreso similares a los que se pueden observar desde la consola. AWS CloudFormation

Si el AWS entorno no se inicia, solo se implementarán correctamente las pilas sin activos y con plantillas sintetizadas de menos de 51 200 bytes.

De uso

$ cdk deploy <arguments> <options>

Argumentos

ID de pila del CDK

El ID de constructo de la pila de CDK correspondiente a la aplicación que desea eliminar.

Tipo: cadena

Obligatorio: no

Opciones

Para obtener una lista de las opciones globales que funcionan con todos los comandos de la CLI de CDK, consulte Opciones globales.

--all <BOOLEAN>

Implemente todas las pilas en su aplicación CDK.

Valor predeterminado: false

--asset-parallelism <BOOLEAN>

Especifique si desea crear y publicar activos en paralelo.

--asset-prebuild <BOOLEAN>

Especifique si desea crear todos los activos antes de implementar la primera pila. Esta opción es útil para compilaciones de Docker fallidas.

Valor predeterminado: true

--build-exclude, -E <ARRAY>

No reconstruya el activo con el identificador indicado.

Esta opción se puede especificar varias veces en un mismo comando.

Valor predeterminado: []

--change-set-name <STRING>

El nombre del conjunto de AWS CloudFormation cambios que se va a crear.

Esta opción no es compatible con --method='direct'.

--concurrency <NUMBER>

Implemente múltiples pilas en paralelo y, al mismo tiempo, tenga en cuenta las dependencias entre pilas. Utilice esta opción para acelerar las implementaciones. Aún debes tener en AWS CloudFormation cuenta otros límites de velocidad de la AWS cuenta.

Proporcione un número para especificar el número máximo de implementaciones simultáneas (si la dependencia lo permite) que se deben realizar.

Valor predeterminado: 1

--exclusively, -e <BOOLEAN>

Implemente solo las pilas solicitadas y no incluya las dependencias.

--express <BOOLEAN>

Implemente mediante el modo CloudFormation exprés. El modo exprés permite realizar despliegues más rápidos, ya que, en cuanto se CloudFormation aplica la configuración de recursos, notifica que las operaciones de pila se han completado. CloudFormation Sin embargo, CloudFormation informa de su éxito sin esperar a que los recursos se estabilicen. Además, el modo express no realiza la reversión automáticamente y deja las pilas en estado fallido si algo sale mal. Para habilitar la reversión automática con el modo rápido, incluye la --rollback marca en la implementación del modo rápido.

Para obtener más información, consulte el modo rápido en la Guía del AWS CloudFormation usuario.

nota

El modo exprés no espera a que se estabilice antes de informar que se ha realizado correctamente y no realiza una reversión automática en caso de error. No recomendamos el modo exprés para las implementaciones de producción. El modo exprés está orientado a las implementaciones iterativas que realizaría mientras desarrollaba su aplicación.

Valor predeterminado: false

--force, -f <BOOLEAN>

Cuando implemente para actualizar una pila existente, la CLI de CDK comparará la plantilla y las etiquetas de la pila implementada con las de la pila que se va a implementar. Si no se detectan cambios, la CLI de CDK se saltará la implementación.

Para anular este comportamiento e implementar siempre las pilas, incluso si no se detectan cambios, utilice esta opción.

Valor predeterminado: false

--help, -h <BOOLEAN>

Muestra la información de referencia del comando cdk deploy.

--hotswap <BOOLEAN>

Implementaciones de cambio en caliente para un desarrollo más rápido. Esta opción intenta realizar una implementación de cambio de caliente más rápida si es posible. Por ejemplo, si modificas el código de una función de Lambda en tu aplicación de CDK, la CLI del CDK actualizará el recurso directamente a través de las API de servicio en lugar de realizar una implementación. CloudFormation

Si la CLI de CDK detecta cambios que no admiten el cambio en caliente, dichos cambios se ignorarán y aparecerá un mensaje. Si prefiere realizar una CloudFormation implementación completa como alternativa, utilícela en su lugar. --hotswap-fallback

La CLI del CDK usa tus AWS credenciales actuales para realizar las llamadas a la API. No asume los roles de su pila de arranque, incluso si el indicador de característica @aws-cdk/core:newStyleStackSynthesis está establecido en true. Estas funciones no tienen los permisos necesarios para actualizar los AWS recursos directamente, sin usarlos CloudFormation. Por ese motivo, asegúrese de que sus credenciales pertenecen a la misma AWS cuenta de las pilas en las que está realizando despliegues de hotswap y de que tienen los permisos de IAM necesarios para actualizar los recursos.

El cambio en caliente se admite actualmente para los siguientes cambios:

  • Activos de código (incluidas imágenes de Docker y código en línea), cambios de etiquetas y cambios de configuración (solo se admiten variables de descripción y entorno) de las funciones de Lambda.

  • Versiones de Lambda y cambios de alias.

  • Cambios en la definición de las máquinas de estado de Step Functions. AWS

  • Cambios en los activos de contenedores de los servicios de Amazon ECS.

  • Cambios en los activos del sitio web de las implementaciones del bucket de Amazon S3.

  • Cambios en el origen y el entorno de AWS CodeBuild los proyectos.

  • Cambios en la plantilla de mapeo de VTL para los AWS AppSync resolutores y las funciones.

  • Cambios en el esquema de las API de AWS AppSync GraphQL.

  • Cambios en la API REST, la implementación y los métodos para Amazon API Gateway.

  • Cambios en la API y la integración de Amazon API Gateway V2.

  • Cambios en la configuración de los agentes de Amazon Bedrock.

  • Cambios en la configuración de Amazon Bedrock Runtime AgentCore

  • Cambios en las reglas de Amazon EventBridge.

  • Cambios en la configuración de las tablas globales y tablas de Amazon DynamoDB.

  • Cambios en la configuración de las colas de Amazon SQS.

  • Cambios en la alarma, la alarma compuesta y el panel de control de Amazon. CloudWatch

Se admite el uso de determinadas funciones CloudFormation intrínsecas como parte de una implementación intercambiada en caliente. Entre ellos se incluyen:

  • Ref

  • Fn::GetAtt— Solo se admite parcialmente y utiliza una combinación de API de Cloud Control e implementaciones personalizadas. Consulta la lista de recursos compatibles con la API de Cloud Control y esta implementación para ver la lista completa de los recursos compatibles.

  • Fn::ImportValue

  • Fn::Join

  • Fn::Select

  • Fn::Split

  • Fn::Sub

Esta opción también es compatible con las pilas anidadas.

nota

  • Esta opción introduce deliberadamente la dispersión en CloudFormation las pilas para acelerar las implementaciones. Por este motivo, utilícela únicamente con fines de desarrollo. No utilice esta opción para sus implementaciones de producción.

  • Los valores predeterminados de algunos parámetros pueden ser diferentes a los del parámetro de cambio en caliente. Por ejemplo, el porcentaje mínimo de estado de un servicio Amazon ECS se establecerá actualmente en 0. Si esto ocurre, revise la fuente en consecuencia.

  • Cuando realice un CloudFormation despliegue después de otro de intercambio en caliente, utilícelo cdk deploy --revert-drift para implementar con un conjunto de cambios que tenga en cuenta las variaciones y conciliar cualquier variación introducida por el intercambio en caliente.

Valor predeterminado: false

--hotswap-fallback <BOOLEAN>

--hotswapEsta opción es similar a. La diferencia es que --hotswap-fallback recurrirá a realizar un CloudFormation despliegue si se detecta un cambio que lo requiera.

Para obtener más información acerca de esta opción, consulta --hotswap.

Valor predeterminado: false

--ignore-no-stacks <BOOLEAN>

Realice una implementación incluso si su aplicación de CDK no contiene ninguna pila.

Esta opción resulta útil en el siguiente escenario: puede que tenga una aplicación con varios entornos, como dev y. prod Al iniciar el desarrollo, es posible que su aplicación de producción no tenga ningún recurso o que los recursos estén comentados. Esto provocará un error de implementación con un mensaje que indica que la aplicación no tiene pilas. Utilice --ignore-no-stacks para evitar este error.

Valor predeterminado: false

--import-existing-resources <BOOLEAN>

Importe los AWS CloudFormation recursos existentes y no administrados de su AWS cuenta.

Cuando utilices esta opción, los recursos de tu AWS CloudFormation plantilla sintetizada con el mismo nombre personalizado que los recursos no gestionados existentes en la misma cuenta se importarán a tu pila.

Puede usar esta opción para importar los recursos existentes a pilas nuevas o a pilas existentes.

Puede importar los recursos existentes e implementar nuevos recursos en el mismo comando cdk deploy.

Para obtener más información sobre los nombres personalizados, consulta el tipo de nombre en la Guía del AWS CloudFormation usuario.

Para obtener más información sobre el ImportExistingResources CloudFormation parámetro, consulte AWS CloudFormation Simplifica la importación de recursos con un nuevo parámetro para ChangeSets.

Para obtener más información sobre el uso de esta opción, consulte Importar los recursos existentes en el repositorio GitHub aws-cdk-cli.

--logs <BOOLEAN>

Muestre el CloudWatch registro de Amazon en la salida estándar (stdout) para todos los eventos de todos los recursos de las pilas seleccionadas.

Esta opción es únicamente compatible con --watch.

Valor predeterminado: true

--method, -m <STRING>

Configure el método para ejecutar una implementación.

  • change-set: método predeterminado. La CLI del CDK crea un conjunto de CloudFormation cambios con los cambios que se implementarán y, a continuación, realiza la implementación.

  • direct: no cree un conjunto de cambios. En su lugar, aplique el cambio inmediatamente. Esto suele ser más rápido que crear un conjunto de cambios, pero se pierden los detalles de progreso de la implementación en el resultado de la CLI.

  • prepare-change-set: cree un conjunto de cambios pero no realice la implementación. Esto resulta útil si dispone de herramientas externas que inspeccionarán el conjunto de cambios o si tiene un proceso de aprobación de los conjuntos de cambios. Se utiliza execute-change-set para ejecutar el conjunto de cambios preparado.

  • execute-change-set— Ejecute un conjunto de cambios con el que se creó anteriormenteprepare-change-set. El nombre del conjunto de cambios se establece de forma predeterminada encdk-deploy-change-set, o puede especificar un nombre personalizado con--change-set-name.

Valores válidos: change-set, direct, execute-change-set, prepare-change-set

Valor predeterminado: change-set

--notification-arns <ARRAY>

Los ARN de los temas de Amazon SNS en los que CloudFormation se notificarán los eventos relacionados con la pila.

--outputs-file, -O <STRING>

La ruta en la que se escriben los resultados de la pila de las implementaciones.

Tras la implementación, los resultados de la pila se escribirán en el archivo de salida especificado en formato JSON.

Puede configurar esta opción en el archivo cdk.json del proyecto o en ~/.cdk.json en su máquina de desarrollo local:

{
   "app": "npx ts-node bin/myproject.ts",
   // ...
   "outputsFile": "outputs.json"
}

Si se implementan varias pilas, los resultados se escriben en el mismo archivo de salida, organizados por claves que representan el nombre de la pila.

--parameters <ARRAY>

Transfiera parámetros adicionales CloudFormation durante la implementación.

Esta opción acepta una matriz con el siguiente formato: STACK:KEY=VALUE.

  • STACK: el nombre de la pila con la que se va a asociar el parámetro.

  • KEY: el nombre del parámetro de la pila.

  • VALUE: el valor que se transferirá en el momento de la implementación.

Si no se proporciona un nombre de pila, o si se proporciona * como nombre de pila, los parámetros se aplicarán a todas las pilas que se estén implementando. Si una pila no utiliza el parámetro, la implementación fallará.

Los parámetros no se propagan a las pilas anidadas. Para pasar los parámetros a las pilas anidadas, utilice el constructo NestedStack .

Valor predeterminado: {}

--previous-parameters <BOOLEAN>

Utilice los valores anteriores para los parámetros existentes.

Si esta opción está establecida en false, debe especificar todos los parámetros de cada implementación.

Valor predeterminado: true

--progress <STRING>

Configure la forma en que la CLI de CDK muestra el progreso de la implementación.

  • bar: muestra los eventos de implementación de la pila como una barra de progreso, con los eventos del recurso que se está implementando actualmente.

  • events— Proporcione un historial completo, incluidos todos los CloudFormation eventos.

También puede configurar esta opción en el archivo cdk.json del proyecto o en ~/.cdk.json en su máquina de desarrollo local:

{
   "progress": "events"
}

Valores válidos: bar, events

Valor predeterminado: bar

--require-approval <STRING>

Especifique qué cambios requieren aprobación manual.

  • any-change: se requiere una aprobación manual para cualquier cambio en la pila.

  • broadening: se requiere la aprobación manual si los cambios implican una ampliación de los permisos o las reglas de los grupos de seguridad.

  • never: no se requiere aprobación.

Valores válidos: any-change, broadening, never

Valor predeterminado: broadening

--revert-drift

Utilice un conjunto de cambios que tenga en cuenta las variaciones para la implementación. Esto crea un conjunto de cambios con el modo CloudFormation de REVERT_DRIFT implementación, que detecta los recursos que se han desviado de sus definiciones de plantilla debido a cambios fuera de banda y los revierte al estado deseado definido en la plantilla.

Consulta la documentación de Cloudformation sobre los conjuntos de cambios adaptados a las variaciones para obtener más información sobre su funcionamiento.

Valor predeterminado: false

--rollback | --no-rollback, -R

Durante la implementación, si no se puede crear o actualizar un recurso, la implementación volverá al último estado estable antes de que la CLI de CDK vuelva. Todos los cambios realizados hasta ese momento se anularán. Los recursos que se crearon se eliminarán y las actualizaciones que se hayan realizado se revertirán.

Especifique --no-rollback para desactivar este comportamiento. Si no se puede crear o actualizar un recurso, la CLI de CDK dejará en su lugar los cambios realizados hasta ese momento y regresará. Esto dejará la implementación en un estado fallido y pausado. Desde aquí, puede actualizar el código y volver a intentar la implementación. Esto puede resultar útil en entornos de desarrollo en los que se realiza una iteración rápida.

Si falla una implementación realizada con --no-rollback y decide que quiere revertirla, puede usar el comando cdk rollback. Para obtener más información, consulte Reversión de CDK.

nota

Con --no-rollback, las implementaciones que provocan la sustitución de recursos siempre fallarán. Solo puede utilizar este valor de opción para las implementaciones que actualicen o creen nuevos recursos.

Valor predeterminado: --rollback

--toolkit-stack-name <STRING>

El nombre de la pila del kit de herramientas de CDK existente.

De forma predeterminada, cdk bootstrap implementa una pila denominada CDKToolkit en el entorno especificado. AWS Utilice esta opción para proporcionar un nombre diferente a la pila de arranque.

La CLI de CDK usa este valor para verificar la versión de la pila de arranque.

--watch <BOOLEAN>

Observe continuamente los archivos de proyecto del CDK e implemente las pilas especificadas automáticamente cuando se detecten cambios.

Esta opción implica --hotswap de forma predeterminada.

Esta opción tiene un comando de la CLI de CDK equivalente. Para obtener más información, consulte Supervisión de CDK.

Ejemplos

Implementa la pila denominada MyStackName

$ cdk deploy MyStackName --app='node bin/main.js'

Implementación de varias pilas en una aplicación

Utilice cdk list para enumerar sus pilas:

$ cdk list
CdkHelloWorldStack
CdkStack2
CdkStack3

Para implementar todas las pilas, use la opción --all:

$ cdk deploy --all

Para elegir qué pilas implementar, proporcione los nombres de las pilas como argumentos:

$ cdk deploy CdkHelloWorldStack CdkStack3

Implementación de pilas de canalizaciones

Use cdk list para mostrar los nombres de las pilas como rutas, mostrando dónde se encuentran en la jerarquía de canalización:

$ cdk list
PipelineStack
PiplelineStack/Prod
PipelineStack/Prod/MyService

Usa la opción --all o el comodín * para implementar todas las pilas. Si tiene una jerarquía de pilas como la descrita anteriormente, --all y * solo coincidirán con las del nivel superior. Para hacer coincidir todas las pilas de la jerarquía, use **.

Puede combinar estos patrones. Lo siguiente implementa todas las pilas en el escenario Prod:

$ cdk deploy PipelineStack/Prod/**

Pase los parámetros en el momento de la implementación

Defina los parámetros en su pila de CDK. A continuación, se muestra un ejemplo de creación de un parámetro con el nombre TopicNameParam para un tema de Amazon SNS:

new sns.Topic(this, 'TopicParameter', {
    topicName: new cdk.CfnParameter(this, 'TopicNameParam').value.toString()
});

Para proporcionar un valor de parámetro de parameterized, ejecute lo siguiente:

$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterized"

Puede anular los valores de los parámetros mediante la opción --force. A continuación, se muestra un ejemplo de cómo anular el nombre de tema de una implementación anterior:

$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterName" --force

Escriba los resultados de la pila en un archivo después de la implementación

Defina las salidas en su archivo de pila de CDK. El siguiente es un ejemplo que crea una salida para función de ARN:

const fn = new lambda.Function(this, "fn", {
  handler: "index.handler",
  code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
  runtime: lambda.Runtime.NODEJS_LATEST
});

new cdk.CfnOutput(this, 'FunctionArn', {
  value: fn.functionArn,
});

Implemente la pila y escriba los resultados en outputs.json:

$ cdk deploy --outputs-file outputs.json

A continuación, se muestra un ejemplo de outputs.json luego de la implementación:

{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  }
}

A partir de este ejemplo, la clave FunctionArn corresponde al identificador lógico de la instancia CfnOutput.

A continuación, se muestra un ejemplo de outputs.json posterior a la implementación en el que se implementan varias pilas:

{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  },
  "AnotherStack": {
    "VPCId": "vpc-z0mg270fee16693f"
  }
}

Modificación en el método de implementación

Para realizar una implementación más rápida, sin utilizar conjuntos de cambios, utilice --method='direct':

$ cdk deploy --method='direct'

Para crear un conjunto de cambios pero no implementarlo, utilice --method='prepare-change-set'. De forma predeterminada, se creará un conjunto de cambios con el nombre cdk-deploy-change-set. Si existe un conjunto de cambios anterior con este nombre, se sobrescribirá. Si no se detecta ningún cambio, se seguirá creando un conjunto de cambios vacío.

También puede asignar un nombre al conjunto de cambios. A continuación, se muestra un ejemplo:

$ cdk deploy --method='prepare-change-set' --change-set-name='MyChangeSetName'