Skip to content

Latest commit

 

History

History
139 lines (95 loc) · 5.09 KB

README.md

File metadata and controls

139 lines (95 loc) · 5.09 KB
Raw

Terraform Backend Server

A state backend server which implements the Terraform HTTP backend API with plugable modules for authentication, storage, locking and state encryption.

⚠️ Disclaimer: This code is in an early development state and not tested extensively for bugs and security issues. If you find some, please raise an issue or merge request.

Supported authentication methods:

  • HTTP basic auth
  • JSON Web Tokens

Supported storage backends:

  • local file system
  • S3
  • Postgres

Supported lock backends:

  • local map
  • Redis
  • Postgres

Supported KMS (encryption) backends:

  • local AES key
  • AES from HashiCorp Vault Key/Value store (v2)
  • HashiCorp Vault Transit engine

Deployment

Run locally for development:

LOG_LEVEL=debug go run ./cmd/terraform-backend

or use docker-compose:

docker-compose up -d

Default settings

The following table describes the default configuration, although the backend server will run with these values, it's not scalable and therefore only for testing purposes.

Environment Variable Type Default Description
LOG_LEVEL string info Log level (options are: fatal, info, warning, debug, trace)
LISTEN_ADDR string :8080 Address the HTTP server listens on
TLS_KEY string -- Path to TLS key file for listening with TLS (fallback to HTTP if not specified)
TLS_CERT string -- Path to TLS certificate file for listening with TLS (fallback to HTTP if not specified)
STORAGE_BACKEND string fs Module for state file storage (checkout docs/storage.md for other options)
STORAGE_FS_DIR string ./states File system directory for fs storage module to store state files
KMS_BACKEND string local Module used for encryption (checkout docs/kms.md for other options)
KMS_KEY string -- Key for local KMS module, if not defined, the server will generate a new one and exit
LOCK_BACKEND string local Module used for locking the state (checkout docs/lock.md for other options)
AUTH_BASIC_ENABLED bool true HTTP basic auth is enabled by default (checkout docs/auth.md for other options)
FORCE_UNLOCK_ENABLED bool true Force-unlock feature enables the native Terraform behavior which unlocks the state even if no lock id was sent

Usage

The path to the state is: /state/<project-id>/<state-name>.

Example Terraform backend configuration

terraform {
  backend "http" {
    address        = "http://localhost:8080/state/project1/example"
    lock_address   = "http://localhost:8080/state/project1/example"
    unlock_address = "http://localhost:8080/state/project1/example"
    username       = "basic"
    password       = "some-random-secret"
  }
}

For more information about username and password checkout docs/auth.md

Tests

Run unit tests:

go test ./...

Run integration tests:

docker-compose up -d redis postgres minio
go test ./... --tags integration -count=1

Speculative Runs in GitHub Actions

This project includes a CLI to trigger speculative runs via GitHub Actions, similar to how Terraform Cloud works.

Install

To install the binary on your system, download the binary from the latest release and make it executable:

curl -L "https://github.com/ffddorf/terraform-backend/releases/latest/download/tf-preview-gh_$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)" > tf-preview-gh
sudo mv tf-preview-gh /usr/local/bin/tf-preview-gh
sudo chmod +x /usr/local/bin/tf-preview-gh

Configure

In order to use it with your respository, you need to have some workflows in place.

The tf-preview-gh scaffold command sets up everything that's necessary. This includes the workflows to run plans for pull requests and applies for merges to main.

It should look like this:

% tf-preview-gh scaffold
Wrote backend config to: backend.tf
Wrote workflow to: .github/workflows/tf-preview.yaml
Wrote workflow to: .github/workflows/tf-run.yaml

Next, commit the new files and get them on main before continuing.

Usage

Run the CLI in the directory for which you want to run a remote plan.

The tool will pick its context from the environment:

  • Address of the Terraform Backend from your backend config
  • Repository to use from the git remote called origin
tf-preview-gh