Deployment Patterns

You can configure your Continuous Integration/Continuous Deployment (CI/CD) environment to automatically deploy your CDKTF applications. This page explains different types of deployment patterns to help you choose the methods that are most appropriate for your use case.

Deployment Methods

You can provision your infrastructure using either CDKTF CLI commands (e.g., cdktf deploy) or by synthesizing your application into a Terraform configuration file and using Terraform directly. Both approaches allow you to use HCP Terraform and integrate with a CI/CD pipeline.

Run CDKTF CLI Commands

We recommend using CDKTF CLI commands in the following use cases:

• Your application performs additional tasks For example, your application may build a Docker image or start a build pipeline locally through synchronous APIs. You might also be using the null provider to execute these actions when a resource is created (e.g., after the Docker registry has been created). Running cdktf deploy triggers all of these actions at runtime in addition to using Terraform to provision your infrastructure.

• Your application contains stacks with complex dependencies. Each stack in a CDKTF application is like a separate Terraform working directory. Terraform respects complex dependencies within the same configuration, but it is not designed to manage complex dependencies between multiple working directories. For example, if you define a stack A that depends on data from stack B and stack C, Terraform runs will fail. This is because Terraform will not understand that it must wait to build stack A until both stack B and stack C are completed.

Run cdktf synth and Use Terraform Directly

We recommend synthesizing your CDKTF application and using Terraform directly when you need to integrate into existing Terraform workflows. Your organization may already use HCP Terraform or have integrated Terraform into CI pipelines. In these cases, you may want to run cdktf synth and set the output folder to a particular directory that you can reference in your existing workflows.

Using HCP Terraform

HCP Terraform lets you review the current state of your infrastructure and run progress in the HCP Terraform UI. You can also use HCP Terraform as the source of secrets.

Refer to Set Up CDKTF With HCP Terraform for details. Refer to Example Workflows for several examples of connecting your CDKTF application to HCP Terraform and using HCP Terraform in a Continuous Integration pipeline.

Managing Secrets and Sensitive Data

You should read secrets with Terraform Variables so that they do not appear in your synthesized CDKTF code.

Example Workflows

The following examples demonstrate common deployment workflows for your CDKTF application.

Deploy with Terraform and HCP Terraform

Connect your synthesized CDKTF configuration to a HCP Terraform workspace with the following steps:

1. Add a pre-commit step in your CDKTF application that runs cdktf synth. This creates Terraform configuration files in the cdktf.out/stacks/<stack-name> directory.
2. Configure the VCS integration for a HCP Terraform workspace to point to the directory with the synthesized configuration files. To deploy multiple independent stacks, configure one HCP Terraform workspace to point to the output directory for each stack.

Refer to Automatic Run Triggering in the HCP Terraform documentation for details about how to trigger Terraform runs from merges and commits.

Terraform CDK GitHub Action

You can use the Terraform CDK GitHub Action if you are using GitHub Actions and you want a default review / deployment workflow. The Terraform CDK GitHub Action runs the CDKTF CLI under the hood, it comments Terraform plans on your pull requests and provides a default review workflow. If you need more customization, refer to GitHub Actions CI and HCP Terraform.

GitHub Actions CI and HCP Terraform

Set the TERRAFORM_CLOUD_TOKEN environment variable to the HCP Terraform API token. This allows the CDKTF stacks CloudBackend to connect to HCP Terraform.

You must create a job like this for every stack so that you can pass the stack name into cdktf diff <stack name>. None of the stacks can depend on each other because Terraform cannot reason about which stacks must be launched first to respect these dependencies.

The following example shows a GitHub Actions configuration where the CDKTF application is deployed from the main branch and uses HCP Terraform. You could store this file in .github/workflows/cdktf-deploy.yml.

name: CDKTF Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js 18.x
        uses: actions/setup-node@v3
        with:
          node-version: 18.x
          cache: "npm"
      - name: Install CDKTF CLI
        run: npm install -g cdktf-cli
      - name: Install Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.1.7
      - name: Install dependencies
        run: npm ci
      # If you use providers or modules that are not pre-built, you can install them here
      - name: Generate bindings for providers and modules
        run: cdktf get
      - name: Run Tests
        run: npm test
      - name: Deploy
        run: cdktf deploy --auto-approve '*' # Deploys all stacks
        env:
          TERRAFORM_CLOUD_TOKEN: ${{ secrets.TF_API_TOKEN }}

To get the plan output posted as a comment on your pull request, add the following to your .github/workflows/cdktf-diff.yml file:

name: CDKTF Diff

on: [pull_request]

jobs:
  diff:
    name: "Terraform CDK Diff"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v1
        with:
          terraform_version: 1.1.7
          cli_config_credentials_token: ${{ secrets.TF_CLOUD_TOKEN }}

      - uses: actions/setup-node@v1
        with:
          node-version: "14"

      - run: yarn install

      # CDKTF runs the plan here, so you need to fill in the name of your stack.
      - name: plan
        run: cdktf plan <stack name>
        env:
          TERRAFORM_CLOUD_TOKEN: ${{ secrets.TF_API_TOKEN }}
        continue-on-error: true # We want to see the plan output even if the plan fails

      # Replace this step with any workflow you like, e.g. posting a message in a slack channel.
      - uses: actions/github-script@0.9.0
        if: github.event_name == 'pull_request'
        env:
          PLAN: "terraform\n${{ steps.plan.outputs.stdout }}" # CDKTF gets the output from the last step
        with:
          github-token: ${{ secrets.GH_COMMENT_TOKEN }} # Create a secret with a GitHub token that can comment on PRs
          script: |
            const output = `#### Terraform Plan 📖\`${{ steps.plan.outcome }}\`
            <details><summary>Show Plan</summary>
            \`\`\`${process.env.PLAN}\`\`\`
            </details>
            *Pusher: @${{ github.actor }}, Action: \`${{ github.event_name }}\`, Working Directory: \`${{ env.tf_actions_working_dir }}\`, Workflow: \`${{ github.workflow }}\`*`;
            github.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            })

Running the CDKTF CLI on a General Purpose CI

If you have a general purpose CI like GitHub Actions or CircleCI configured, use the cdktf deploy --auto-approve <your stacks> command to trigger a deployment. This deploys your stacks in the right order and in parallel. To set up this workflow, you must install the following software:

• Node in version 14.0+
• The cdktf-cli CLI
• Terraform v1.0+
• Any other languages you use for your CDKTF application

Contribute Additional Examples

To share another solution, please open a GitHub issue or submit a pull request for this documentation page.