Terraform Cloud Scanner

The Terraform Cloud Scanner is a standalone tool that can be run in your own infrastructure. It imports all Terraform workspaces as ctrlplane resources and populates them with configuration and metadata that can be used with the github actions dispatcher for continuous delivery.

This scanner runs as a Docker container and requires credentials to be provided to the access your Terraform Cloud Org.

Docker Image

The Docker image for the Terraform Cloud Scanner can be pulled from Docker Hub

docker pull ctrlplane/terraform-cloud-scanner:latest
docker run --env-file .env ctrlplane/terraform-cloud-scanner:latest

Make sure to create a .env file with the necessary environment variables before running the container.

Environment Variables

To configure the scanner, the following environment variables can be set.

The workspace id can be found by navigating to

https://${CTRLPLANE_BASE_URL}/${WORKSPACE_SLUG}/settings/workspace/general

See the API docs to set up an api key for the Terraform Cloud Scanner.

Properties

The following properties will be populated for each resource scanned into Ctrlplane:

• Identifier: example-workspace-id
• Name: example-workspace-name
• Version: terraform/v1
• Kind: Workspace
• Resource Provider: terraform-cloud-scanner
• Last Sync: MM/DD/YYYY HH:MM:SS
• External ID: example-external-id

Config

The config for a Terraform Cloud workspace resource adheres to the following schema:

version: terraform/v1
kind: Workspace
config:
  workspaceId: example-workspace-id
metadata:
  organization: example-org
  name: example-workspace-name
  autoApply: false
  vcsRepo:
    identifier: example-repo
    branch: example-branch
    repositoryHttpUrl: https://github.com/example/repo

This config structure provides essential information about the Terraform Cloud workspace, allowing Ctrlplane to interact with it consistently.

Metadata

The following metadata will be automatically scanned into Ctrlplane:

ctrlplane/external-id: example-external-id
ctrlplane/links:
  {
    "Terraform Workspace": "https://app.terraform.io/app/example-org/workspaces/example-workspace-name",
  }
terraform-cloud/organization: example-org
terraform-cloud/vcs-repo/branch: example-branch
terraform-cloud/vcs-repo/identifier: example-repo
terraform-cloud/vcs-repo/repository-http-url: https://github.com/example/repo
terraform-cloud/workspace-auto-apply: false
terraform-cloud/workspace-name: example-workspace-name
terraform/version: 1.9.4

This metadata provides additional context and information about the Terraform Cloud workspace, facilitating organization and filtering within Ctrlplane. All metadata will be available to any job you have configured that uses the github actions dispatcher

Variables

The Terraform Cloud Scanner captures both Terraform variables and environment variables from your workspace. These variables are added to the metadata with the prefix terraform-cloud/variables/.

• Terraform Variables: These are used directly in your Terraform configuration.
• Environment Variables: These are used by Terraform providers or external scripts.

Both types of variables are represented in the metadata as:

terraform-cloud/variables/${variable_name}: ${value}

Examples:

terraform-cloud/variables/deletion_protection: true
terraform-cloud/variables/instance_type: t2.micro

Tags

Any tags you have set on the Terraform Cloud workspace will be added to the metadata. The tag format in the metadata depends on whether the original tag contains a colon :.

• If the tag contains a colon, it will be split into a key-value pair.
• If the tag doesn’t contain a colon, it will be set to true.

Examples:

Here’s how these tags would appear in the metadata:

terraform-cloud/tag/env: development
terraform-cloud/tag/gcp: true
terraform-cloud/tag/region: us-central1

This approach allows for both simple flags and key-value pairs in your Terraform Cloud tags, which are then reflected in the Ctrl Plane metadata for easy filtering and organization when building a View, Group, or Environment Filter.