Skip to content

Execute Terragrunt packs in isolated workdir with generated inputs.auto.tfvars.json

Status

Proposed — Standardise Terragrunt execution so runs are isolated, reproducible, and evidence-first.

1. Context

Terragrunt stacks must be executed in a way that is:

  • independent of repository layout and current working directory
  • deterministic in its runtime paths and evidence capture
  • compatible with module input overrides
  • safe for packaged distribution (tarball-safe)

Terragrunt and Terraform support *.auto.tfvars.json for automatic variable loading. Using a generated file keeps packs immutable and gives the driver a stable injection mechanism.

2. Decision

The Terragrunt driver MUST:

1) Resolve the selected pack stack directory using the pack layout contract. 2) Create an isolated work directory under the runtime root: - <runtime_root>/work/<module_id>/<run_id>/ 3) Copy the pack stack into: - <workdir>/stack/ 4) Generate an inputs file in the stack directory: - <workdir>/stack/inputs.auto.tfvars.json 5) Execute Terragrunt from <workdir>/stack/: - terragrunt init - terragrunt apply - terragrunt output -json 6) Capture evidence for each step (stdout/stderr redacted by default) under the module evidence directory.

The driver MUST treat the pack source as immutable.

3. Inputs injection

3.1 Source of inputs

The driver consumes the resolved module input mapping (request["inputs"]) produced by module resolution.

3.2 File format and naming

The driver MUST write JSON tfvars using the Terraform supported format:

  • filename: inputs.auto.tfvars.json
  • content: a JSON object mapping variable names to values

The driver SHOULD also write an evidence pointer file into evidence:

  • inputs_tfvars.json containing the absolute path of the generated tfvars file

The tfvars file MUST be written into the workdir stack (not into evidence) to avoid leaking values into evidence artifacts.

4. Runtime environment injection

The driver MUST set:

  • HYOPS_RUNTIME_ROOT=<runtime_root>

The driver MAY set runtime-injected tool variables as applicable (example: HYOPS_GCP_TFVARS pointing to a credentials tfvars file under <runtime_root>/credentials/), but MUST NOT write secret material into evidence.

5. Evidence requirements

The driver MUST write:

  • driver_meta.json (pack resolution, workdir paths, non-secret env summary)
  • driver_result.json (status, normalized outputs)
  • terragrunt_init.*, terragrunt_apply.*, terragrunt_output.* result envelopes and redacted stdout/stderr captures

If execution fails, the driver MUST return status=error and MUST capture the failing step evidence before returning.

6. Consequences

6.1 Positive

  • Fully isolated runs and deterministic paths.
  • Packs remain immutable and reusable.
  • Simple, tool-native mechanism for passing structured inputs.
  • Evidence capture becomes consistent and reviewable.

6.2 Negative / risks

  • Copying packs into workdir adds overhead; acceptable for v1.
  • Some stacks may require additional profile-owned templates (backend/provider/hooks); these must be generated by profiles into the workdir, not embedded in modules.

7. Alternatives considered

  • Passing -var flags — rejected; unstable, harder to audit, and increases logging leakage risk.
  • Writing terraform.tfvars — rejected; less explicit than *.auto.tfvars.json and easier to collide with pack content.
  • Mutating pack source in-place — rejected; violates immutability and breaks parallel runs.

8. References