Infrastructure as code has matured into the backbone of platform engineering, and teams operating on AWS frequently encounter a decision point between staying with AWS CloudFormation or adopting Terraform for ongoing infrastructure management. The migration is not a simple file conversion. It is a systematic transfer of resource ownership, state control, and operational workflow from an AWS-native stack model to a provider-agnostic, state-file based model with multi-cloud capabilities.
The primary audience for a guided migration is cloud architects and platform teams, and DevOps and infrastructure engineers who need to maintain production stability while changing tooling. Completing a responsible migration requires an active AWS account, a GitHub, BitBucket, or other source repository for version control, an HCP Terraform account for state handling, and a review of the Terraform Solution Design Guide and Operating Guides.
Why Teams Move From CloudFormation To Terraform
Teams migrate for several reasons. Terraform supports multiple cloud providers, enabling a unified workflow for multi-cloud environments. The Terraform module registry provides thousands of reusable modules. HCL is often considered more readable than CloudFormation's JSON or YAML. Terraform's plan command gives a clear preview of changes before applying. Additionally, Terraform's state management and import capabilities have matured significantly.
Terraform modules provide a way to create reusable and composable infrastructure components, promoting consistency and reducing duplication in infrastructure code. This extensive provider support makes Terraform a versatile tool for multi-cloud and hybrid-cloud deployments. AWS CloudFormation is designed only to support AWS cloud infrastructure deployment.
Multi-cloud reach is a practical differentiator. Terraform allows deployment to other cloud providers as well. Granted, you will not be able to re-use the same codebase from one cloud provider to another, but at the very least, when using Terraform, there is familiar syntax and methods for deploying to different cloud providers. For some companies, this is a significant benefit, as being able to use the same syntax and deployment methods to deploy to multiple cloud providers is a clear plus.
Core Differences That Shape Migration Decisions
Understanding the differences between these two infrastructure as code offerings is essential before any migration planning.
Language is a foundational difference. CloudFormation uses JSON or YAML to define infrastructure as code, while Terraform utilizes HCL, HashiCorp Configuration Language.
State management diverges significantly. Terraform maintains a state file to track infrastructure resources, enabling better management and collaboration. HCP Terraform simplifies this process by automatically handling state management, offering a secure and scalable solution for teams. AWS CloudFormation manages the state of your AWS infrastructure using a concept called stacks.
Providers and scope are also distinct. Terraform supports a wide range of providers, not just AWS. This includes Google Cloud, Azure, and many others. This extensive provider support makes Terraform a versatile tool for multi-cloud and hybrid-cloud deployments. AWS CloudFormation is designed only to support AWS cloud infrastructure deployment.
Terraform is multi-cloud and uses HashiCorp Configuration Language, whereas CloudFormation is AWS-native and uses JSON or YAML. Terraform is generally preferred for complex, cross-platform infrastructure management, whereas CloudFormation is optimal for teams operating solely within AWS.
Community and documentation patterns differ. Being provider-agnostic gives Terraform the edge when it comes to community. Many organizations contribute modules and providers to the ecosystem, but sometimes, this means that documentation can be as good as the provider's documentation itself.
CloudFormation has an active AWS community, that is smaller when compared to Terraform's. The documentation is very thorough but can be overwhelming. Integration with AWS-specific features and services is well-documented, which is beneficial for users fully committed to the AWS ecosystem.
Cost models are similar in practice. Terraform is free to run. CloudFormation is also free for native AWS resources: you pay only for the resources you provision.
A comparison of the key dimensions is summarized below.
| Dimension | Terraform | AWS CloudFormation |
| Language | HCL | JSON or YAML |
| State Management | State file, HCP Terraform managed state | Stacks, AWS managed |
| Provider Scope | Multi-cloud: AWS, Google Cloud, Azure, many others | AWS only |
| Reuse | Modules for composable components | Nested stacks, templates |
| Preview Changes | plan command | change sets |
| Cost | Free to run | Free, pay for provisioned resources |
State Management And Ownership Risks
CloudFormation stacks own the resources they create. If you simply delete a stack, CloudFormation deletes most resources unless a DeletionPolicy or resource-specific default changes that behavior. The migration must transfer resource management from CloudFormation to Terraform without deleting anything.
This is the central migration challenge. CloudFormation stacks own the resources they create. If you simply delete a stack, CloudFormation deletes most resources unless a DeletionPolicy or resource-specific default changes that behavior. The migration must transfer resource ownership without recreating or disrupting existing infrastructure.
Mapping CloudFormation resources to Terraform requires manual effort due to the differences in design and usage between the two tools. CloudFormation is an AWS-specific UI tool, while Terraform is a CLI-based tool focused on automation.
State transfer is handled through import. Terraform's state management and import capabilities have matured significantly, allowing existing resources to be imported into Terraform state without recreation. The Terraform configuration maps each element from the CloudFormation template, ensuring a smooth migration.
A systematic approach to convert existing infrastructure as code setups is required. Migrating from AWS CloudFormation to HCP Terraform involves a systematic approach to convert existing infrastructure as code setups.
Manual Mapping And Design Patterns
Mapping is manual because the tools model resources differently. It is important for enterprises migrating from AWS CloudFormation to HCP Terraform to understand the differences between these two infrastructure as code offerings.
The purpose of this document is to outline patterns for migrating CloudFormation templates and AWS resources to Terraform. Mapping CloudFormation resources to Terraform requires manual effort due to the differences in design and usage between the two tools.
A typical CloudFormation DynamoDB table definition illustrates the level of detail that must be translated.
AWSTemplateFormatVersion: "2010-09-09"
Resources:
myDynamoDBTable:
Type: AWS::DynamoDB::Table
Properties:
AttributeDefinitions:
-
AttributeName: "Album"
AttributeType: "S"
-
AttributeName: "Artist"
AttributeType: "S"
-
AttributeName: "Sales"
AttributeType: "N"
-
AttributeName: "NumberOfSongs"
AttributeType: "N"
KeySchema:
-
AttributeName: "Album"
KeyType: "HASH"
-
AttributeName: "Artist"
KeyType: "RANGE"
ProvisionedThroughput:
ReadCapacityUnits: "5"
WriteCapacityUnits: "5"
TableName: "myTableName"
GlobalSecondaryIndexes:
-
IndexName: "myGSI"
KeySchema:
-
AttributeName: "Sales"
KeyType: "HASH"
-
AttributeName: "Artist"
KeyType: "RANGE"
Projection:
NonKeyAttributes:
- "Album"
- "NumberOfSongs"
ProjectionType: "INCLUDE"
ProvisionedThroughput:
ReadCapacityUnits: "5"
WriteCapacityUnits: "5"
-
IndexName: "myGSI2"
KeySchema:
-
AttributeName: "NumberOfSongs"
KeyType: "HASH"
-
AttributeName: "Sales"
KeyType: "RANGE"
Projection:
NonKeyAttributes:
- "Album"
- "Artist"
ProjectionType: "INCLUDE"
ProvisionedThroughput:
ReadCapacityUnits: "5"
WriteCapacityUnits: "5"
LocalSecondaryIndexes:
-
IndexName: "myLSI"
KeySchema:
-
AttributeName: "Album"
KeyType: "HASH"
-
AttributeName: "Sales"
KeyType: "RANGE"
Projection:
NonKeyAttributes:
- "Artist"
- "NumberOfSongs"
ProjectionType: "INCLUDE"
Terraform can be used to execute existing CloudFormation runs as an intermediate step. This is useful when you have completed runbooks in CloudFormation and are seeking an easier way to migrate existing CloudFormation scripts to HCP Terraform. This approach allows for a smoother transition while maintaining the integrity of your current infrastructure setup.
Suppose you have a CloudFormation template stored in an S3 bucket. You can use the awscloudformationstack resource in Terraform to deploy the template.
provider "aws" {
region = "us-west-2"
}
resource "aws_cloudformation_stack" "example" {
name = "example-stack"
template_url = "https://my-bucket.s3.amazonaws.com/templates/my-template.yaml"
parameters = {
ParameterKey = "ParameterValue"
}
tags = {
Name = "example-stack"
}
}
The same pattern works with GitHub-hosted templates.
provider "aws" {
region = "us-west-2"
}
resource "aws_cloudformation_stack" "example" {
name = "example-stack"
template_url = "https://raw.githubusercontent.com/my-repo/cloudformation-templates/main/templates/my-template.yaml"
parameters = {
ParameterKey = "ParameterValue"
}
tags = {
Name = "example-stack"
}
}
Using Terraform to manage and run your current CloudFormation templates makes it easy to switch to Terraform while keeping your existing infrastructure setup.
Phased Migration Practices
A safe migration follows a phased approach. First, inventory all CloudFormation stacks and resources, noting dependencies, outputs, and custom resources. Next, design Terraform modules that mirror the logical groupings of those resources. Then import existing resources into Terraform state using terraform import, verifying that the imported configuration matches the live infrastructure.
Running Terraform plan after import should show no changes. If differences appear, reconcile the configuration before applying. Once the import is verified, gradually replace awscloudformationstack wrappers with native Terraform resources. Maintain parallel runs for a period to validate behavior.
For teams needing a gradual transition, Terraform with CloudFormation can be used to execute existing CloudFormation runs while new components are built natively in Terraform. This hybrid model reduces risk and allows platform teams to migrate at their own pace.
Can Terraform And CloudFormation Coexist
Yes. You can theoretically achieve deployment to third-party resources through the use of custom resources, but this is rather hacky, and at the end of the day, those third-party resources are not truly supported by CloudFormation. On the other hand, Terraform allows you to deploy to other cloud providers as well.
In practice, many organizations run CloudFormation for legacy AWS-only stacks and Terraform for new multi-cloud workloads, or use Terraform to orchestrate CloudFormation stacks via awscloudformationstack during a transition window.
Conclusion
Migrating from AWS CloudFormation to Terraform is a design and operational shift, not a mechanical translation. The move trades AWS-native stack ownership for provider-agnostic state management, HCL readability, and module reuse. The key risks center on state ownership and accidental resource deletion during transfer, which can be mitigated through careful import planning, phased adoption, and the use of Terraform to wrap existing CloudFormation templates temporarily.
The decision to migrate is driven by multi-cloud needs, collaboration requirements, and the desire for a unified IaC workflow. For teams committed to AWS only, CloudFormation remains a capable and well-documented choice. For organizations seeking portability, richer module ecosystems, and centralized state management through HCP Terraform, the investment in manual mapping and migration patterns pays off in long-term operational flexibility.