Using Terraform YAML Functions: Yamldecode & Yamlencode

YAML is everywhere in modern infrastructure. Kubernetes manifests, Helm values, Ansible playbooks, and CI/CD pipelines all rely on it. So when your Terraform configuration needs to read from or write to YAML, you need to know how to bridge the two.

Terraform provides two built-in functions for this: yamldecode, which parses a YAML string into a Terraform data structure, and yamlencode, which does the reverse. In this guide, we’ll cover how both functions work, how they map Terraform types to YAML, and walk through practical examples of each.

What we will cover:

1. What is YAML?
2. Can YAML be used in Terraform?
3. What is the yamldecode function in Terraform?
4. Examples – Using Terraform yamldecode function
5. What is the yamlencode function in Terraform?
6. How to generate YAML from a Terraform template file
7. Examples – Using Terraform yamlencode function

YAML (YAML Ain’t Markup Language) is a human-readable data serialization format. It stands out for its simplicity and readability, making it popular for configuration files, data exchange between programming languages, and other similar use cases. YAML has a minimalistic syntax compared to other data serialization formats like JSON or XML. Despite its simplicity, YAML can represent complex data structures and relationships.

YAML is often used in contexts where data needs to be structured hierarchically, such as configuration files for software applications, data storage, and communication protocols, and is specifically more common in infrastructure configuration files for Docker, Kubernetes, Ansible, and APIs.

It uses indentation to represent nesting, similar to the way Python does. YAML is designed to be language-agnostic, meaning it can be used with virtually any programming language. Its human-readable nature and ease of use have contributed to its widespread adoption in the software development community.

Terraform primarily uses its own declarative language called HashiCorp Configuration Language (HCL) for defining infrastructure as code. Configuration files cannot be written in YAML directly.

Terraform has yamlencode and yamldecode functions available, which allow you to convert values between Terraform and YAML format. These functions are the main focus of this article.

Alternatively, Terraform does support JSON as an alternative input format, and YAML files can be converted to JSON. There are various tools and libraries available for converting YAML to JSON in different programming languages. For example, you can use Python with libraries like pyyaml or ruamel.yaml to parse YAML and then output JSON.

The yamldecode is a Terraform function used to parse a string formatted in a subset of YAML 1.2 and convert it into a Terraform data structure. It allows you to decode YAML data into Terraform’s data types, such as strings, numbers, booleans, lists, maps, etc.

Below is a simple example of using the yamldecode() function:

> yamldecode("hello: world")
{
 "hello" = "world"
}

How yamldecode maps Terraform types to YAML?

yamldecode supports a limited set of YAML features to ensure compatibility with Terraform’s data types. Terraform automatically converts the parsed YAML data to the most appropriate Terraform type (e.g., string, number, list, or object). 

Note that the function doesn’t support the full YAML specification. For instance, it cannot handle cyclic data structures or tags beyond a specific set. Because of these limitations, using yamldecode followed by yamlencode (which encodes Terraform data back to YAML) might not produce an identical YAML output so be sure to test whilst implementing your code.

Basic YAML types

• String — Plain strings in YAML directly map to Terraform strings.
• Number — Integers and floating-point numbers in YAML become Terraform numbers.
• Boolean — true and false in YAML translate to Terraform booleans.
• Lists — YAML lists become Terraform lists. The elements within the list will be converted based on their individual data types.
• Maps (Objects) — YAML maps (represented by key-value pairs) are converted to Terraform maps. Keys in YAML maps must be strings, which become the keys in the Terraform map. Values in the map are converted based on their data type in YAML.

Let’s take a look at some practical examples of retrieving values from YAML files using the yamldecode function in Terraform

1. Getting the API key from a YAML file

In the first example, we have a config.yaml file containing an API key that we want Terraform to be able to read. It is then exposed using a Terraform output block.

# config.yaml
# api_key: "your_api_key_here"

# main.tf
locals {
  config  = yamldecode(file("${path.module}/config.yaml"))
  api_key = local.config["api_key"]
}

output "api_key_preview" {
  value     = local.api_key
  sensitive = true
}

2. Accessing nested data in a YAML file

Taking this a step further, the next example shows how to access nested data within the YAML configuration.

# server_config.yaml
# servers:
#   web:
#     host: "webserver.example.com"
#     port: 80
#   api:
#     host: "api.example.com"
#     port: 443

# main.tf
locals {
  server_config = yamldecode(file("${path.module}/server_config.yaml"))
  web_host      = local.server_config["servers"]["web"]["host"]
  web_port      = local.server_config["servers"]["web"]["port"]
  api_host      = local.server_config["servers"]["api"]["host"]
  api_port      = local.server_config["servers"]["api"]["port"]
}

output "web_endpoint" {
  value = "${local.web_host}:${local.web_port}"
}

output "api_endpoint" {
  value = "${local.api_host}:${local.api_port}"
}

3. Handling list of objects defined in a YAML file

The next example shows how to handle a list of objects that might be defined in your YAML file. 

A for_each meta-argument iterates through the security_groups list to create one resource per entry. Each element’s properties (name and description) are accessed using each.value. Alternatively, a for expression in an output block can collect just the names into a list.

# security_groups.yaml
# security_groups:
#   - name: "web-server-sg"
#     description: "Security group for web server instances"
#   - name: "database-sg"
#     description: "Security group for database instances"

# main.tf
locals {
  sg_config       = yamldecode(file("${path.module}/security_groups.yaml"))
  security_groups = local.sg_config["security_groups"]
}

# Use for_each to create a real resource per entry
resource "aws_security_group" "this" {
  for_each    = { for sg in local.security_groups : sg["name"] => sg }
  name        = each.value["name"]
  description = each.value["description"]
}

# Or simply output the parsed list
output "security_group_names" {
  value = [for sg in local.security_groups : sg["name"]]
}

The opposite of yamldecode, the yamlencode function takes a Terraform value (such as a map or a list) and returns a string representing the YAML-encoded version of that value. This string can then be used within your Terraform configuration to generate YAML files.

• Input: It accepts any valid Terraform data type (strings, numbers, booleans, lists, or maps).
• Output: It returns a string representing the data in YAML format.

If you have a Terraform template file with placeholders for dynamic values, you can use the templatefile function to render the template with actual data and then use yamlencode to convert the rendered content into a YAML string.

Here’s a breakdown of the steps:

Template File: 

1. Create a file (e.g., config.tmpl) with placeholders for your desired configuration values. 
2. Use template interpolation syntax (${variable_name}) for the placeholders, where variable_name matches the keys you pass in the second argument of templatefile().

Terraform Code:

1. Define variables for the dynamic values you want to inject into the template.
2. Use the templatefile function to read the template and replace placeholders with actual values:

In this example, the local_file resource writes the generated YAML string (local.yaml_config) to a file named config.yaml.

# config.tmpl
# name: "${name}"
# environment: "${environment}"

# variables.tf
variable "config_name" {
  type = string
}

variable "environment" {
  type = string
}

# main.tf
locals {
  template_content = templatefile("${path.module}/config.tmpl", {
    name        = var.config_name
    environment = var.environment
  })
}

# Write it to a file using the local_file resource (no anti-pattern local-exec needed)
resource "local_file" "config_yaml" {
  content  = local.template_content
  filename = "${path.module}/output/config.yaml"
}

Now, we’ll show some practical examples for using the yamlencode function in Terraform.

1. Generating a simple YAML configuration with dynamic values

This example demonstrates how to generate a simple YAML configuration with dynamic values from Terraform variables. The yamlencode function takes a map as input, where keys become YAML keys, and values are converted to their corresponding YAML representation.

variable "app_name" {
  type = string
}

variable "server_port" {
  type = number
}

locals {
  yaml_config = yamlencode({
    name = var.app_name
    port = var.server_port
  })
}

resource "local_file" "app_config" {
  content  = local.yaml_config
  filename = "${path.module}/output/config.yaml"
}

output "yaml_preview" {
  value = local.yaml_config
}

2. Creating a YAML configuration for a user with SSH keys

In this example, we create a YAML configuration for a user with SSH keys. The ssh_keys variable is a list of strings, which gets converted to a YAML list during encoding.

variable "user_name" {
  type = string
}

variable "ssh_keys" {
  type = list(string)
}

locals {
  user_config = yamlencode({
    username = var.user_name
    ssh_keys = var.ssh_keys
  })
}

resource "local_file" "user_config" {
  content  = local.user_config
  filename = "${path.module}/output/user_config.yaml"
}

3. Handling nested data structures in Terraform

This example shows how to handle nested data structures in Terraform. The web_servers variable holds a list of objects, each representing a web server with its host and port. yamlencode recursively encodes this nested structure into the corresponding YAML format.

variable "web_servers" {
  type = list(object({
    host = string
    port = number
  }))
}

locals {
  server_config = yamlencode({
    servers = var.web_servers
  })
}

resource "local_file" "server_config" {
  content  = local.server_config
  filename = "${path.module}/output/servers.yaml"
}

output "server_config_yaml" {
  value = local.server_config
}

To read and output YAML in your Terraform configurations, you can use the built-in functions yamlencode and yamldecode

yamldecode parses a string as a subset of YAML, and produces a representation of its value.yamlencode performs the opposite operation, encoding a given value to a string using YAML 1.2 block syntax.

Terraform is really powerful, but managing imports, state, and configuration at scale requires more than the CLI alone. Spacelift takes Terraform management to the next level by giving you access to a powerful CI/CD workflow and features such as:

• Policy as code (based on Open Policy Agent) to enforce guardrails on every plan and apply
• Drift detection to catch resources that have changed outside of Terraform
• Multi-IaC workflows across Terraform, OpenTofu, CloudFormation, Pulumi, and Kubernetes
• Self-service infrastructure through Blueprints and Templates
• Full audit trails so you always know what changed, when, and who approved it

If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.

Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.