Terraboard

<img alt="Terraboard logo" height="200" src="https://github.com/camptocamp/terraboard/raw/v2.4.0/logo/terraboard_logo.png">

🌍 📋 A web dashboard to inspect Terraform States

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?
• Overview
• Search
• State
• Compare
• Requirements
  • AWS S3 (state) + DynamoDB (lock)
  • Terraform Cloud
• Configuration
• Multiple buckets/providers
• 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
• Use with Docker
• Docker-compose
• Docker command line
• Use with Kubernetes
• Use with Rancher
• Authentication and base URL
• Install from source
• Compatibility Matrix
• Development
• Architecture
  • A server process
  • A web UI
• Testing
• Contributing

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

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.

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 (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:

• Set the CONFIG_FILE environment variable or the -c/--config-file flag to point to a valid YAML config file.
• In the YAML file, specify your desired providers configuration. For example with two MinIO buckets (using the AWS provider with compatible mode):

# 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

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

General Provider Options

• --no-versioning Disable versioning support from Terraboard (useful for S3 compatible providers like MinIO)
• Env: TERRABOARD_NO_VERSIONING
• Yaml: provider.no-versioning
• --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 Set log level ('debug', 'info', 'warn', 'error', 'fatal', 'panic').
• Env: TERRABOARD_LOG_LEVEL
• Yaml: log.level
• --log-format Set log format ('plain', 'json').
• Env: TERRABOARD_LOG_FORMAT
• Yaml: log.format

Database Options

• --db-host Database host.
• Env: DB_HOST
• Yaml: database.host
• --db-port Database port.
• Env: DB_PORT
• Yaml: database.port
• --db-user Database user.
• Env: DB_USER
• Yaml: database.user
• --db-password Database password.
• Env: DB_PASSWORD
• Yaml: database.password
• --db-name Database name.
• Env: DB_NAME
• Yaml: database.name
• --db-sslmode Database SSL mode.
• Env: DB_SSLMODE
• Yaml: database.sslmode
• --no-sync Do not sync database.
• Yaml: database.no-sync
• --sync-interval DB sync interval (in minutes)
• Yaml: database.sync-interval

AWS (and S3 compatible providers) Options

• --aws-access-key AWS account access key.
• Env: AWS_ACCESS_KEY_ID
• Yaml: aws.access-key
• --aws-secret-access-key AWS secret account access key.
• Env: AWS_SECRET_ACCESS_KEY
• Yaml: aws.secret-access-key
• --aws-session-token AWS session token.
• Env: AWS_SESSION_TOKEN
• Yaml: aws.session-token
• --dynamodb-table AWS DynamoDB table for locks.
• Env: AWS_DYNAMODB_TABLE
• Yaml: aws.dynamodb-table
• --aws-endpoint AWS endpoint.
• Env: AWS_ENDPOINT
• Yaml: aws.endpoint
• --aws-region AWS region.
• Env: AWS_REGION
• Yaml: aws.region
• --aws-role-arn Role ARN to Assume.
• Env: APP_ROLE_ARN
• Yaml: aws.app-role-arn
• --aws-external-id External ID to use when assuming role.
• Env: AWS_EXTERNAL_ID
• Yaml: aws.external-id

S3 Options

• --s3-bucket AWS S3 bucket.
• Env: AWS_BUCKET
• Yaml: aws.s3.bucket
• --key-prefix AWS Key Prefix.
• Env: AWS_KEY_PREFIX
• Yaml: aws.s3.key-prefix
• --file-extension File extension(s) of state files.
• Env: AWS_FILE_EXTENSION
• Yaml: aws.s3.file-extension
• --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 Terraform Enterprise address for states access
• Env: TFE_ADDRESS
• Yaml: tfe.address
• --tfe-token Terraform Enterprise Token for states access
• Env: TFE_TOKEN
• Yaml: tfe.token
• --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 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 GitLab address (root)
• Env: GITLAB_ADDRESS
• Yaml: gitlab.address
• --gitlab-token Token to authenticate upon GitLab
• Env: GITLAB_TOKEN
• Yaml: gitlab.token

Web

• -p, --port Port to listen on.
• Env: TERRABOARD_PORT
• Yaml: web.port
• --base-url Base URL.
• Env: TERRABOARD_BASE_URL
• Yaml: web.base-url
• --logout-url Logout URL.
• Env: TERRABOARD_LOGOUT_URL
• Yaml: web.logout-url

Help Options

• -h, --help Show this help message

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.

```shell

Set AWS credentials as environment variables:

export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY=

Set AWS configuration as environment variables:

export AWS_DEFAULT_REGION= export AWS_BUCKET= export AWS_DYNAMODB_TABLE=<Aws DynamoDB Table