Skip to content
dev-shimadaPublic

About

Transparent terraform CLI wrapper that runs plan without acquiring the state lock, avoiding lock contention in parallel CI runs

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

parraform

CI Coverage Go Version MIT License

Release Homebrew

A transparent wrapper around the terraform CLI.

plan can run without acquiring the state lock, so parallel plan runs in CI don't fail by fighting over it.

Every other command, including apply, behaves exactly like normal terraform and keeps the usual locking.

(日本語版はこちら)

Install

Homebrew

brew tap dev-shimada/parraform
brew install parraform

Go

go install github.com/dev-shimada/parraform/cmd/parraform@latest

GitHub Actions

- uses: dev-shimada/parraform@main

Caution

If you pair this action with hashicorp/setup-terraform, always set its terraform_wrapper input to false.

Input Default Description
version latest parraform release to install (e.g. v0.1.1)
terraform_wrapper false Capture the output of parraform (see below)
github-token github.token Token used to download the release
verify-attestation true Verify the archive's build provenance before installing (see below)
sha256 none Expected SHA-256 of the archive (see below). Requires a pinned version

Verifying the download

The action checks the archive in this order, and stops at the first failure.

  1. sha256 (if set): the archive must match the hash you wrote in your own repository.
  2. verify-attestation (default): gh attestation verify must confirm the archive was built by this repository's release.yml from the release's own tag.
  3. The checksums.txt published with the release. This only catches a corrupted download, because it is stored in the same release as the archive.
- uses: dev-shimada/parraform@main
  with:
    version: v0.2.0
    sha256: |
      <hash>  parraform_Linux_x86_64.tar.gz
      <hash>  parraform_Darwin_arm64.tar.gz
  • Copy the sha256 lines from the release's parraform_<version>_checksums.txt. List one line per runner architecture you use.
  • Releases published before attestations existed (v0.1.3 and earlier) cannot be verified. To install one, set verify-attestation: false.

Capturing output (terraform_wrapper: true)

Equivalent to the option of the same name in hashicorp/setup-terraform, it sets these outputs on the step that runs parraform.

Output Description
stdout Standard output of parraform
stderr Standard error of parraform
exitcode Exit code of parraform
  • The step succeeds when the exit code is 0 or 2.
    • 2 means -detailed-exitcode found changes.
- uses: hashicorp/setup-terraform@v4
  with:
    terraform_wrapper: false

- uses: dev-shimada/parraform@main
  with:
    terraform_wrapper: true

- run: parraform init

- id: plan
  run: parraform plan -detailed-exitcode -out=tfplan

- if: steps.plan.outputs.exitcode == '2'
  run: parraform apply tfplan

Usage

Use parraform in place of terraform, and all subcommands and flags are passed through unchanged.

parraform init
parraform plan -out=tfplan
parraform apply tfplan

Put it on PATH under the name terraform to use it in existing pipelines without changes.

Options

Options for plan.

Option Description
-lock=false (default) Does not acquire the state lock
-lock=true Acquires the state lock
-lock-check=warn (default) If the lock is held, prints a warning and runs plan
-lock-check=strict If the lock is held, exits with code 1 without running plan
-lock-check=require Like strict, and also exits with code 1 if it cannot confirm the lock is free
  • -lock is terraform's own option, and parraform only changes its default for plan to false.
  • If the lock state cannot be determined (unsupported backend, timeout, etc.), warn and strict run plan.
  • require is the fail-closed mode: plan runs only when the lock was confirmed free. It exits with code 1 and prints the reason when:
    • .terraform/terraform.tfstate (or terraform.tfstate under TF_DATA_DIR) is missing or names no backend (not initialized, or an implicit local backend)
    • the backend is unsupported, or has no lock configured (e.g. s3 with neither dynamodb_table nor use_lockfile)
    • the check times out or fails (e.g. missing dynamodb:GetItem permission)
    • PARRAFORM_LOCK_CHECK_TIMEOUT is 0 or less
  • -lock-check can also be set with TF_CLI_ARGS_plan (e.g. TF_CLI_ARGS_plan=-lock-check=strict).
    • The command line takes precedence.
  • Commands other than plan (apply, import, state mv, ...) are passed through unchanged.

Environment variables

Variable Default Description
PARRAFORM_TERRAFORM_BIN none Path of the terraform binary to run
PARRAFORM_LOCK_CHECK_TIMEOUT 3s Timeout of the lock check (Go duration)
  • If PARRAFORM_TERRAFORM_BIN is not set, terraform is looked up on PATH.
  • Setting PARRAFORM_LOCK_CHECK_TIMEOUT to 0 or less disables the lock check (with -lock-check=require, plan is refused instead).

Shell completion

parraform completion bash > /etc/bash_completion.d/parraform

bash, zsh, fish, and powershell are supported.

About

Transparent terraform CLI wrapper that runs plan without acquiring the state lock, avoiding lock contention in parallel CI runs

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages