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
- A complete inventory snapshot (
cloudopt collect … inventory, thencloudopt analyzeif you want enriched findings). - 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 resourceremediation: review steps; CloudOpt does not apply thempatch_suggestion: optional HCL hints when confidence is high; always hasrequires_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) and0750(directories).