CloudFormation to Terraform Blueprint
Convert AWS IaC from CloudFormation to Terraform without rebuilding infrastructure. The core is importing live resources stack by stack until terraform plan shows no diff, replacing stack exports with remote state, and moving execution into a plan-on-PR pipeline.
What and Why
This blueprint converts AWS infrastructure-as-code from CloudFormation (and CDK-generated templates) to Terraform. Teams move for Terraform's multi-cloud reach, larger module ecosystem, and richer planning workflow. The critical constraint: the migration must not destroy or recreate live resources. It is a code and state migration, not an infrastructure rebuild.
Phases
Assessment. Inventory all CloudFormation stacks, their resources, dependencies, and outputs. Identify resources that other stacks reference via exports, and any custom resources or stack policies.
Module design. Design a Terraform module structure (per service or per environment) following module design patterns. Define remote state (S3 with DynamoDB locking) and a workspace or directory strategy per environment.
Import. This is the core. Write Terraform resource definitions that exactly match each live resource, then bring them under management with terraform import or, preferably, import blocks (Terraform 1.5+) which generate configuration. Migrate stack by stack; after each, terraform plan must show no changes, proving parity. Do not delete the CloudFormation stack until its resources are fully under Terraform management (retain resources on stack deletion).
Validation. For each migrated stack, confirm a clean plan (no diff), run policy and security scanning (tfsec/Checkov), and peer-review the HCL.
Pipeline. Move execution into CI (e.g., GitHub Actions or Terraform Cloud) with plan-on-PR and apply-on-merge, remote state, and least-privilege credentials via OIDC.
Key Risks and Mitigations
- Accidental resource recreation. Always verify a no-op plan after import before applying; never let Terraform replace imported resources.
- State drift during the dual-management window. Freeze CloudFormation changes per stack while migrating it.
- Dependency on stack exports. Replace cross-stack exports with Terraform remote state data sources.
- Skills gap on HCL and state. Start with a small, low-risk stack to build the playbook.
Recommended Tooling
Terraform with import blocks, remote state in S3 with locking, tfsec or Checkov for scanning, GitHub Actions or Terraform Cloud for the pipeline, and OIDC for credential-less CI.
Success Metrics
Track lead time for infrastructure changes, deployment frequency, reduction in config drift, and mean time to recovery for infrastructure incidents.
Prerequisites
A complete CloudFormation stack inventory, remote state backend, a change freeze process per stack during migration, and CI with secure AWS credentials.