Terraform workspace and state inspection cheat sheet
Verify the active workspace, provider requirements, configuration validity and recorded resources before planning infrastructure changes.
Terraform CLI in an already initialized, trusted configuration directory with the intended backend access.
Updated · Terraform · 6 min read
| Command | What it does |
|---|---|
terraform version | Record CLI and installed provider versions |
terraform workspace show | Identify the selected CLI workspace |
terraform providers | Inspect provider requirements by module |
terraform validate | Validate configuration in the initialized directory |
terraform state list | List addresses in the selected state |
terraform state show 'aws_instance.web' | Inspect one recorded resource |
Walkthrough
Use the approved checkout and installed providers. Replace aws_instance.web with a real state address. These commands do not apply changes; state output can expose infrastructure identifiers and sensitive values.
Step 1: Record CLI and installed provider versions
terraform version
Compare the CLI and provider versions with the project constraints and lock file. A local version difference can explain validation behavior. Version output alone does not prove that the correct backend or cloud account is selected.
Step 2: Identify the selected CLI workspace
terraform workspace show
Compare the workspace name with the deployment process. A workspace is a state selection mechanism, not proof of cloud account identity. HCP Terraform workspace mapping and backend configuration require their own verification.
Step 3: Inspect provider requirements by module
terraform providers
Compare provider requirements from configuration and state with the expected modules. This helps identify an unexpected dependency or migration gap; it does not query whether the remote resource is healthy or whether credentials are valid.
Step 4: Validate configuration in the initialized directory
terraform validate
Read errors about configuration structure, types and provider schema. Required modules and providers must already be installed. Validation does not compare real infrastructure with state or establish that a later plan will be accepted by an API.
Step 5: List addresses in the selected state
terraform state list
Find the expected module and resource addresses. Empty state can mean a new workspace, wrong backend, wrong workspace or genuinely unmanaged infrastructure. Do not import or create resources until the state-selection question is settled.
Step 6: Inspect one recorded resource
terraform state show 'aws_instance.web'
Use the exact address from state list, preserving quotes for indexed addresses where required. This displays recorded state and does not refresh remote facts. Protect the output; it can include sensitive values and internal resource details.
WORKED INCIDENT
Practical case: A resource exists in the cloud but not in state list
Fictional teaching scenario; observations are examples, not captured production output.
Situation
An engineer is preparing a change and cannot find the production instance in the current Terraform state.
Investigation sequence
1. Identify the selected CLI workspace
terraform workspace showCheck the active workspace. This example reports default rather than the intended production workspace.
2. Inspect provider requirements by module
terraform providersCompare the module/provider layout with the repository used by the production pipeline.
3. List addresses in the selected state
terraform state listRecord the current state addresses without importing or creating anything.
4. Validate configuration in the initialized directory
terraform validateValidate configuration separately; a valid configuration does not make the state selection correct.
Example findings
Illustrative findings: current workspace = default; state list is empty; the production runner is documented to use another state selection.
Interpret the findings
A state-selection mismatch is the leading explanation. The cloud resource existing does not mean that importing it into this empty state is appropriate; it may already belong to the intended production state.
Verify the outcome
After the owner selects the approved backend/workspace through the normal process, repeat workspace show and state list. Compare recorded resource identity with the cloud account before requesting a reviewed plan.
Escalation handoff
Provide the checkout revision, workspace, backend identity and expected resource address to the infrastructure owner. Avoid publishing state contents or changing backend settings during evidence collection.