Terraboard

🌍 📋 A web dashboard to inspect Terraform States

⁠⁠⁠⁠⁠⁠

Website: https://terraboard.io⁠

What is it?

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

• an overview page listing the most recently updated state files with their activity
• a state page with state file details, including versions and resource attributes
• a search interface to query resources by type, name or attributes
• a diff interface to compare state between versions

It currently supports several remote state backend providers:

• AWS S3 (state) + DynamoDB (lock)⁠
• S3 compatible backends (ex: MinIO)⁠
• Google Cloud Storage⁠
• Terraform Cloud (remote)⁠
• GitLab⁠

Overview

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

Search

The search view allows to find resources by various criteria.

State

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

Compare

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

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)

• A versioned S3 bucket name with one or more Terraform states, named with a .tfstate suffix
• AWS credentials with the following IAM permissions over the bucket:
  • s3:GetObject
  • s3:ListBucket
  • s3:ListBucketVersions
  • s3:GetObjectVersion
• If you want to retrieve lock states from a dynamoDB table⁠, you need to make sure the provided AWS credentials have dynamodb:Scan access to that table.

Terraform Cloud

• Account on Terraform Cloud⁠
• Existing organization
• Token assigned to an organization

Configuration

Terraboard currently supports configuration in three different ways:

1. Environment variables
2. CLI parameters
3. Configuration file (YAML). A configuration file example can be found in the root directory of this repository.

The precedence of configurations is as described below.

Available parameters

Application Options

• -V, --version Display version.
• -c, --config-file <default: $CONFIG_FILE> Config File path
  • Env: CONFIG_FILE

General Provider Options

• --no-versioning <default: $TERRABOARD_NO_VERSIONING> Disable versioning support from Terraboard (useful for S3 compatible providers like MinIO)
  • Env: TERRABOARD_NO_VERSIONING
  • Yaml: provider.no-versioning
• --no-locks <default: $TERRABOARD_NO_LOCKS> Disable locks support from Terraboard (useful for S3 compatible providers like MinIO)
  • Env: TERRABOARD_NO_LOCKS
  • Yaml: provider.no-locks

Logging Options

• -l, --log-level <default: "info"> Set log level ('debug', 'info', 'warn', 'error', 'fatal', 'panic').
  • Env: TERRABOARD_LOG_LEVEL
  • Yaml: log.level
• --log-format <default: "plain"> Set log format ('plain', 'json').
  • Env: TERRABOARD_LOG_FORMAT
  • Yaml: log.format

Database Options

• --db-host <default: "db"> Database host.
  • Env: DB_HOST
  • Yaml: database.host
• --db-port <default: "5432"> Database port.
  • Env: DB_PORT
  • Yaml: database.port
• --db-user <default: "gorm"> Database user.
  • Env: DB_USER
  • Yaml: database.user
• --db-password <default: $DB_PASSWORD> Database password.
  • Env: DB_PASSWORD
  • Yaml: database.password
• --db-name <default: "gorm"> Database name.
  • Env: DB_NAME
  • Yaml: database.name
• --db-sslmode <default: "require"> Database SSL mode.
  • Env: DB_SSLMODE
  • Yaml: database.sslmode
• --no-sync Do not sync database.
  • Yaml: database.no-sync
• --sync-interval <default: "1"> DB sync interval (in minutes)
  • Yaml: database.sync-interval

AWS (and S3 compatible providers) Options

• --dynamodb-table <default: $AWS_DYNAMODB_TABLE> AWS DynamoDB table for locks.
  • Env: AWS_DYNAMODB_TABLE
  • Yaml: aws.dynamodb-table
• --aws-endpoint <default: $AWS_ENDPOINT> AWS endpoint.
  • Env: AWS_ENDPOINT
  • Yaml: aws.endpoint
• --aws-region <default: $AWS_REGION> AWS region.
  • Env: AWS_REGION
  • Yaml: aws.region
• --aws-role-arn <default: $APP_ROLE_ARN> Role ARN to Assume.
  • Env: APP_ROLE_ARN
  • Yaml: aws.app-role-arn
• --aws-external-id <default: $AWS_EXTERNAL_ID> External ID to use when assuming role.
  • Env: AWS_EXTERNAL_ID
  • Yaml: aws.external-id

S3 Options

• --s3-bucket <default: $AWS_BUCKET> AWS S3 bucket.
  • Env: AWS_BUCKET
  • Yaml: aws.s3.bucket
• --key-prefix <default: $AWS_KEY_PREFIX> AWS Key Prefix.
  • Env: AWS_KEY_PREFIX
  • Yaml: aws.s3.key-prefix
• --file-extension <default: ".tfstate"> File extension(s) of state files.
  • Env: AWS_FILE_EXTENSION
  • Yaml: aws.s3.file-extension
• --force-path-style <default: $AWS_FORCE_PATH_STYLE> Force path style S3 bucket calls.
  • Env: AWS_FORCE_PATH_STYLE
  • Yaml: aws.s3.force-path-style

Terraform Enterprise Options

• --tfe-address <default: $TFE_ADDRESS> Terraform Enterprise address for states access
  • Env: TFE_ADDRESS
  • Yaml: tfe.address
• --tfe-token <default: $TFE_TOKEN> Terraform Enterprise Token for states access
  • Env: TFE_TOKEN
  • Yaml: tfe.token
• --tfe-organization <default: $TFE_ORGANIZATION> Terraform Enterprise organization for states access
  • Env: TFE_ORGANIZATION
  • Yaml: tfe.organization

Google Cloud Platform Options

• --gcs-bucket Google Cloud bucket to search
  • Yaml: gcp.gcs-bucket
• --gcp-sa-key-path <default: $GCP_SA_KEY_PATH> The path to the service account to use to connect to Google Cloud Platform
  • Env: GCP_SA_KEY_PATH
  • Yaml: gcp.gcp-sa-key-path

GitLab Options

• --gitlab-address <default: *"https://gitlab.com"*>⁠ GitLab address (root)
  • Env: GITLAB_ADDRESS
  • Yaml: gitlab.address
• --gitlab-token <default: $GITLAB_TOKEN> Token to authenticate upon GitLab
  • Env: GITLAB_TOKEN
  • Yaml: gitlab.token

Web

• -p, --port <default: "8080"> Port to listen on.
  • Env: TERRABOARD_PORT
  • Yaml: web.port
• --base-url <default: "/"> Base URL.
  • Env: TERRABOARD_BASE_URL
  • Yaml: web.base-url
• --logout-url <default: $TERRABOARD_LOGOUT_URL> Logout URL.
  • Env: TERRABOARD_LOGOUT_URL
  • Yaml: web.logout-url

Help Options

• -h, --help Show this help message

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 WS_DYNAMODB_TABLE="${AWS_DYNAMODB_TABLE}" \
  -e DB_PASSWORD="<mypassword>" \
  -e DB_SSLMODE="disable" \
  --net terraboard \
  camptocamp/terraboard:latest

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

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. 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

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 API on known access points, taking the data from the PostgreSQL database
• the index page (from static/index.html) on all other URLs

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

Contributing

See CONTRIBUTING.md