Terraform Correlation

Match live inventory to Terraform state and plan JSON for CI and remediation context.

Match collected inventory against Terraform state and plan JSON. You export the JSON with terraform show; CloudOpt reads the files. It does not shell out to Terraform or change infrastructure.

With correlation you can:

  • Point findings at Terraform addresses
  • List live resources with no IaC owner, and Terraform addresses with no live match
  • Read plan-time cost and policy warnings before apply
  • Write JSON or PR-comment Markdown for CI

Prerequisites

  1. A complete inventory snapshot (cloudopt collect … inventory, then cloudopt analyze if you want enriched findings).
  2. Terraform JSON on disk:
terraform show -json > state.json
terraform plan -out=plan.tfplan
terraform show -json plan.tfplan > plan.json

Pass file paths with --state-json and, if you have one, --plan-json.

Basic usage

cloudopt terraform correlate \
  --state-json ./state.json \
  --snapshot-id <snapshot-id>

Omit --snapshot-id and CloudOpt picks the latest complete snapshot when it needs inventory.

By default you get reports/terraform-correlation-<timestamp>.json. Add --json for stdout, or --json-out / --markdown-out for fixed paths.

Enrich findings

Add Terraform addresses, module paths, and remediation hints to analysis findings:

cloudopt analyze

cloudopt terraform correlate \
  --state-json ./state.json \
  --enrich-findings \
  --analysis-run-id <run-id>

With --enrich-findings and no --analysis-run-id, CloudOpt uses the latest analysis run for that snapshot.

The JSON adds enriched_findings:

  • resource_links: correlation metadata per resource
  • remediation: review steps; CloudOpt does not apply them
  • patch_suggestion: optional HCL hints when confidence is high; always has requires_review: true

Explicit mappings

If you renamed a resource in the console and automatic matching fails, add a YAML file:

mappings:
  - resource_id: res-renamed
    terraform_address: aws_instance.legacy_name
    note: explicit mapping after resource rename in AWS console
cloudopt terraform correlate \
  --state-json ./state.json \
  --mappings ./mappings.yaml

resource_id is CloudOpt’s canonical ID from the snapshot, not the cloud provider ID.

Plan forecast

Add --plan-json for forecast checks. These sit beside live-state findings; drift still comes from the snapshot.

cloudopt terraform correlate \
  --state-json ./state.json \
  --plan-json ./plan.json \
  --markdown-out ./correlation-summary.md

plan_analysis lists create/update/delete actions, estimated cost direction, and built-in policy warnings (NAT Gateway creates, instance upsizes, and similar). Plan rows use source_kind: terraform_plan.

In CI, add --strict-plan to exit with code 7 when plan policy warnings appear.

Correlation methods

Matching order:

Method Confidence When used
user_mapping High Entry in --mappings YAML
provider_id High Terraform id matches live provider resource ID
tag_label Medium Tags or labels align
module_metadata Medium Module path / for_each / count metadata
name_heuristic Low Name similarity when IDs differ

Two Terraform resources sharing one cloud ID produce ambiguous: true and a candidates list. Heuristic matches marked ambiguous stay below high confidence.

State JSON from AWS, GCP (Google), Azure, and DigitalOcean providers is supported.

CI workflow example

cloudopt collect aws inventory --regions us-east-1
cloudopt analyze

cloudopt terraform correlate \
  --state-json "$TF_STATE_JSON" \
  --plan-json "$TF_PLAN_JSON" \
  --enrich-findings \
  --markdown-out correlation.md \
  --json-out correlation.json \
  --strict-plan

Exit codes

Code Meaning
0 No ambiguous links; no strict-plan violations
5 Done, but at least one ambiguous link (for gradual CI rollout)
7 --strict-plan and plan policy warnings

Invalid input returns 2; other errors return 1.

Security

  • Treat state and plan JSON as untrusted input. CloudOpt parses defensively and does not execute Terraform.
  • Patch suggestions are for review; CloudOpt does not apply changes.
  • CloudOpt writes output at 0600 (files) and 0750 (directories).

Commands · Configuration