Quickstart
This page switches one existing Terraform or OpenTofu configuration from hashicorp/aws to the compliance.tf provider for AWS, shows a finding, and explains how to switch back. The switch changes the provider address in your configuration, lock file and state; it creates, changes and recreates nothing in AWS.
The steps are for platform engineers trying the provider on one configuration before rolling it out. If the configuration already uses the provider and you need to fix a warning, go to Fix or record each finding.
Before you start
- Terraform 1.5 or later, or OpenTofu. Replacing a resource that has an identity needs Terraform 1.16.6 or later; see Errors and limits.
- A configuration you can already
initandplanwith your AWS credentials. - The version of
hashicorp/awsyou run today. The provider uses the same version numbers. - Run
terraform providers. Its "Providers required by state" part shows the address your state records. Its module list shows which modules still requirehashicorp/aws; their resources will not be checked (see Which modules are checked).
The commands use the Terraform address registry.terraform.io/hashicorp/aws. OpenTofu state usually records registry.opentofu.org/hashicorp/aws; use that address in the commands when it does. tofu takes the same commands.
Step 1: Change the provider source
Pin the exact version you run today while you switch:
terraform {
required_providers {
aws = {
source = "registry.compliance.tf/compliancetf/aws" # was "hashicorp/aws"
version = "6.70.0"
}
}
}Your provider "aws" block and every resource stay as they are.
Step 2: Initialize
terraform initThis adds a lock file entry for the new address. If your team or CI runs on other platforms, add their hashes, listing every platform you use:
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64Step 3: Point the state at the new provider
Skip this step if the configuration has no resources in state yet.
Resources in state still name hashicorp/aws. The command below rebinds every hashicorp/aws resource in the state; it has no module filter. Do not run it on a state that holds resources of modules that stay on hashicorp/aws, such as terraform-aws-modules. Decide what happens to those modules first: Which modules are checked lists the options.
Back up the state, then rebind it:
terraform state pull > state-default.backup.tfstate # holds secrets: keep it out of git and CI logs
terraform state replace-provider registry.terraform.io/hashicorp/aws registry.compliance.tf/compliancetf/awsThis changes only the provider address recorded in state, not your resources. Add -auto-approve in non-interactive runs. On OpenTofu, with the usual state address:
tofu state replace-provider registry.opentofu.org/hashicorp/aws registry.compliance.tf/compliancetf/awsDo this in every workspace and every state of the configuration. Planning a workspace does not change its state.
Step 4: Initialize again
terraform initReview the lock file diff. The hashicorp/aws entry is removed only when neither the state nor any module still requires it.
Step 5: Plan
terraform planIn the default soft_fail mode a violated control is a warning, and the exit code of terraform plan does not change. A warning looks like this:
Warning: [rds_db_instance_encryption_at_rest_enabled] RDS instances must have storage encryption enabled.
with aws_db_instance.non_compliant,
on main.tf line 25, in resource "aws_db_instance" "non_compliant":
25: storage_encrypted = false # deny
Fix: Set storage_encrypted = true.
Docs: https://compliance.tf/docs/controls/aws/rds_db_instance_encryption_at_rest_enabled/The first line names the control. The snippet shows the resource and the line. Fix: says what to set, and Docs: opens the control's page.
Check the result
terraform planproposes the same resource changes it did withhashicorp/aws, plus any compliance warnings.terraform providerslistsregistry.compliance.tf/compliancetf/awsfor the root module and for the state.- Each check wrote a record under
.terraform/compliancetf/evidence.
If the plan shows no warnings, the checked resources pass every control, or the resources are not checked: their type is not in the CIS control list, or they sit in child modules that require hashicorp/aws. To see findings on purpose, plan the soft-fail example; its README lists the expected warnings.
Undo it
Per configuration, the same steps in reverse:
- Set
sourceback tohashicorp/aws. If you pinned a prerelease such as6.70.0-compliancetf.1, change the pin to the matching6.70.0. Remove thecompliance {}block if you added one. - Run
terraform init. - In every workspace and state, run
terraform state replace-provider registry.compliance.tf/compliancetf/aws registry.terraform.io/hashicorp/aws. On OpenTofu the target is usuallyregistry.opentofu.org/hashicorp/aws. - Run
terraform initagain, review the lock file diff, and runterraform planfor each state.
If something goes wrong part way, undo only the steps you already did in that state. The reverse replace-provider is the normal way back. The backup is for last-resort recovery: terraform state push state-default.backup.tfstate refuses it once replace-provider has written a newer serial, and only -force overrides that check. -force overwrites whatever the state holds now, so use it only when nothing else changed that state since the backup.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Provider type mismatch on a module call | The call passes providers = { aws = aws } to a module that requires hashicorp/aws. The root aws is now compliancetf/aws | Remove the providers argument; see Which modules are checked |
Duplicate required provider warning | Both compliancetf/aws and hashicorp/aws are required under two local names | Expected for that layout; each block is used for its own provider |
| The first plan takes longer | The provider downloads and verifies hashicorp/aws once per pinned version, then reuses the cached copy | Persist the cache in CI; see Roll out and run in CI |
| An apply that replaces a resource is blocked | Terraform 1.12 to 1.16.5 and OpenTofu do not send the identity of the object a replace destroys | Use Terraform 1.16.6 or later, or taint the object first; see Errors and limits |