Skip to main content

Terraform Workflow

The overmind terraform command is the recommended way to use Overmind with Terraform. It wraps your normal terraform plan and terraform apply commands to provide real-time blast radius analysis and risk assessment with minimal workflow changes.

Quick Start​

Replace your normal Terraform commands with Overmind's equivalents:

# Instead of: terraform plan
overmind terraform plan

# Instead of: terraform apply
overmind terraform apply

That's it. Overmind handles everything else automatically.

How It Works​

When you run overmind terraform plan:

  1. Runs Terraform: Executes terraform plan with your configuration
  2. Discovers Infrastructure: Queries your cloud accounts for real-time resource data
  3. Maps Dependencies: Builds a comprehensive view of how resources are interconnected
  4. Calculates Blast Radius: Identifies all resources that could be affected
  5. Assesses Risks: Analyzes potential issues and failure points
  6. Opens Results: Displays the blast radius graph in your browser

When you run overmind terraform apply:

  1. Takes a "Before" Snapshot: Captures the current state of your infrastructure
  2. Runs Terraform Apply: Executes the actual apply
  3. Takes an "After" Snapshot: Captures the new state
  4. Tracks Outcomes: Links to the change created by plan and provides a diff of everything that changed, including any unexpected repercussions

Commands​

overmind terraform plan​

Runs terraform plan and sends the results to Overmind for blast radius and risk analysis.

overmind terraform plan [overmind options...] -- [terraform options...]

What it does:

  • Executes terraform plan with any arguments you provide
  • Strips sensitive data from the plan output before uploading
  • Creates or updates a Change in Overmind
  • Calculates the blast radius using real-time infrastructure data
  • Displays risks in the terminal with severity levels (High/Medium/Low)
  • Opens the blast radius graph in your browser

Example output:

Running `terraform plan`...

Plan Complete! Submitting plan to Overmind...
✅ Mapping resources
✅ Stripping sensitive data
✅ Submitting changes to Overmind
✅ Discovering Blast Radius
✅ Blast radius graph ready, opening in browser
✅ Calculating risks

Plan complete: Expected Changes:
+ aws_instance.web_server
~ aws_security_group.main
- aws_route53_record.old

Blast Radius: Items: 128 Edges: 350

Potential Risks:
- Impact on Target Groups (High 🔥): Target groups may be affected if the security group change causes networking issues.
- Impact on Load Balancer Traffic (Medium !): The restriction of egress traffic could affect traffic distribution.

See this change in the graph: https://app.overmind.tech/changes/abc-123-def

overmind terraform apply​

Runs terraform apply with before/after snapshots for tracking.

overmind terraform apply [overmind options...] -- [terraform options...]

What it does:

  • If no plan file is provided, runs terraform plan first
  • Prompts for approval (unless --auto-approve is passed to Terraform)
  • Takes a snapshot before and after applying
  • Links to the Change created by the previous plan command
  • Provides a diff of all changes, including unexpected impacts

Example:

# Apply with approval prompt
overmind terraform apply

# Apply automatically (skips risk calculation)
overmind terraform apply -- --auto-approve

# Apply a specific plan file
overmind terraform apply -- saved-plan.tfplan

Passing Terraform Arguments​

Use -- to separate Overmind options from Terraform arguments:

# Pass variables to terraform
overmind terraform plan -- -var="environment=production"

# Use a variable file
overmind terraform plan -- -var-file=production.tfvars

# Set parallelism
overmind terraform plan -- -parallelism=20

# Combine multiple arguments
overmind terraform plan -- -var-file=prod.tfvars -target=aws_instance.web

Command Options​

Change Metadata Options​

These options add context to your changes:

OptionDescription
--titleShort title for the change. Auto-generated if not specified.
--descriptionQuick description of the change.
--ownerThe owner of this change.
--ticket-linkLink to the ticket/PR. Used as a unique identifier—multiple runs with the same link update the same Change.
--repoRepository URL. Auto-detected from Git config or CI environment.
--tagsTags in key=value format. Can be repeated or comma-separated.

Examples:

# Add metadata to a change
overmind terraform plan \
  --title "Update security groups" \
  --description "Restrict egress to port 8080 only" \
  --owner "platform-team" \
  --ticket-link "https://github.com/org/repo/pull/123"

# Add tags
overmind terraform plan --tags "env=production" --tags "team=platform"
overmind terraform plan --tags "env=production,team=platform"

Connection Options​

OptionDescriptionDefault
--appOvermind instance URLhttps://app.overmind.tech
--timeoutHow long to wait for responses31m

Change Identification Options​

Use these to link commands to existing changes:

OptionDescription
--changeFrontend URL of an existing change
--ticket-linkLink to the ticket for this change
--uuidUUID of an existing change

These options are mutually exclusive.

Source Configuration Options​

OptionDescription
--only-use-managed-sourcesSkip local credential discovery and only use managed sources configured in Overmind

Code Change Options​

OptionDescription
--terraform-plan-outputFilename of cached terraform plan output
--code-changes-diffFilename of the code diff for this change

Linking Plan and Apply​

When you run overmind terraform plan, a Change is created in Overmind. The subsequent overmind terraform apply automatically links to that Change using the --ticket-link identifier.

How linking works:

  1. plan creates a Change with a unique identifier (defaults to a hash of the plan file)
  2. apply finds the Change using the same identifier
  3. Both commands update the same Change record

For CI/CD pipelines, explicitly set --ticket-link to ensure plan and apply are linked:

# In your CI pipeline
TICKET_LINK="${CI_MERGE_REQUEST_URL:-$GITHUB_PR_URL}"

# Plan phase
overmind terraform plan --ticket-link "$TICKET_LINK"

# Apply phase (in a later job)
overmind terraform apply --ticket-link "$TICKET_LINK"

Authentication​

Local Development​

On first run, Overmind prompts you to authenticate via browser:

Please sign-up/login at https://app.overmind.tech/signup?code=XXXX-XXXX
Authentication succeeded.

Credentials are cached locally for subsequent runs.

CI/CD Environments​

Set the OVM_API_KEY environment variable with an API key from your account settings:

export OVM_API_KEY="your-api-key-here"
overmind terraform plan

Required API key permissions:

  • account:read
  • changes:write
  • config:write
  • request:receive
  • sources:read
  • source:write

Cloud Provider Access​

Overmind needs read-only access to discover your infrastructure. There are two approaches:

Automatic (Local Credentials)​

By default, Overmind uses your existing cloud credentials:

# AWS - uses your current profile
export AWS_PROFILE=production
overmind terraform plan

# GCP - uses application default credentials
gcloud auth application-default login
overmind terraform plan

On first run, you'll be prompted to confirm which credentials to use:

Choose how to access your AWS account (read-only):
> Use $AWS_PROFILE (currently: production)
  Use a different profile
  Use the default settings
  Configure managed source (opens browser)

Managed Sources​

For team environments, configure managed sources in the Overmind UI. These provide permanent, centrally-managed access without requiring local credentials.

Use --only-use-managed-sources to skip local credential discovery:

overmind terraform plan --only-use-managed-sources

Complete Workflow Example​

Here's a full example of using Overmind with Terraform:

# Navigate to your Terraform project
cd infrastructure/production

# Make your changes to *.tf files
# ...

# Analyze the impact of your changes
overmind terraform plan \
  --title "Scale web tier" \
  --ticket-link "https://jira.company.com/INFRA-123"

# Review the blast radius and risks in your browser
# Make any adjustments based on the analysis

# Apply the changes with tracking
overmind terraform apply \
  --ticket-link "https://jira.company.com/INFRA-123"

# View the before/after diff in Overmind

Docker Usage​

The Overmind CLI is available as a Docker container with OpenTofu included:

# Run terraform plan in a container
docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e OVM_API_KEY \
  ghcr.io/overmindtech/cli:latest \
  overmind terraform plan

Configuration​

When using overmind terraform plan, configuration is managed through your Overmind account settings:

  • Blast radius tuning: Configure analysis depth and scope via your account settings
  • Signals config: Configure in the Overmind UI to define what constitutes routine vs. high-risk changes

For advanced use cases requiring per-command configuration (local config files, custom blast radius parameters), use overmind changes submit-plan instead. See the CLI Configuration Guide for details.

Troubleshooting​

"No sources configured"​

Overmind needs access to your cloud accounts to discover infrastructure.

Solution: Either:

  • Ensure your cloud credentials are accessible (e.g., AWS_PROFILE is set)
  • Configure managed sources in the Overmind UI

"Blast radius incomplete"​

The blast radius analysis couldn't access all accounts or resources.

Solution:

  • Check that your sources have proper read permissions
  • Verify all relevant cloud accounts are configured
  • Review source logs in the Overmind UI

"Plan parsing failed"​

Terraform plan couldn't be parsed or executed.

Solution:

  • Verify terraform plan works on its own
  • Ensure you're running from the correct directory
  • Check Terraform is properly initialized (terraform init)

Authentication issues in CI/CD​

Solution:

  • Verify OVM_API_KEY is set correctly
  • Check the API key has the required permissions
  • Ensure the key hasn't expired

Next Steps​