CloudFormation JSON to Terraform Converter

How to convert a CloudFormation JSON template to Terraform

To convert CloudFormation JSON to Terraform, paste the template into the editor above and press Convert to Terraform. Each resource becomes a resource block, Parameters become variables, Outputs become outputs, and intrinsic functions become HCL expressions. Then run terraform validate and import the live resources before you apply anything.

1. Add the templatePaste the JSON into the CloudFormation (JSON) editor, or open a .json, .template or .txt file up to 500 KB. For a deployed stack, aws cloudformation get-template --stack-name NAME returns the template body. Sample loads an SNS topic that delivers to an SQS queue.
2. Let the secret check runTemplates sometimes carry real values in parameter defaults. Before anything is sent, the page scans for AWS keys, private keys and common API tokens, and points to any it finds so you can replace them.
3. Convert to TerraformClick Convert to Terraform or press Ctrl + Enter. The HCL streams into the right-hand editor, and you can stop it at any time. One conversion takes up to 60,000 characters, so split very large templates by nested stack or by service.
4. Review and validateCheck every Ref and Fn::GetAtt against the attribute it became, and look for TODO: comments. Download the result as main.tf, then run terraform init and terraform validate to catch argument names that don't exist.
5. Import, then planRetain the resources in CloudFormation, delete the stack, and add an import block for each resource. terraform plan should report no changes before you ever run apply.

Why convert a CloudFormation JSON template to Terraform

Teams usually make this move when Terraform becomes the standard for new infrastructure and the older CloudFormation stacks are the odd ones out. JSON templates are common among those older stacks, and they're also what you get from aws cloudformation get-template or from tools that generate CloudFormation, such as troposphere.

Rewriting JSON by hand is slow and error-prone. Every value is wrapped in an Fn:: object, properties are PascalCase while Terraform arguments are snake_case, and some properties become nested blocks or even separate resources. This converter produces a first draft of the whole template in one pass, so your time goes into checking references and importing resources rather than retyping them.

If the JSON came from cdk synth, converting the CDK source with the AWS CDK to Terraform converter usually gives more readable code than converting the synthesized template. And if your templates are in YAML, use the CloudFormation YAML to Terraform converter instead.

Translating intrinsic functions to Terraform

The heart of this conversion is CloudFormation's intrinsic functions. {"Ref": "OrderQueue"} becomes a resource attribute such as aws_sqs_queue.order_queue.id, Fn::GetAtt becomes an attribute like .arn, and Fn::Sub becomes string interpolation: "order-events-${var.env}". Parameters become variable blocks and Outputs become output blocks.

What Ref returns depends on the resource type: an SNS topic's ARN, but an SQS queue's URL and an S3 bucket's name. The converter has to pick the matching Terraform attribute for each case, so these are the first lines to check. Conditions usually become count expressions, and Mappings become maps in locals.

Converting the template doesn't release the resources from their CloudFormation stack. Retain them in the stack first, then adopt them with Terraform import blocks.

CloudFormation JSON to Terraform: quick reference

How the parts of a JSON template usually translate. The right-hand column says what to check in the converted code.

Key features

• Intrinsic functions become HCLRef, Fn::GetAtt, Fn::Sub, Fn::Join, Fn::If and Fn::FindInMap are rewritten as Terraform references, interpolation and functions.
• Every template section mappedParameters become variables, Outputs become outputs, and Conditions and Mappings become locals, count and conditional expressions.
• Properties become provider argumentsPascalCase properties become the matching snake_case arguments, such as VisibilityTimeout to visibility_timeout_seconds, with nested blocks where the provider uses them.
• Pseudo parameters handledAWS::AccountId, AWS::Region and AWS::Partition become data sources such as aws_caller_identity instead of hard-coded values.
• Gaps are flaggedCustom resources, macros and properties with no Terraform argument get a TODO: comment rather than a silent guess.
• Large templates, one filePaste up to 60,000 characters, or open a .json or .template file up to 500 KB.
• Secret check before sendingParameter defaults and outputs are scanned for AWS keys, private keys and tokens in your browser before the template leaves it.
• Ready to save as main.tfCopy the HCL or download it as main.tf, then run it through terraform validate.

Examples: CloudFormation JSON converted to Terraform

Two constructs that need more than renaming. Each shows the JSON and the Terraform it should become. Choose Try this example to load the JSON into the converter; your output may be laid out differently.

{
  "Parameters": {
    "Env": { "Type": "String", "AllowedValues": ["dev", "prod"] }
  },
  "Conditions": {
    "IsProd": { "Fn::Equals": [{ "Ref": "Env" }, "prod"] }
  },
  "Resources": {
    "LogsBucket": {
      "Type": "AWS::S3::Bucket",
      "Condition": "IsProd",
      "Properties": {
        "BucketName": {
          "Fn::Join": ["-", ["app-logs", { "Ref": "AWS::AccountId" }]]
        }
      }
    }
  }
}

variable "env" {
  type = string

  validation {
    condition     = contains(["dev", "prod"], var.env)
    error_message = "env must be dev or prod."
  }
}

data "aws_caller_identity" "current" {}

locals {
  is_prod = var.env == "prod"
}

resource "aws_s3_bucket" "logs_bucket" {
  count  = local.is_prod ? 1 : 0
  bucket = join("-", ["app-logs", data.aws_caller_identity.current.account_id])
}

{
  "Parameters": {
    "Env": { "Type": "String", "Default": "dev" }
  },
  "Mappings": {
    "SizeByEnv": {
      "dev": { "Instance": "t3.micro" },
      "prod": { "Instance": "m6i.large" }
    }
  },
  "Resources": {
    "Worker": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": "ami-0123456789abcdef0",
        "InstanceType": { "Fn::FindInMap": ["SizeByEnv", { "Ref": "Env" }, "Instance"] },
        "SubnetId": { "Fn::ImportValue": "network-PrivateSubnetA" }
      }
    }
  }
}

variable "env" {
  type    = string
  default = "dev"
}

locals {
  size_by_env = {
    dev  = { instance = "t3.micro" }
    prod = { instance = "m6i.large" }
  }
}

data "aws_cloudformation_export" "private_subnet_a" {
  name = "network-PrivateSubnetA"
}

resource "aws_instance" "worker" {
  ami           = "ami-0123456789abcdef0"
  instance_type = local.size_by_env[var.env].instance
  subnet_id     = data.aws_cloudformation_export.private_subnet_a.value
}

Tips for better results

• Expand transforms first. SAM templates (AWS::Serverless-2016-10-31) and macros hide the real resources. Get the processed template with aws cloudformation get-template --template-stage Processed and convert that.
• Convert nested stacks one at a time. Each nested template maps well to its own Terraform module.
• Keep the Outputs section. It tells the converter which values other stacks and systems rely on, so they become output blocks.
• Custom resources don't convert directly. Custom:: types run a Lambda function during deployment. Replace them with a native Terraform resource or a separate step.
• Plan after importing. Once resources are imported, terraform plan should report no changes. Differences point to arguments the converter set differently from the live resource.

Common mistakes to avoid

• Trusting every Ref. Ref returns an SQS queue's URL, an SNS topic's ARN and an S3 bucket's name. Check each one maps to the matching attribute.
• Skipping terraform validate. Converted arguments can look right and still not exist. For example, aws_sqs_queue_policy takes a single queue_url, not a queues list. Validate before you plan.
• Keeping names the template never set. When a template leaves a name out, CloudFormation generates one. If the converted code adds its own name, it won't match the live resource you import.
• Deleting the stack without Retain. CloudFormation deletes the resources with the stack unless DeletionPolicy says otherwise.
• Applying before importing. Without import blocks, terraform apply tries to create a second copy of every resource, or fails on names that already exist.
• Treating prevent_destroy as Retain. It makes Terraform refuse to destroy the resource; it doesn't leave the resource behind when you remove it from the code.

Frequently asked questions

Related tools and next steps

• CloudFormation YAML to TerraformThe same conversion for YAML templates with !Ref, !Sub and !GetAtt tags.
• Terraform to CloudFormation converterGo the other way when a stack has to stay in CloudFormation.
• AWS CDK to Terraform converterConvert CDK source directly instead of its synthesized template.
• Terraform to Pulumi TypeScriptTake the converted HCL one step further if you're heading to Pulumi.
• All AWS code convertersSDK, infrastructure-as-code and IAM policy tools in one place.
• How ChatWithCloud worksAsk questions about your live AWS account in plain English from your terminal.