Terragrunt Preview Stack with Guaranteed Teardown in Kestra

id: terragrunt-preview-stack-teardown
namespace: company.team
description: |
  Ephemeral preview stack with guaranteed teardown. run-all apply brings
  up a preview folder, a placeholder task stands in for the test suite,
  and a finally block runs run-all destroy against the state handed over
  from the apply, so the stack is removed even when the tests fail.

tasks:
  - id: apply_preview
    type: io.kestra.plugin.terragrunt.cli.TerragruntCLI
    description: Apply every unit under live/preview and export the state files
      pinned to a predictable path by root.hcl, so the teardown task can find
      exactly what was created.
    containerImage: alpine/terragrunt
    inputFiles:
      live/root.hcl: |
        remote_state {
          backend = "local"

          generate = {
            path      = "backend.tf"
            if_exists = "overwrite"
          }

          config = {
            path = "${get_parent_terragrunt_dir()}/../state/${path_relative_to_include()}/terraform.tfstate"
          }
        }
      live/preview/network/terragrunt.hcl: |
        include "root" {
          path = find_in_parent_folders("root.hcl")
        }

        terraform {
          source = "${get_terragrunt_dir()}/../../../modules/network"
        }
      live/preview/app/terragrunt.hcl: |
        include "root" {
          path = find_in_parent_folders("root.hcl")
        }

        terraform {
          source = "${get_terragrunt_dir()}/../../../modules/app"
        }
      modules/network/main.tf: |
        resource "local_file" "network_manifest" {
          filename = "${path.module}/preview-network.txt"
          content  = "preview network\n"
        }
      modules/app/main.tf: |
        resource "local_file" "app_manifest" {
          filename = "${path.module}/preview-app.txt"
          content  = "preview app\n"
        }
    commands:
      - terragrunt run-all apply --non-interactive --working-dir live/preview
        -no-color
    outputFiles:
      - state/**/*.tfstate

  - id: run_preview_checks
    type: io.kestra.plugin.core.log.Log
    description: Placeholder for the real test suite. Replace with HTTP health
      checks, a Python test runner, or an end-to-end suite pointed at the
      preview stack.
    message: Preview stack is up, running placeholder checks against the temporary
      environment.

finally:
  - id: teardown_when_applied
    type: io.kestra.plugin.core.flow.If
    description: Destroy the preview stack whenever the apply produced state, even
      if the checks failed, so no execution leaks a preview environment.
    condition: "{{
      (outputs.apply_preview.outputFiles['state/preview/app/terraform.tfstate']
      ?? '') != '' }}"
    then:
      - id: destroy_preview
        type: io.kestra.plugin.terragrunt.cli.TerragruntCLI
        description: Recreate the repo layout, restore the state files exported by the
          apply task, and run run-all destroy against them.
        containerImage: alpine/terragrunt
        inputFiles:
          live/root.hcl: |
            remote_state {
              backend = "local"

              generate = {
                path      = "backend.tf"
                if_exists = "overwrite"
              }

              config = {
                path = "${get_parent_terragrunt_dir()}/../state/${path_relative_to_include()}/terraform.tfstate"
              }
            }
          live/preview/network/terragrunt.hcl: |
            include "root" {
              path = find_in_parent_folders("root.hcl")
            }

            terraform {
              source = "${get_terragrunt_dir()}/../../../modules/network"
            }
          live/preview/app/terragrunt.hcl: |
            include "root" {
              path = find_in_parent_folders("root.hcl")
            }

            terraform {
              source = "${get_terragrunt_dir()}/../../../modules/app"
            }
          modules/network/main.tf: |
            resource "local_file" "network_manifest" {
              filename = "${path.module}/preview-network.txt"
              content  = "preview network\n"
            }
          modules/app/main.tf: |
            resource "local_file" "app_manifest" {
              filename = "${path.module}/preview-app.txt"
              content  = "preview app\n"
            }
          state/preview/network/terraform.tfstate: "{{
            outputs.apply_preview.outputFiles['state/preview/network/terraform.\
            tfstate'] }}"
          state/preview/app/terraform.tfstate: "{{
            outputs.apply_preview.outputFiles['state/preview/app/terraform.tfst\
            ate'] }}"
        commands:
          - terragrunt run-all destroy --non-interactive --working-dir
            live/preview -no-color

errors:
  - id: alert_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Tell the team a preview run failed. The finally block has already
      torn down whatever the apply created.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Terragrunt preview stack run FAILED in flow {{ flow.id }} (execution {{ execution.id }}). Teardown ran in the finally block, verify nothing was left behind."
      }

Preview environments are only cheap when they reliably disappear. This blueprint applies a Terragrunt preview folder, runs a placeholder test step, and then destroys the stack from a finally block, the part of a Kestra flow that runs whether the tasks before it succeeded or failed. The interesting mechanics are in the state handoff: each Kestra task runs in its own container, so the apply task exports its Terraform state files as outputFiles, and the teardown task restores them via inputFiles before running run-all destroy.

To make that handoff deterministic, root.hcl pins state to a predictable path with a remote_state block, state/preview/network/terraform.tfstate and state/preview/app/terraform.tfstate, instead of letting it live inside Terragrunt's cache directories. The demo modules only create local_file resources, so the whole lifecycle runs without cloud credentials.

How it works

apply_preview (io.kestra.plugin.terragrunt.cli.TerragruntCLI) materializes the repo from inputFiles and runs terragrunt run-all apply --non-interactive --working-dir live/preview, bringing up both preview units.
The remote_state block in root.hcl writes each unit's state under a top-level state/ folder, and the task exports those files with outputFiles: state/**/*.tfstate.
run_preview_checks is a placeholder Log task standing in for your real test suite against the preview stack.
In the finally block, teardown_when_applied (io.kestra.plugin.core.flow.If) checks that the apply actually exported state, then destroy_preview recreates the same repo layout, restores both state files through inputFiles, and runs terragrunt run-all destroy --non-interactive.
The errors block posts a Slack alert on any failure, noting that teardown already ran.

What you get

Preview stacks that cannot outlive their execution, teardown runs on success, on test failure, and on most crashes.
A worked example of passing Terraform state between isolated Kestra tasks with outputFiles and inputFiles.
A guard condition that skips teardown cleanly when the apply never produced state.
A Slack alert for failed runs so leaked-resource suspicion triggers a manual check.

Who it's for

Teams reviewing infrastructure or application changes against short-lived, real stacks instead of shared staging.
Platform engineers who have been burned by orphaned preview environments quietly accruing cost.
Anyone building apply-test-destroy loops around Terragrunt.

Why orchestrate this with Kestra

Shell scripts implement this pattern with trap, until the runner dies, the step times out, or someone ctrl-c's the pipeline. Kestra's finally block is a first-class flow construct: it runs server-side regardless of upstream task state, its guard condition is declarative, and the execution history shows the apply, the checks, and the destroy as separate, individually logged tasks. The state handoff through Kestra's internal storage also means no shared runner disk is required between steps.

Prerequisites

A Slack incoming webhook for failure alerts.
No cloud credentials are needed for the demo. For real preview stacks, use a real remote state backend such as S3 or GCS in root.hcl, then the teardown task no longer needs the state file handoff, and pass provider credentials through task env from {{ secret('...') }}.

Secrets

SLACK_WEBHOOK_URL: Slack incoming webhook URL.

Quick start

Add the SLACK_WEBHOOK_URL secret to your Kestra namespace.
Execute the flow and watch the apply, the placeholder checks, and the destroy run in order.
Make the checks fail on purpose, for example by replacing the Log task with a failing script, and confirm the destroy still runs.

How to extend

Replace run_preview_checks with a real test runner, an HTTP health check task, or a container running your end-to-end suite.
Move state to a real backend in root.hcl, then drop the state entries from the teardown task's inputFiles, the backend becomes the handoff.
Trigger the flow from a pull request webhook and name the preview folder after the branch.
Switch the underlying binary to OpenTofu with an image that ships tofu and the TERRAGRUNT_TFPATH environment variable in the task env.

Ephemeral Terragrunt Preview Stacks with Guaranteed Teardown

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Ephemeral Terragrunt Preview Stacks with Guaranteed Teardown

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Page Squadcast on Batch SLA Breach

Rolling Ansible Patch Wave with Health Gates

Automatically Review GitHub Pull Requests with OpenAI GPT-4o and Post Comments

Ansible Scalability, Deploy Configuration Files to Multiple Servers at Scale

Render Kestra-Templated Ansible Playbooks Before Execution

Ship Kestra logs to Splunk

New to Kestra?