Guardrails / terraform

Terraform state is kept in a remote backend

terraform/remote-state@v1

Every live Terraform root stores its state in a remote backend, and no state file is left in the checkout.

Id	terraform/remote-state
Version	v1
Category	terraform
Default severity	error
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	terraform

Collectors

This guardrail doesn't gather anything itself. It relies on the collectors below, which the CLI runs once per build before any check, and reads what they found from GUARDRAIL_FACTS. If a collector collects nothing, this guardrail is skipped, not failed.

Collector	Gathers	Inputs it is given
terraform	The Terraform configuration in the checkout: every root directory holding .tf files, the backend it stores state in, the providers and modules it takes on and how tightly they are pinned, the resources it declares, the variables it takes, the lock file that resolves it, and any state file left in the tree. Everything is read from the files themselves, so it works on a runner with no Terraform installed. When the terraform CLI is there, the versions an initialised root has already resolved are added.	none

The inputs above are this guardrail's own inputs, passed straight through to the collector. Setting one in buildnote.json changes what is collected, and two guardrails configured the same way share a single collection.

Configuration

{
  "guardrails": {
      "failOn": "error",
      "checks": [
          {
              "use": "terraform/remote-state@v1",
              "severity": "error",
              "with": {
                  "checkStateFiles": "true",
                  "modulePaths": "modules/*,*/modules/*"
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
checkStateFiles	Whether a .tfstate or .tfstate.backup file in the working tree is a violation. The collector reads the working tree, not the git index, so a developer who has run terraform apply locally has one even though nobody committed it. In CI the checkout matches the repository, so the two are the same.	true	GUARDRAIL_INPUT_CHECKSTATEFILES
modulePaths	Comma separated globs naming directories that hold reusable modules rather than live roots. A module declares no backend and pins nothing, so it is not judged here. A directory another root takes on with a local source is recognised as a module whether or not it matches.	modules/*,*/modules/*	GUARDRAIL_INPUT_MODULEPATHS

How to fix

Store state in a shared backend with locking and encryption:

terraform {
  backend "s3" {
    bucket       = "company-terraform-state"
    key          = "live/network.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

Then keep state files out of the repository:

printf '*.tfstate\n*.tfstate.backup\n' >> .gitignore
git rm --cached terraform.tfstate

Local state is one lost laptop away from being gone, and two concurrent applies overwrite each other with nothing to stop them. A state file in the repository is worse than lost state: it contains every attribute of every resource, including the ones marked sensitive, and anyone who can read the repository can read it.

More in terraform

• terraform/modules-pinned. Every module a Terraform root pulls from a registry or a git URL names a version, so the same commit always resolves to the same module code.
• terraform/no-plaintext-secrets. Every Terraform variable named like a credential declares sensitive = true.
• terraform/providers-pinned. Every provider a live Terraform root requires is pinned to one exact version, and the lock file that resolves them is committed.
• terraform/state-encrypted. Every live Terraform root declares an encrypted backend, so its state isn't stored in the clear in its bucket.
• terraform/state-locking. Every live Terraform root declares state locking, so two applies cannot write the same state at once.

All 6 terraform guardrails