How to plan and apply multiple stacks with CDKTF

[paymog]

I have a CDKTF project with multiple stacks. I'm using custom workflows in atlantis. Are there canonical examples of how to plan/apply this particular setup? I'm having some trouble figuring out how to use the $PLANFILE when there are multiple stacks that need to be planned and applied, and especially when they have interstack dependencies.

[dosubot[bot]]

Hi @paymog! I'm Dosu and I’m helping the atlantis team.

Atlantis supports multi-stack CDKTF projects by treating each stack as a separate project, usually mapped to a directory containing a generated cdk.tf.json file. In your atlantis.yaml, define each stack as a project with its own dir and optionally a name. For custom workflows, use pre_workflow_hooks to run cdktf synth before planning, and in your plan/apply steps, always use $PLANFILE for the plan output and apply input—Atlantis manages this per project, so you don’t need to merge plan files across stacks.

To handle interstack dependencies, use the depends_on key in your project config, and/or execution_order_group to control orchestration. Atlantis will ensure dependent stacks are applied in the correct order and will block applies if dependencies aren’t met. You can also enable parallel_plan and parallel_apply for faster execution, respecting dependency order.

Here’s a canonical example structure (docs, docs):

version: 3
parallel_plan: true
parallel_apply: true
projects:
  - name: stack-a
    dir: stacks/stack-a
    workflow: cdk-workflow
    execution_order_group: 1
  - name: stack-b
    dir: stacks/stack-b
    workflow: cdk-workflow
    execution_order_group: 2
    depends_on:
      - stack-a
workflows:
  cdk-workflow:
    plan:
      steps:
        - run: cdktf synth
        - run: terraform init -input=false
        - run: terraform plan -input=false -refresh -out $PLANFILE
    apply:
      steps:
        - run: terraform apply $PLANFILE

Each project’s workflow uses $PLANFILE for its own plan/apply. Dependencies and execution order are managed in the config, not by sharing plan files. For CDKTF, make sure your Atlantis image has cdktf installed and that you include **/cdk.tf.json in your autoplan files.

Let me know if you want a more detailed example or have a specific workflow you’re trying to implement!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[paymog]

what if my two stacks aren't in different directories? and where is the pre workflow hook in the above example?

[dosubot[bot]]

If your two stacks aren't in different directories, you can still configure them as separate Atlantis projects by giving each a unique name (and, if needed, workspace) in your atlantis.yaml. For example, both projects can have the same dir, but must have different name values—this is required if they share the same directory and workspace, and is enforced by Atlantis validation. This lets Atlantis manage plan/apply for each stack independently, even within the same directory. See the official example here:

projects:
  - name: stack1
    dir: app
    workflow: cdk-workflow
  - name: stack2
    dir: app
    workflow: cdk-workflow

For CDKTF, you typically distinguish stacks by the generated cdk.tf.json files (e.g., in subfolders or with different workspaces), but Atlantis only cares about how you define the projects.

The pre-workflow hook isn't in the atlantis.yaml workflow definition—it lives in your server-side repo config (like repos.yaml). This hook runs before any workflow steps (plan/apply) and is where you should run cdktf synth to generate the Terraform JSON files. Example:

# repos.yaml
repos:
  - id: /.*/
    pre_workflow_hooks:
      - run: npm i && cdktf get && cdktf synth --output ci-cdktf.out

This ensures the necessary files are generated before Atlantis starts planning or applying. More details and examples are in the custom workflows and pre-workflow hooks docs.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}