camptocamp/terraboard repository overview

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