Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # Deploying an AWS CDK app with a workflow This section describes how to deploy an AWS Cloud Development Kit (AWS CDK) app into your AWS account using a workflow. To accomplish this, you must add the **AWS CDK deploy** action to your workflow. The **AWS CDK deploy** action synthesizes and deploys your AWS Cloud Development Kit (AWS CDK) app into AWS. If your app already exists in AWS, the action updates it if necessary. For general information about writing apps using the AWS CDK, see [What is the AWS CDK?](https://docs.aws.amazon.com/cdk/v2/guide/home.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. **Topics** + [When to use the 'AWS CDK deploy' action](#cdk-dep-action-when-to-use) + [How the 'AWS CDK deploy' action works](#cdk-dep-action-how-it-works) + [CDK CLI versions used by the 'AWS CDK deploy' action](#cdk-dep-action-cdk-version) + [Runtime image used by the 'AWS CDK deploy' action](#cdk-dep-action-runtime) + [How many stacks can the action deploy?](#cdk-dep-action-how-many-stacks) + [Example: Deploying an AWS CDK app](cdk-dep-action-example-workflow.md) + [Adding the 'AWS CDK deploy' action](cdk-dep-action-add.md) + ['AWS CDK deploy' variables](cdk-dep-action-variables.md) + ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md) ## When to use the 'AWS CDK deploy' action Use this action if you have developed an app using the AWS CDK, and you now want to deploy it automatically as part of automated continuous integration and delivery (CI/CD) workflow. For example, you might want to deploy your AWS CDK app automatically whenever someone merges a pull request related to your AWS CDK app source. ## How the 'AWS CDK deploy' action works The **AWS CDK deploy** works as follows: 1. At runtime, if you specified version 1.0.12 or earlier of the action, the action downloads the latest CDK CLI (also called the AWS CDK Tookit) to the CodeCatalyst [runtime environment image](#cdk-dep-action-runtime). If you specified version 1.0.13 or later, the action comes bundled with a [specific version](#cdk-dep-action-cdk-version) of the CDK CLI, so no download occurs. 1. The action uses the CDK CLI to run the `cdk deploy` command. This command synthesizes and deploys your AWS CDK app into AWS. For more information about this command, see the [AWS CDK Toolkit (cdk command)](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) topic in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. ## CDK CLI versions used by the 'AWS CDK deploy' action The following table shows which version of the CDK CLI is used by default by different versions of the **AWS CDK deploy** action. **Note** You might be able to override the default. For more information, see [CdkCliVersion](cdk-dep-action-ref.md#cdk.dep.cdk.cli.version) in the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). | 'AWS CDK deploy' action version | AWS CDK CLI version | | --- | --- | | 1.0.0 – 1.0.12 | latest | | 1.0.13 or later | 2.99.1 | ## Runtime image used by the 'AWS CDK deploy' action The following table shows the runtime environment images that CodeCatalyst uses to run different versions of the **AWS CDK deploy** action. The images include different sets of preinstalled tooling. For more information, see [Active images](build-images.md#build-curated-images). **Note** We recommend upgrading your **AWS CDK deploy** action to version 2.x to take advantage of the latest tooling available on the March 2024 image. To upgrade the action, set its `Identifier` property to `aws/cdk-deploy@v2` in your workflow definition file. For more information, see ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). | 'AWS CDK deploy' action version | Runtime environment images | | --- | --- | | 1.x | November 2022 images | | 2.x | March 2024 images | ## How many stacks can the action deploy? The **AWS CDK deploy** can deploy a single stack only. If your AWS CDK app consists of multiple stacks, you must create a parent stack with nested stacks, and deploy the parent using this action. # Example: Deploying an AWS CDK app The following example workflow includes the **AWS CDK deploy** action, along with the **AWS CDK bootstrap** action. The workflow consists of the following building blocks that run sequentially: + A **trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. This repository contains your AWS CDK app. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). + An **AWS CDK bootstrap** action (`CDKBootstrap`) – On trigger, the action deploys the `CDKToolkit` bootstrap stack into AWS. If the `CDKToolkit` stack already exists in the environment, it will be upgraded if necessary; otherwise, nothing happens, and the action is marked as succeeded. + An **AWS CDK deploy** action (`AWS CDKDeploy`) – On completion of the **AWS CDK bootstrap** action, the **AWS CDK deploy** action synthesizes your AWS CDK app code into an CloudFormation template and deploys the stack defined in the template into AWS. **Note** The following workflow example is for illustrative purposes, and will not work without additional configuration. **Note** In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies required by the **AWS CDK bootstrap** and **AWS CDK deploy** actions. For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md). For more information about the permissions and trust policies required by the **AWS CDK bootstrap** and **AWS CDK deploy** actions, see the description of the `Role` property in the ['AWS CDK bootstrap' action YAML](cdk-boot-action-ref.md) and ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). ``` Name: codecatalyst-cdk-deploy-workflow SchemaVersion: 1.0 Triggers: - Type: PUSH Branches: - main Actions: CDKBootstrap: Identifier: aws/cdk-bootstrap@v2 Inputs: Sources: - WorkflowSource Environment: Name: codecatalyst-cdk-deploy-environment Connections: - Name: codecatalyst-account-connection Role: codecatalyst-cdk-bootstrap-role Configuration: Region: us-west-2 CDKDeploy: Identifier: aws/cdk-deploy@v2 DependsOn: - CDKBootstrap Environment: Name: codecatalyst-cdk-deploy-environment Connections: - Name: codecatalyst-account-connection Role: codecatalyst-cdk-deploy-role Inputs: Sources: - WorkflowSource Configuration: StackName: my-app-stack Region: us-west-2 ``` # Adding the 'AWS CDK deploy' action Use the following instructions to add the **AWS CDK deploy** action to your workflow. **Before you begin** Before you can add the **AWS CDK deploy** action to your workflow, complete the following tasks: 1. **Have an AWS CDK app ready**. You can write your AWS CDK app using AWS CDK v1 or v2, in any programming language supported by the AWS CDK. Make sure your AWS CDK app files are available in: + A CodeCatalyst [source repository](source.md), or + A CodeCatalyst [output artifact](workflows-working-artifacts.md) generated by another workflow action 1. **Bootstrap your AWS environment**. To bootstrap, you can: + Use one of the methods described in [How to bootstrap](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html#bootstrapping-howto) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. + Use the **AWS CDK bootstrap** action. You can add this action in the same workflow as your **AWS CDK deploy**, or in a different one. Just make sure the bootstrap action runs at least once prior to running the **AWS CDK deploy** action so that the necessary resources are in place. For more information about the**AWS CDK bootstrap** action, see [Bootstrapping an AWS CDK app with a workflow](cdk-boot-action.md). For more information about bootstrapping, see [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. ------ #### [ Visual ] **To add the 'AWS CDK deploy' action using the visual editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. At the top-left, choose **\$1 Actions** to open the action catalog. 1. From the drop-down list, choose **Amazon CodeCatalyst**. 1. Search for the **AWS CDK deploy** action, and do one of the following: + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane. Or + Choose **AWS CDK deploy**. The action details dialog box appears. On this dialog box: + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title). + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane. 1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and then choose **Commit** again. **Note** If your **AWS CDK deploy** action fails with an `npm install` error, see [How do I fix "npm install" errors?](troubleshooting-workflows.md#troubleshooting-workflows-npm) for information about how to fix the error. ------ #### [ YAML ] **To add the 'AWS CDK deploy' action using the YAML editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. At the top-left, choose **\$1 Actions** to open the action catalog. 1. From the drop-down list, choose **Amazon CodeCatalyst**. 1. Search for the **AWS CDK deploy** action, and do one of the following: + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane. Or + Choose **AWS CDK deploy**. The action details dialog box appears. On this dialog box: + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title). + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane. 1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and then choose **Commit** again. **Note** If your **AWS CDK deploy** action fails with an `npm install` error, see [How do I fix "npm install" errors?](troubleshooting-workflows.md#troubleshooting-workflows-npm) for information about how to fix the error. ------ # 'AWS CDK deploy' variables The **AWS CDK deploy** action produces and sets the following variables at run time. These are known as *predefined variables*. For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md). | Key | Value | | --- | --- | | stack-id | The Amazon Resource Name (ARN) of the AWS CDK application stack that was deployed to during the workflow run. Example: `arn:aws:cloudformation:us-west-2:111122223333:stack/codecatalyst-cdk-app-stack/6aad4380-100a-11ec-a10a-03b8a84d40df` | | deployment-platform | The name of the deployment platform. Hardcoded to `AWS:CloudFormation`. | | region | The region code of the AWS Region that was deployed to during the workflow run. Example: `us-west-2` | | SKIP-DEPLOYMENT | A value of `true` indicates that deployment of your AWS CDK application stack was skipped during the workflow run. A stack deployment will be skipped if there is no change in the stack since the last deployment. This variable is only produced if its value is `true`. Hardcoded to `true`. | | *CloudFormation variables* | In addition to generating the variables listed previously, the **AWS CDK deploy** action also exposes *CloudFormation* output variables as *workflow* variables for use in subsequent workflow actions. By default, the action only exposes the first four (or fewer) CloudFormation variables that it finds. To determine which ones are exposed, run the **AWS CDK deploy** action once, and then look in the **Variables** tab of the run details page. If the variables listed on the **Variables** tab are not what you want, you can configure different ones using the `CfnOutputVariables` YAML property. For more information, see the [CfnOutputVariables](cdk-dep-action-ref.md#cdk.dep.cfn.out) property description in the ['AWS CDK deploy' action YAML](cdk-dep-action-ref.md). | # 'AWS CDK deploy' action YAML The following is the YAML definition of the **AWS CDK deploy** action. To learn how to use this action, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md). This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md). **Note** Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use **Ctrl\$1F**. The element will be listed with its associated YAML property. ``` # The workflow definition starts here. # See Top-level properties for details. Name: MyWorkflow SchemaVersion: 1.0 Actions: # The action definition starts here. CDKDeploy\$1nn: Identifier: aws/cdk-deploy@v2 DependsOn: - CDKBootstrap Compute: Type: EC2 | Lambda Fleet: fleet-name Timeout: timeout-minutes Inputs: # Specify a source or an artifact, but not both. Sources: - source-name-1 Artifacts: - artifact-name Outputs: Artifacts: - Name: cdk_artifact Files: - "cdk.out/**/*" Environment: Name: environment-name Connections: - Name: account-connection-name Role: iam-role-name Configuration: StackName: my-cdk-stack Region: us-west-2 Tags: '{"key1": "value1", "key2": "value2"}' Context: '{"key1": "value1", "key2": "value2"}' CdkCliVersion: version CdkRootPath: directory-containing-cdk.json-file CfnOutputVariables: '["CnfOutputKey1","CfnOutputKey2","CfnOutputKey3"]' CloudAssemblyRootPath: path-to-cdk.out ``` ## CDKDeploy (Required) Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names. Default: `CDKDeploy_nn`. Corresponding UI: Configuration tab/**Action name** ## Identifier (*CDKDeploy*/**Identifier**) (Required) Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md). **Note** Specifying `aws/cdk-deploy@v2` causes the action to run on the [March 2024 image](build-images.md#build.default-image) which includes newer tooling such as Node.js 18. Specifying `aws/cdk-deploy@v1` causes the action to run on the [November 2022 image](build-images.md#build.previous-image) which includes older tooling such as Node.js 16. Default: `aws/cdk-deploy@v2`. Corresponding UI: Workflow diagram/CDKDeploy\$1nn/**aws/cdk-deploy@v2** label ## DependsOn (*CDKDeploy*/**DependsOn**) (Optional) Specify an action or action group that must run successfully in order for the **AWS CDK deploy** action to run. We recommend specifying the **AWS CDK bootstrap** action in the `DependsOn` property, like this: ``` CDKDeploy: Identifier: aws/cdk-deploy@v2 DependsOn: - CDKBootstrap ``` **Note** [Bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) is a mandatory prerequisite for deploying an AWS CDK app. If you do not include the **AWS CDK Bootstrap** action in your workflow, then you must find another way to deploy the AWS CDK bootstrap stack before running your **AWS CDK deploy** action. For more information, see [Adding the 'AWS CDK deploy' action](cdk-dep-action-add.md) in [Deploying an AWS CDK app with a workflow](cdk-dep-action.md). For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md). Corresponding UI: Inputs tab/**Depends on - optional** ## Compute (*CDKDeploy*/**Compute**) (Optional) The computing engine used to run your workflow actions. You can specify compute either at the workflow level or at the action level, but not both. When specified at the workflow level, the compute configuration applies to all actions defined in the workflow. At the workflow level, you can also run multiple actions on the same instance. For more information, see [Sharing compute across actions](compute-sharing.md). Corresponding UI: *none* ## Type (*CDKDeploy*/Compute/**Type**) (Required if [Compute](#cdk.dep.computename) is included) The type of compute engine. You can use one of the following values: + **EC2** (visual editor) or `EC2` (YAML editor) Optimized for flexibility during action runs. + **Lambda** (visual editor) or `Lambda` (YAML editor) Optimized action start-up speeds. For more information about compute types, see [Compute types](workflows-working-compute.md#compute.types). Corresponding UI: Configuration tab/Advanced - optional/**Compute type** ## Fleet (*CDKDeploy*/Compute/**Fleet**) (Optional) Specify the machine or fleet that will run your workflow or workflow actions. With on-demand fleets, when an action starts, the workflow provisions the resources it needs, and the machines are destroyed when the action finishes. Examples of on-demand fleets: `Linux.x86-64.Large`, `Linux.x86-64.XLarge`. For more information about on-demand fleets, see [On-demand fleet properties](workflows-working-compute.md#compute.on-demand). With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. For more information about provisioned fleets, see [Provisioned fleet properties](workflows-working-compute.md#compute.provisioned-fleets). If `Fleet` is omitted, the default is `Linux.x86-64.Large`. Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet** ## Timeout (*CDKDeploy*/**Timeout**) (Required) Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout. Corresponding UI: Configuration tab/**Timeout - optional ** ## Inputs (*CDKDeploy*/**Inputs**) (Optional) The `Inputs` section defines the data that the `CDKDeploy` needs during a workflow run. **Note** Only one input (either a source or an artifact) is allowed for each **AWS CDK deploy** action. Corresponding UI: **Inputs** tab ## Sources (*CDKDeploy*/Inputs/**Sources**) (Required if the AWS CDK app you want to deploy is stored in a source repository) If your AWS CDK app is stored in a source repository, specify the label of that source repository. The **AWS CDK deploy** action synthesizes the app in this repository before starting the deployment process. Currently, the only supported label is `WorkflowSource`. If your AWS CDK app is not contained within a source repository, it must reside in an artifact generated by another action. For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md). Corresponding UI: Inputs tab/**Sources - optional** ## Artifacts - input (*CDKDeploy*/Inputs/**Artifacts**) (Required if the AWS CDK app you want to deploy is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action) If your AWS CDK app is contained in an artifact generated by a previous action, specify that artifact here. The **AWS CDK deploy** action synthesizes the app in the specified artifact into a CloudFormation template before starting the deployment process. If your AWS CDK app is not contained within an artifact, it must reside in your source repository. For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md). Corresponding UI: Inputs tab/**Artifacts - optional** ## Outputs (*CDKDeploy*/**Outputs**) (Optional) Defines the data that is output by the action during a workflow run. Corresponding UI: **Outputs** tab ## Artifacts - output (*CDKDeploy*/Outputs/**Artifacts** (Optional) Specify the artifacts generated by the action. You can reference these artifacts as input in other actions. For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md). Corresponding UI: Outputs tab/**Artifacts** ## Name (*CDKDeploy*/Outputs/Artifacts/**Name**) (Required if [Artifacts - output](#cdk.dep.outputs.artifacts) is included) Specify the name of the artifact that will contain the CloudFormation template that is synthesized by the **AWS CDK deploy** action at runtime. The default value is `cdk_artifact`. If you do not specify an artifact, then the action synthesizes the template but won't save it in an artifact. Consider saving the synthesized template in an artifact to preserve a record of it for testing or troubleshooting purposes. Corresponding UI: Outputs tab/Artifacts/Add artifact/**Build artifact name** ## Files (*CDKDeploy*/Outputs/Artifacts/**Files**) (Required if [Artifacts - output](#cdk.dep.outputs.artifacts) is included) Specify the files to include in the artifact. You must specify `"cdk.out/**/*"` to include your AWS CDK app's synthesized CloudFormation template. **Note** `cdk.out` is the default directory into which synthesized files are saved. If you specified an output directory other than `cdk.out` in your `cdk.json` file, specify that directory here instead of `cdk.out`. Corresponding UI: Outputs tab/Artifacts/Add artifact/**Files produced by build** ## Environment (*CDKDeploy*/**Environment**) (Required) Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC. **Note** If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md). For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md). Corresponding UI: Configuration tab/**Environment** ## Name (*CDKDeploy*/Environment/**Name**) (Required if [Environment](#cdk.dep.environment) is included) Specify the name of an existing environment that you want to associate with the action. Corresponding UI: Configuration tab/**Environment** ## Connections (*CDKDeploy*/Environment/**Connections**) (Optional in newer versions of the action; required in older versions) Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`. If you do not specify an account connection: + The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md). + The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation. For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md). Corresponding UI: One of the following depending on the action version: + (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** + (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection** ## Name (*CDKDeploy*/Environment/Connections/**Name**) (Required if [Connections](#cdk.dep.environment.connections) is included) Specify the name of the account connection. Corresponding UI: One of the following depending on the action version: + (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** + (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection** ## Role (*CDKDeploy*/Environment/Connections/**Role**) (Required if [Connections](#cdk.dep.environment.connections) is included) Specify the name of the account connection. Specify the name of the IAM role that the **AWS CDK deploy** action uses to access AWS and deploy the AWS CDK application stack. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies. If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies. + The following permissions policy: **Warning** Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "cloudformation:DescribeStackEvents", "cloudformation:DescribeChangeSet", "cloudformation:DescribeStacks", "cloudformation:ListStackResources" ], "Resource": "*" }, { "Sid": "VisualEditor1", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::111122223333:role/cdk-*" } ] } ``` ------ + The following custom trust policy: **Note** You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. Corresponding UI: One of the following depending on the action version: + (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** + (Older versions) Configuration tab/'Environment/account/role'/**Role** ## Configuration (*CDKDeploy*/**Configuration**) (Required) A section where you can define the configuration properties of the action. Corresponding UI: **Configuration** tab ## StackName (*CDKDeploy*/Configuration/**StackName**) (Required) The name of your AWS CDK app stack, as it appears in the entrypoint file in your AWS CDK app's `bin` directory. The following example shows the contents of a TypeScript entrypoint file, with the stack name highlighted in *red italics*. If your entrypoint file is in a different language, it will look similar. ``` import * as cdk from 'aws-cdk-lib'; import { CdkWorksopTypescriptStack } from '../lib/cdk_workshop_typescript-stack'; const app = new cdk.App(); new CdkWorkshopTypescriptStack(app, 'CdkWorkshopTypescriptStack'); ``` You can only specify one stack. **Tip** If you have multiple stacks, you can create a parent stack with nested stacks. You can then specify the parent stack in this action to deploy all stacks. Corresponding UI: Configuration tab/**Stack name** ## Region (*CDKDeploy*/Configuration/**Region**) (Optional) Specify the AWS Region into which the AWS CDK application stack will be deployed. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes). If you do not specify a Region, the **AWS CDK deploy** action deploys into the Region specified in your AWS CDK code. For more information, see [Environments](https://docs.aws.amazon.com/cdk/v2/guide/environments.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. Corresponding UI: Configuration tab/**Region** ## Tags (*CDKDeploy*/Configuration/**Tags**) (Optional) Specify tags that you want to apply to the AWS resources in the AWS CDK application stack. Tags are applied to the stack itself as well as to individual resources in the stack. For more information about tagging, see [Tagging](https://docs.aws.amazon.com/cdk/v2/guide/tagging.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. Corresponding UI: Configuration tab/Advanced - optional/**Tags** ## Context (*CDKDeploy*/Configuration/**Context**) (Optional) Specify contexts, in the form of key-value pairs, to associate with the AWS CDK application stack. For more information about contexts, see [Runtime contexts](https://docs.aws.amazon.com/cdk/v2/guide/context.html) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. Corresponding UI: Configuration tab/Advanced - optional/**Context** ## CdkCliVersion (*CDKDeploy*/Configuration/**CdkCliVersion**) (Optional) This property is available with version 1.0.13 or later of the **AWS CDK deploy** action, and version 1.0.8 or later of the **AWS CDK bootstrap** action. Specify one of the following: + The full version of the AWS Cloud Development Kit (AWS CDK) Command Line Interface (CLI) (also called the AWS CDK Toolkit) that you want this action to use. Example: `2.102.1`. Consider specifying a full version to ensure consistency and stability when building and deploying your application. Or + `latest`. Consider specifying `latest` to take advantage of the latest features and fixes of the CDK CLI. The action will download the specified version (or the latest version) of the AWS CDK CLI to the CodeCatalyst [build image](build-images.md), and then use this version to run the commands necessary to deploy your CDK application or bootstrap your AWS environment. For a list of supported CDK CLI versions you can use, see [AWS CDK Versions](https://docs.aws.amazon.com/cdk/api/versions.html). If you omit this property, the action uses a default AWS CDK CLI version described in one of the following topics: + [CDK CLI versions used by the 'AWS CDK deploy' action](cdk-dep-action.md#cdk-dep-action-cdk-version) + [CDK CLI versions used by the "AWS CDK bootstrap" action](cdk-boot-action.md#cdk-boot-action-cdk-version) Corresponding UI: Configuration tab/**AWS CDK CLI version** ## CdkRootPath (*CDKDeploy*/Configuration/**CdkRootPath**) (Optional) The path to the directory that contains your AWS CDK project's `cdk.json` file. The **AWS CDK deploy** action runs from this folder, and any outputs created by the action will be added to this directory. If unspecified, the **AWS CDK deploy** action assumes that the `cdk.json` file is in the root of your AWS CDK project. Corresponding UI: Configuration tab/**Directory where the cdk.json resides** ## CfnOutputVariables (*CDKDeploy*/Configuration/**CfnOutputVariables**) (Optional) Specify which `CfnOutput` constructs in your AWS CDK application code you want to expose as workflow output variables. You can then reference the workflow output variables in subsequent actions in your workflow. For more information about variables in CodeCatalyst, see [Using variables in workflows](workflows-working-with-variables.md). For example, if your AWS CDK application code looks like this: ``` import { Duration, Stack, StackProps, CfnOutput, RemovalPolicy} from 'aws-cdk-lib'; import * as dynamodb from 'aws-cdk-lib/aws-dynamodb'; import * as s3 from 'aws-cdk-lib/aws-s3'; import { Construct } from 'constructs'; import * as cdk from 'aws-cdk-lib'; export class HelloCdkStack extends Stack { constructor(scope: Construct, id: string, props?: StackProps) { super(scope, id, props); const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { removalPolicy: RemovalPolicy.DESTROY, }); new CfnOutput(this, 'bucketName', { value: bucket.bucketName, description: 'The name of the s3 bucket', exportName: 'amzn-s3-demo-bucket', }); const table = new dynamodb.Table(this, 'todos-table', { partitionKey: {name: 'todoId', type: dynamodb.AttributeType.NUMBER}, billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, removalPolicy: RemovalPolicy.DESTROY, }) new CfnOutput(this, 'tableName', { value: table.tableName, description: 'The name of the dynamodb table', exportName: 'myDynamoDbTable', }); ... } } ``` ...and your `CfnOutputVariables` property looks like this: ``` Configuration: ... CfnOutputVariables: '["bucketName","tableName"]' ``` ...then the action generates the following workflow output variables: | Key | Value | | --- | --- | | bucketName | `bucket.bucketName` | | tableName | `table.tableName` | You can then reference the `bucketName` and `tableName` variables in subsequent actions. To learn how to reference workflow output variables in subsequent actions, see [Referencing a predefined variable](workflows-working-with-variables-reference-output-vars.md). If you do not specify any `CfnOutput` constructs in the `CfnOutputVariables` property, then the action exposes the first four (or fewer) CloudFormation output variables it finds as workflow output variables. For more information, see ['AWS CDK deploy' variables](cdk-dep-action-variables.md). **Tip** To obtain a list of all the CloudFormation output variables the action produces, run the workflow containing the **AWS CDK deploy** action once, and then look in the action's **Logs** tab. The logs contain a list of all the CloudFormation output variables associated with your AWS CDK app. Once you know what all the CloudFormation variables are, you can specify which ones you want to convert to workflow output variables using the `CfnOutputVariables` property. For more information about CloudFormation output variables, see the documentation for the `CfnOutput` construct, available at [class CfnOutput (construct)](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnOutput.html) in the *AWS Cloud Development Kit (AWS CDK) API Reference*. Corresponding UI: Configuration tab/**CloudFormation output variables** ## CloudAssemblyRootPath (*CDKDeploy*/Configuration/**CloudAssemblyRootPath**) (Optional) If you have already synthesized your AWS CDK app's stack into a cloud assembly (using the `cdk synth` operation), specify the root path of the cloud assembly directory (`cdk.out`). The CloudFormation template located in the specified cloud assembly directory will be deployed by the **AWS CDK deploy** action into your AWS account using the `cdk deploy --app` command. When the `--app` option is present, the `cdk synth` operation does not occur. If you do not specify a cloud assembly directory, then the **AWS CDK deploy** action will run the `cdk deploy` command without the `--app` option. Without the `--app` option, the `cdk deploy` operation will both synthesize (`cdk synth`) and deploy your AWS CDK app into your AWS account. **Why would I specify an existing, synthesized cloud assembly when the "AWS CDK deploy" action can do the synthesis at run time?** You might want to specify an existing, synthesized cloud assembly to: + **Ensure that the exact same set of resources are deployed every time the "AWS CDK deploy" action runs** If you don't specify a cloud assembly, it's possible for the **AWS CDK deploy** action to synthesize and deploy different files depending on when it is run. For example, the **AWS CDK deploy** action might synthesize a cloud assembly with one set of dependencies during a testing stage, and another set of dependencies during a production stage (if those dependencies changed between stages). To guarantee exact parity between what is tested and what is deployed, we recommend synthesizing once and then using the **Path to cloud assembly directory** field (visual editor) or `CloudAssemblyRootPath` property (YAML editor) to specify the already-synthesized cloud assembly. + **Use non-standard package managers and tooling with the AWS CDK app** During a `synth` operation, the **AWS CDK deploy** action tries to run your app using standard tools such as npm or pip. If the action can't successfully run your app using those tools, the synthesis will not occur and the action will fail. To work around this issue, you can specify the exact commands needed to run your app successfully in the AWS CDK app's `cdk.json` file, and then synthesize your app using a method that does not involve the **AWS CDK deploy** action. After the cloud assembly has been generated, you can specify it in the **Path to cloud assembly directory** field (visual editor) or `CloudAssemblyRootPath` property (YAML editor) of the **AWS CDK deploy** action. For information about configuring the `cdk.json` file to include commands for installing and running your AWS CDK app, see [Specifying the app command](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-app-command). For information about the `cdk deploy` and `cdk synth` commands, as well as the `--app` option, see [Deploying stacks](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy), [Synthesizing stacks](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-synth) and [Skipping synthesis](https://docs.aws.amazon.com/cdk/v2/guide/cli.html#cli-deploy-nosynth) in the *AWS Cloud Development Kit (AWS CDK) Developer Guide*. For information about cloud assemblies, see [Cloud Assembly](https://docs.aws.amazon.com/cdk/api/v2/docs/cloud-assembly-schema-readme.html) in the *AWS Cloud Development Kit (AWS CDK) API Reference*. Corresponding UI: Configuration tab/**Path to cloud assembly directory**