Sign in
Menu
Sign up
Docs

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 init and plan with your AWS credentials.
  • The version of hashicorp/aws you 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 require hashicorp/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 init

This 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_arm64

Step 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/aws

This 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/aws

Do this in every workspace and every state of the configuration. Planning a workspace does not change its state.

Step 4: Initialize again

terraform init

Review 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 plan

In 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 plan proposes the same resource changes it did with hashicorp/aws, plus any compliance warnings.
  • terraform providers lists registry.compliance.tf/compliancetf/aws for 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:

  1. Set source back to hashicorp/aws. If you pinned a prerelease such as 6.70.0-compliancetf.1, change the pin to the matching 6.70.0. Remove the compliance {} block if you added one.
  2. Run terraform init.
  3. 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 usually registry.opentofu.org/hashicorp/aws.
  4. Run terraform init again, review the lock file diff, and run terraform plan for 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

SymptomCauseFix
Provider type mismatch on a module callThe call passes providers = { aws = aws } to a module that requires hashicorp/aws. The root aws is now compliancetf/awsRemove the providers argument; see Which modules are checked
Duplicate required provider warningBoth compliancetf/aws and hashicorp/aws are required under two local namesExpected for that layout; each block is used for its own provider
The first plan takes longerThe provider downloads and verifies hashicorp/aws once per pinned version, then reuses the cached copyPersist the cache in CI; see Roll out and run in CI
An apply that replaces a resource is blockedTerraform 1.12 to 1.16.5 and OpenTofu do not send the identity of the object a replace destroysUse Terraform 1.16.6 or later, or taint the object first; see Errors and limits

Next steps

On this page

Ask AI about this

Help improve this page