terraboard

Terraboard

Terraboard logo

šŸŒ šŸ“‹ A web dashboard to inspect Terraform States

Docker Pulls Go Report Card Gitter Build Status Coverage Status By Camptocamp Documentation

Website: https://terraboard.io

Caution: Terraboard's Docker registry was migrated from Dockerhub to GHCR! All new tags will be now pushed here. You can still access to old tags on the legacy Dockerhub repository.

Table of content - [What is it?](#what-is-it) - [Overview](#overview) - [Search](#search) - [State](#state) - [Compare](#compare) - [Requirements](#requirements) - [AWS S3 (state) + DynamoDB (lock)](#aws-s3-state--dynamodb-lock) - [Terraform Cloud](#terraform-cloud) - [Configuration](#configuration) - [Multiple buckets/providers](#multiple-bucketsproviders) - [Available parameters](#available-parameters) - [Application Options](#application-options) - [General Provider Options](#general-provider-options) - [Logging Options](#logging-options) - [Database Options](#database-options) - [AWS (and S3 compatible providers) Options](#aws-and-s3-compatible-providers-options) - [S3 Options](#s3-options) - [Terraform Enterprise Options](#terraform-enterprise-options) - [Google Cloud Platform Options](#google-cloud-platform-options) - [GitLab Options](#gitlab-options) - [Web](#web) - [Help Options](#help-options) - [Push plans to Terraboard](#push-plans-to-terraboard) - [Use with Docker](#use-with-docker) - [Docker-compose](#docker-compose) - [Docker command line](#docker-command-line) - [Use with Kubernetes](#use-with-kubernetes) - [Use with Rancher](#use-with-rancher) - [Authentication and base URL](#authentication-and-base-url) - [Install from source](#install-from-source) - [Compatibility Matrix](#compatibility-matrix) - [Development](#development) - [Architecture](#architecture) - [A server process](#a-server-process) - [A web UI](#a-web-ui) - [Testing](#testing) - [Contributing](#contributing)

What is it?

Terraboard is a web dashboard to visualize and query Terraform states. It currently features:

It currently supports several remote state backend providers:

Terraboard is now able to handle multiple buckets/providers configuration! šŸ„³ Check configuration section for more details.

Overview

The overview presents all the state files in the S3 bucket, by most recent modification date.

Screenshot Overview

The search view allows to find resources by various criteria.

Screenshot Search

State

The state view presents details of a Terraform state at a given version.

Screenshot State

Compare

From the state view, you can compare the current state version with another version.

Screenshot Compare

Requirements

Independently of the location of your statefiles, Terraboard needs to store an internal version of its dataset. For this purpose it requires a PostgreSQL database. Data resiliency is not paramount though as this dataset can be rebuilt upon your statefiles at anytime.

AWS S3 (state) + DynamoDB (lock)

Configuration

Terraboard currently supports configuration in three different ways:

  1. Environment variables (only usable for single provider configuration)
  2. CLI parameters (only usable for single provider configuration)
  3. Configuration file (YAML). A configuration file example can be found in the root directory of this repository and in the test/ subdirectory.

Important: all flags/environment variables related to the providers settings arenā€™t compatible with multi-provider configuration! Instead, you must use the YAML config file to be able to configure multiples buckets/providers. YAML config is able to load values from environments variables.

The precedence of configurations is as described below.

Multiple buckets/providers

In order for Terraboard to import states from multiples buckets or even providers, you must use the YAML configuration method:

# Needed since MinIO doesn't support versioning or locking
provider:
  no-locks: true
  no-versioning: true

aws:
  - endpoint: http://minio:9000/
    region: ${AWS_DEFAULT_REGION}
    s3:
      - bucket: test-bucket
        force-path-style: true
        file-extension:
          - .tfstate

  - endpoint: http://minio:9000/
    region: eu-west-1
    s3:
      - bucket: test-bucket2
        force-path-style: true
        file-extension:
          - .tfstate

In the case of AWS, donā€™t forget to set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Thatā€™s it! Terraboard will now fetch these two buckets on DB refresh. You can also mix providers like AWS and Gitlab or anything else. You can find a ready-to-use Docker example with two MinIO buckets in the test/multiple-minio-buckets/ sub-folder.

Available parameters

Application Options

General Provider Options

Logging Options

Database Options

AWS (and S3 compatible providers) Options

S3 Options

Terraform Enterprise Options

Google Cloud Platform Options

GitLab Options

Web

Help Options

Push plans to Terraboard

In order to send Terraform plans to Terraboard, you must wrap it in this JSON format:

{
    "lineage": "<Plan's lineage>",
    "terraform_version": "<Terraform version>",
    "git_remote": "<The URL of the remote that generated this plan>",
    "git_commit": "<Commit hash>",
    "ci_url": "<The URL of the CI that sent this plan>",
    "source": "<Free field for the triggering event>",
    "plan_json": "<Terraform plan JSON export>"
}

And send it to /api/plans using POST method

Use with Docker

Docker-compose

Configuration file can be provided to the container using a volume or a configuration.

# Set AWS credentials as environment variables:
export AWS_ACCESS_KEY_ID=<access_key>
export AWS_SECRET_ACCESS_KEY=<access_secret>

# Set AWS configuration as environment variables:
export AWS_DEFAULT_REGION=<AWS default region>
export AWS_BUCKET=<S3 Bucket name>
export AWS_DYNAMODB_TABLE=<Aws DynamoDB Table>

docker-compose up

Then point your browser to http://localhost:8080.

Docker command line

# Set AWS credentials as environment variables:
export AWS_ACCESS_KEY_ID=<access_key>
export AWS_SECRET_ACCESS_KEY=<access_secret>

# Set AWS configuration as environment variables:
export AWS_DEFAULT_REGION=<AWS default region>
export AWS_BUCKET=<S3 Bucket name>
export AWS_DYNAMODB_TABLE=<AWS_DYNAMODB_TABLE>

# Spin up the two containers and a network for them to communciate on:
docker network create terraboard
docker run --name db \
  -e POSTGRES_USER=gorm \
  -e POSTGRES_DB=gorm \
  -e POSTGRES_PASSWORD="<mypassword>" \
  -e GODEBUG="netdns=go" \
  --net terraboard \
  --detach \
  --restart=always \
  postgres:9.5

docker run -p 8080:8080 \
  -e AWS_ACCESS_KEY_ID="${AWS_ACCESS_KEY_ID}" \
  -e AWS_SECRET_ACCESS_KEY="${AWS_SECRET_ACCESS_KEY}" \
  -e AWS_REGION="${AWS_DEFAULT_REGION}" \
  -e AWS_BUCKET="${AWS_BUCKET}" \
  -e AWS_DYNAMODB_TABLE="${AWS_DYNAMODB_TABLE}" \
  -e DB_PASSWORD="<mypassword>" \
  -e DB_SSLMODE="disable" \
  --net terraboard \
  ghcr.io/nkbud/terraboard:latest

Then point your browser to http://localhost:8080.

Use with Kubernetes

A Helm chart is available as an OCI artifact in GitHub Container Registry.

In order to install it:

# Pull and install from OCI registry
$ helm registry login ghcr.io
$ helm install terraboard oci://ghcr.io/nkbud/terraboard --version 2.4.0

Alternatively, you can pull the chart first and then install:

$ helm registry login ghcr.io
$ helm pull oci://ghcr.io/nkbud/terraboard --version 2.4.0
$ helm install terraboard terraboard-2.4.0.tgz

You can also use a values file for configuration:

$ helm install terraboard oci://ghcr.io/nkbud/terraboard --version 2.4.0 -f values.yaml

Use with Rancher

Camptocampā€™s Rancher Catalog contains a Terraboard template to automate its installation in Cattle.

Authentication and base URL

Terraboard does not implement authentication. Instead, it is recommended to use an authentication proxy such as oauth2_proxy.

If you need to set a route path for Terraboard, you can set a base URL by passing it as the BASE_URL environment variable.

When using an authentication proxy, Terraboard will retrieve the logged in user and email from the headers passed by the proxy. Terraboard expects you to setup the HTTP Headers X-Forwarded-User and X-Forwarded-Email when passing the logged in user and email. A Nginx example can be found below:

location / {
  ....
  auth_request_set $user   $upstream_http_x_auth_request_user;
  auth_request_set $email  $upstream_http_x_auth_request_email;
  proxy_set_header X-Forwarded-User  $user;
  proxy_set_header X-Forwarded-Email $email;
  ...
  proxy_pass http://terraboard/;
}

You can also pass a TERRABOARD_LOGOUT_URL parameter to allow users to sign out of the proxy.

Install from source

$ go get github.com/camptocamp/terraboard

Compatibility Matrix

Terraboard Max Terraform version
0.15.0 0.12.7
0.16.0 0.12.7
0.17.0 0.12.18
0.18.0 0.12.18
0.19.0 0.12.20
0.20.0 0.12.26
0.21.0 0.12.28
0.22.0 0.13.0
1.0.0 0.14.5
1.1.0 0.14.10

Development

Architecture

Terraboard is made of two components:

A server process

The server is written in go and runs a web server which serves:

The server also has a routine which regularly (every 1 minute) feeds the PostgreSQL database from the S3 bucket.

A web UI

The UI is an AngularJS application served from index.html. All the UI code can be found in the static/ directory.

Testing

$ docker-compose build && docker-compose up -d
# Point your browser to http://localhost

Environment Setup:

# AWS Choices
export AWS_PROFILE="YOUR PROFILE"
export AWS_ROLE_ARN="YOUR ROLE ARN"
export AWS_REGION="YOUR REGION"     
export AWS_BUCKET="YOUR S3 BUCKET"

# App Choices
export TERRABOARD_NO_VERSIONING="true"
export TERRABOARD_NO_LOCKS="true"

# Get temporary credentials
response=$(aws --profile=${AWS_PROFILE} sts assume-role \                                               
  --role-arn ${AWS_ROLE_ARN} \
  --role-session-name mysession \      
  --output json)        
  
export AWS_ACCESS_KEY_ID=$(echo "$response" | jq -r '.Credentials.AccessKeyId')
export AWS_SECRET_ACCESS_KEY=$(echo "$response" | jq -r '.Credentials.SecretAccessKey')
export AWS_SESSION_TOKEN=$(echo "$response" | jq -r '.Credentials.SessionToken')

Run it:

docker compose up

Contributing

See CONTRIBUTING.md

This site is open source. Improve this page.