Docs

Install

Or download a binary from the releases page↗ (external site). A release ships terraken and tken, built from the same package, so use whichever name is free on your machine. Builds are for Linux, macOS, Windows, FreeBSD, OpenBSD and Solaris; there is no native Windows build, so on Windows it wants WSL.

Use

Terraken reads a plan that Terraform or OpenTofu has already produced:

Or read it from standard input and never write the plan to disk at all. This is the better habit: plan JSON can hold a credential in the clear, and a file on a shared runner is one more place for one to be left.

Flags go before the file. Go's flag parsing stops at the first positional argument, so a flag written after the filename is not read. Terraken notices that case and tells you what to type instead of exiting on a bare usage block.

Flags

--min-level and --fail-on are independent on purpose. Filtering changes what you read, never what was found: the counts stay complete, the report says how many findings were held back and what the bar was, and the gate is measured against every finding. Turning the volume down cannot turn a gate off.

terraken  5 findings  terraform 1.16.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CRITICAL ──────────────────────────────────────────────────────────────────  1

  azurerm_postgresql_flexible_server.main
  destroy and create
  ├ holds data, so destroying it loses that data
  ├ an attribute changed that cannot be updated in place
  ├ forces replacement   zone
  ├ these values are not known until apply, so no claim about them can be
  │ checked in review
  │   fqdn
  │   id
  └ these values are sensitive and are redacted in all output
      administrator_password

HIGH ──────────────────────────────────────────────────────────────────────  1

  azurerm_subnet.app
  destroy
  ├ its configuration block was removed
  └ possible missed moved block
      6 of 6 attributes match azurerm_subnet.application
      moved { from = azurerm_subnet.app  to = azurerm_subnet.application }
      verify the pairing before using that block

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1 critical  1 high  1 low  2 info                       3 below high not shown

Levels

Four, and deliberately no medium: a middle bucket is where findings go to be ignored.

A resource type Terraken has not been curated against is never assumed safe. A destroy of an unrecognised type keeps its base level and is annotated to say that whether destroying it loses data has not been assessed.

Output formats

terminal

The default. One section per severity present, most severe first, and none at all for a severity with nothing in it. The report is set to the width of the stream it is going to, clamped between 60 and 100 columns, so a report redirected to a file is not set to the width of whatever terminal launched it. --plain drops colour and every box-drawing character, for a pipeline or a console that renders them badly.

md

A table for a pull request comment or a job summary, with the evidence behind each annotation in a collapsed section underneath, including the suggested moved block where there is one.

| Level | Change | Resource | Notes |
|---|---|---|---|
| CRITICAL | destroy and create | `azurerm_postgresql_flexible_server.main` | holds data, so destroying it loses that data; an attribute changed that cannot be updated in place; forces replacement: `zone` |

1 finding.

json

Indented JSON for machines. The shape is below.

html

One self-contained document: inline CSS, no external stylesheet, no font, no image and no script. It opens from a file:// URL with nothing else on disk and follows prefers-color-scheme, so it reads the same way in a dark editor as in a light browser. Anything taken from the plan is escaped before it is written, because a resource address can carry a key somebody else chose.

--out writes any format to a path and prints one line naming it, so nothing else lands on standard output. The file is created mode 0600: the report names every resource in the plan, which on a shared runner is a map of the estate. Colour is never written to a file.

The JSON shape

{
  "terraform_version": "1.9.8",
  "format_version": "1.2",
  "findings": [
    {
      "address": "azurerm_postgresql_flexible_server.main",
      "type": "azurerm_postgresql_flexible_server",
      "provider": "registry.terraform.io/hashicorp/azurerm",
      "kind": "replace",
      "level": "critical",
      "reason": "an attribute changed that cannot be updated in place",
      "replace_paths": [
        "zone"
      ],
      "data_loss": true
    }
  ],
  "counts": {
    "critical": 1
  }
}

Four things about it that are easy to get wrong:

• findings is always an array, never null, even on a clean plan. A nil slice would marshal as null and break iteration on the one plan whose answer is good news.
• counts always describes the whole plan, even under --min-level. It is not recounted around the filter.
• hidden and hidden_below are omitted entirely on an unfiltered run, so read .hidden // 0 rather than assuming the key exists.
• reason, replace_paths, module, provider and annotations are omitted when empty rather than emitted as nulls.

A possible-missed-moved-block annotation carries a moved object beside its sentence, holding the two addresses, the matched and compared attribute counts and whether the pairing crossed a module boundary. It is there so a consumer that cannot print a paragraph is not left with a bare code.

Annotation codes

An annotation is extra context attached to a finding. Annotations are reported separately from the level rather than folded into it, so their reasoning is always visible.

None of the rewrite classes moves a finding's level, and none of them says a change is harmless. Each one has a case where the difference is real: order is significant for a container command, whitespace is significant in a script and in anything hashed, a number and its string form are different types, and null and empty are not the same thing to Terraform everywhere. Terraken names the kind of difference and leaves the ruling to you.

terraken  5 findings  terraform 1.9.8
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

LOW ───────────────────────────────────────────────────────────────────────  5

  aws_ecs_task_definition.api
  update in place
  ├ same text, different whitespace
  │   container_definitions
  └ every attribute this plan shows as changed here is a difference in how the
    value is written

  aws_iam_policy.pipeline
  update in place
  ├ same JSON, written differently
  │   policy
  └ every attribute this plan shows as changed here is a difference in how the
    value is written

  aws_instance.bastion
  update in place
  ├ same text, different whitespace
  │   user_data
  └ same JSON, written differently
      metadata

  aws_lb_target_group.app
  update in place
  ├ null on one side, empty on the other
  │   load_balancing_anomaly_mitigation
  │   tags
  └ every attribute this plan shows as changed here is a difference in how the
    value is written

  aws_security_group.web
  update in place
  ├ same elements, different order
  │   ingress[0].cidr_blocks
  ├ same number, written differently
  │   ingress[0].from_port
  │   ingress[0].to_port
  └ every attribute this plan shows as changed here is a difference in how the
    value is written

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Whitespace is significant in a script, in a YAML document carried as a string
and in anything hashed, so whether a whitespace change matters is yours to
judge.

Each of these classes has a case where the difference is real. Order matters
in a container command, and whitespace matters in a script. This says what
kind of difference each one is and rules on none of them.

A consumer that compares the document byte for byte still sees a change, so
whether a rewritten document matters is yours to judge.

Null and empty are not the same thing to Terraform everywhere, where null can
mean inherit a default and empty means explicitly none, so whether this one
matters is yours to judge.

Order is significant for some attributes, such as a container command or an
ordered rule list, so whether a reordering matters is yours to judge.

A number and its string form are different types, and a type change can
matter, so whether this one does is yours to judge.

5 low

Exit codes

The separation matters in a pipeline. 1 means the tool worked and the plan failed your gate; 2 means the tool did not work, and treating the two as one number is how a broken step gets read as a passing one.

Colour

Colour is emitted only when the output is going to a terminal, so a pipe and a file both come out plain. Beyond that:

• NO_COLOR↗ (external site) set to anything non-empty switches colour off, whatever its value. An empty value means nothing and does not opt in.
• FORCE_COLOR turns it back on when the destination is a pipe, which a CI log that renders ANSI and a pager held open with less -R both need.
• NO_COLOR wins if both are set, because turning colour off should never be the setting that loses.
• --no-colour and its American alias --no-color both work. --plain goes further and drops the box drawing too.

In CI

--fail-on is off by default, because a tool that blocks by default gets switched off on day one rather than adopted. Adopt it read-only first, see what it says about the plans you are already approving, and turn the gate on afterwards.

There is a GitHub Action in the repository that does both in one step, and one step is the point: the same run produces the summary and the exit code, so the two cannot disagree and a large plan is not assessed twice.

- uses: dbhq-uk/terraken@v0.3.0
  with:
    plan: plan.json
    fail-on: critical

Pin the action to a tag. It never installs from @latest, and a released action must not change what it runs because somebody pushed to a branch.