Migrating to Compliance.tf

You are already using the right modules. Migration from upstream terraform-aws-modules to compliance.tf is a source URL change — typically no resource recreation, no state surgery, no workflow changes.

Some compliance controls enforce values you may not have set yet. Your terraform plan output will tell you exactly what needs attention — that is the migration working as designed, not a failure.

What Changes and What Doesn't

What changes

The module source URL changes: terraform-aws-modules/s3-bucket/aws becomes soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws. With that, compliance controls are enforced. terraform plan will fail if your current configuration does not satisfy all active controls for your chosen framework, and each error tells you exactly what to fix.

What does NOT change

Terraform tracks resources by their address (module.s3_bucket.aws_s3_bucket.this[0]), not by the module source URL. Changing the source does not recreate resources. The module interface is also identical: same arguments, same variable names, same types.

• Terraform workflow — same init, plan, apply cycle. No new CLI tools, no policy engines, no sidecars.
• Provider configuration — no new providers, no provider version changes.
• Your existing variable definitions and .tfvars files work without modification.
• No state migration, no backend reconfiguration.

Step-by-Step Migration

Step 1: Pick a framework

Each compliance framework maps to a registry endpoint. Your framework determines which controls are enforced.

Not sure which framework to pick? Start with SOC 2 — it covers the broadest set of general security controls and is the most commonly used endpoint.

See all supported frameworks and registry endpoints for the full list.

Step 2: Configure authentication

You need an access token to download modules from the compliance.tf registry. If you have already configured authentication from the Get Started guide, skip to Step 3.

terraform login soc2.compliance.tf

credentials "soc2.compliance.tf" {
  token = "ctf_YOUR_TOKEN_HERE"
}

machine soc2.compliance.tf
    login anything
    password ctf_YOUR_TOKEN_HERE

For detailed authentication setup, see Get Started and Registry Endpoints.

Step 3: Change the source URL

Replace the upstream terraform-aws-modules source with the compliance.tf endpoint.

 module "s3_bucket" {
-  source  = "terraform-aws-modules/s3-bucket/aws"
+  source  = "soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws"
   version = "5.0.0"

   bucket = "my-app-data"
 }

 module "s3_bucket" {
-  source  = "terraform-aws-modules/s3-bucket/aws"
-  version = "5.0.0"
+  source  = "https://soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws?version=5.0.0"

   bucket = "my-app-data"
 }

Version constraints work the same way. If you already pin versions (and you should), keep your existing version constraint.

# Find all files referencing the upstream S3 module
rg 'source\s*=\s*"terraform-aws-modules/s3-bucket/aws"' --type tf -l

# Replace with the compliance.tf source (macOS sed)
find . -name '*.tf' -exec sed -i '' \
  's|"terraform-aws-modules/s3-bucket/aws"|"soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws"|g' {} +

# Replace with the compliance.tf source (Linux sed)
find . -name '*.tf' -exec sed -i \
  's|"terraform-aws-modules/s3-bucket/aws"|"soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws"|g' {} +

# macOS
find . -name '*.tf' -exec sed -i '' \
  's|"terraform-aws-modules/|"soc2.compliance.tf/terraform-aws-modules/|g' {} +

# Linux
find . -name '*.tf' -exec sed -i \
  's|"terraform-aws-modules/|"soc2.compliance.tf/terraform-aws-modules/|g' {} +

rg 'source\s*=.*compliance\.tf' --type tf

Step 4: Run terraform init -upgrade

terraform init -upgrade

The -upgrade flag is required. It tells Terraform to re-download modules from the new source even if a cached version exists.

Expected output:

Initializing modules...
Downloading soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws 5.0.0 for s3_bucket...
- s3_bucket in .terraform/modules/s3_bucket

Initializing provider plugins...

Terraform has been successfully initialized!

Step 5: Run terraform plan

terraform plan

One of two things will happen:

Clean plan — your existing configuration already satisfies all controls. You will see the standard Terraform plan output. For existing infrastructure, this typically shows No changes. Your infrastructure matches the configuration. or minor in-place updates.

Validation errors — one or more controls require values you have not set. This is expected. Each error message names the control, explains what is required, and lists the frameworks that require it:

│ Error: Invalid value for variable
│
│   on main.tf line 3, in module "s3_bucket":
│    3:   source  = "soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws"
│
│ s3_bucket_logging_enabled: logging.target_bucket must be set
│ to enable S3 bucket access logging.
│
│ Frameworks requiring this control:
│   SOC 2, CIS AWS v1.4.0 (3.6), PCI DSS v4.0 (10.2.1)

This is the migration working as designed. The module is telling you what your infrastructure needs to be compliant. Proceed to Step 6.

Step 6: Fix validation errors

Each validation error tells you the control name and what value to provide. Most fixes are adding a single argument or block.

Example: S3 logging control

The error above requires a logging block with a target_bucket. Add it to your module configuration:

module "s3_bucket" {
  source  = "soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws"
  version = "5.0.0"

  bucket = "my-app-data"

  # Fix: add logging configuration
  logging = {
    target_bucket = "my-logging-bucket"
    target_prefix = "s3-access-logs/my-app-data/"
  }
}

Run terraform plan again. Repeat until plan succeeds.

module "s3_bucket" {
  source = "https://soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws?version=5.0.0&disable=s3_bucket_object_lock_enabled"

  bucket = "my-app-data"

  logging = {
    target_bucket = "my-logging-bucket"
    target_prefix = "s3-access-logs/my-app-data/"
  }
}

Step 7: Apply

terraform apply

Once your plan is clean, terraform apply works exactly as before. For existing infrastructure, the apply will make in-place changes for any new attribute values you added (logging configuration, encryption settings, etc.) — it will not recreate resources.

After apply, your state reflects the compliance.tf module source. The resource addresses are unchanged.

Per-Module Migration Impact

Migration difficulty varies by module. Some modules migrate with zero plan changes. Others require additional values to satisfy compliance controls. The table below covers all 34 supported modules.

Migration impact key:

• Usually clean — terraform plan shows no changes or only minor in-place updates. No new arguments needed.
• Minor fixes — plan fails with 1-3 validation errors. Each fix is adding an argument or block. Typically 15-30 minutes including testing.
• Minor to significant — depends on your existing configuration. If encryption is already enabled, migration is clean. If not, the fix may require resource recreation (an AWS limitation, not a compliance.tf limitation).

Migrating Multiple Modules

Start with one module

Start with S3 if you use it. It has the highest control count and will surface the most validation errors, giving you a clear picture of what compliance.tf enforces. If you do not use S3, pick any module with "Usually clean" impact from the table above.

After your first module migrates cleanly and you have applied the changes, batch the rest by migration difficulty.

Batch by difficulty

1. First batch: all "Usually clean" modules (ACM, AppSync, CloudWatch, KMS, Lambda, Secrets Manager, SNS, SQS, SSM Parameter, Step Functions, VPN Gateway). These should migrate with zero or minimal plan changes.
2. Second batch: "Minor fixes" modules (S3, ALB, API Gateway V2, Auto Scaling, CloudFront, DMS, DynamoDB, EC2, ECR, ECS, EFS, EKS, ELB, MSK, Network Firewall, OpenSearch, RDS, RDS Aurora, VPC). Fix validation errors one module at a time.
3. Third batch: "Minor to significant" modules (ElastiCache, EMR, FSx, Redshift). Plan for potential resource recreation if encryption is not already enabled.

Phased approach for large teams

For teams managing many modules across multiple environments:

During any phase, compliance.tf modules and upstream terraform-aws-modules coexist in the same codebase without conflict. There is no requirement to migrate everything at once.

Team coordination workflow

For a team of 4–10 engineers migrating across multiple services:

Platform lead responsibilities:

1. Complete the first module migration yourself (S3 or VPC) to establish the pattern
2. Set up registry authentication in CI/CD — one-time setup for the team
3. Create a migration tracking table (spreadsheet or issue board) listing every module, its current source, assigned engineer, and status
4. Add the optional module source governance CI step in warning mode during migration, switching to blocking after Phase 3

Individual engineer responsibilities:

1. Pick an unassigned module from the tracking table and mark it as in-progress
2. Change the source URL, run terraform plan, and fix validation errors
3. Open a PR with the source URL change and any configuration fixes

PR review checklist for module migrations:

• [ ] Source URL changed to <framework>.compliance.tf/...
• [ ] terraform plan output is clean (no validation errors)
• [ ] Any ?disable= parameters have a documented justification in the PR description
• [ ] No unrelated changes bundled with the migration

Handling the transition period:

During migration, some modules will use compliance.tf and others will still use upstream sources. This is expected and safe — the modules are independent. Track progress in your migration table and aim for one batch per sprint.

Rollback

If you need to switch back to upstream modules:

1. Change the source URL back to terraform-aws-modules/...
2. Run terraform init -upgrade
3. Run terraform plan to confirm

That is the complete rollback. No state surgery. No resource changes. Your deployed infrastructure is unchanged — the values you configured (logging, encryption, etc.) remain in place because they are standard AWS resource attributes, not proprietary settings.

Compliance enforcement stops after rollback. terraform plan will no longer validate controls, but the security configurations you already deployed continue to protect your resources.

Frequently Asked Questions

module "s3_bucket" {
  source = "https://soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws?version=5.0.0&disable=s3_bucket_object_lock_enabled"
  # ...
}

What's Next

• New to compliance.tf? — Get Started covers account setup, authentication, and your first compliant module
• Need to disable or enable specific controls? — Customize modules
• Want to see what controls are enforced? — Browse controls by module
• Looking for your compliance framework? — Browse supported frameworks