Terraform Append to List with Concat Examples

Appending to a list in Terraform is a common task when building flexible and reusable infrastructure configurations. Since Terraform treats data structures as immutable, lists cannot be updated directly. Instead, you create a new list that includes the existing elements along with the additional values you want to add. 

In this article, we’ll cover how to append to a list in Terraform using the concat() function in a few common patterns.

In Terraform, you append to a list by creating a new list that includes the existing elements plus the new ones. Terraform uses immutable data structures, which means you do not modify a list in place. Instead you usually build a new list using the concat() function.

1. Using the concat function

The concat() function merges two or more lists into a new list. This is the most explicit and readable method and works well when the existing value may come from a variable or module output.

variable "base_list" {
  default = ["a", "b"]
}

locals {
  extended_list = concat(var.base_list, ["c"])
}

Terraform evaluates this into ["a", "b", "c"]. You can keep adding more items by extending the second list.

2. Using conditional append with concat

Terraform also allows you to append values only when a condition is true by first building a small list of extra items and then merging it with your base list using concat(). This keeps the configuration simple and avoids modifying the original list.

For example, you can control whether to append an item based on a boolean variable:

variable "base_list" {
default = ["a", "b"]
}

variable "include_c" {
type = bool
default = true
}

locals {
extra_items = var.include_c ? ["c"] : []
extended_list = concat(var.base_list, local.extra_items)
}

If include_c is true, extended_list becomes ["a", "b", "c"]. If it is false, extended_list stays ["a", "b"].

3. Appending inside a resource or module input

When passing a list into a resource, you can append additional values without modifying the original variable. This is helpful when you have defaults but want to add environment specific items.

variable "security_groups" {
  default = ["sg-base-1", "sg-base-2"]
}

resource "aws_instance" "web" {
  ami           = "ami-123"
  instance_type = "t3.micro"

  vpc_security_group_ids = concat(
    var.security_groups,
    ["sg-extra"]
  )
}

Terraform takes the original list and outputs a new one containing the extra item. The original var.security_groups value remains unchanged. This pattern is common when combining defaults with dynamic configuration.

In this example, we’ll start with a base list of names. We then create a new list that contains everything from the original list plus an additional value. 

Terraform does not modify the original list. Instead, it builds a fresh one that merges both lists. This is the most common and readable pattern for appending items during configuration.

variable "names" {
  default = ["anna", "john"]
}

locals {
  all_names = concat(var.names, ["maria"])
}

output "result" {
  value = local.all_names
}

Running this will return ["anna", "john", "maria"] as the final list.

Appending to a list in Terraform becomes simple once you understand that Terraform relies on immutable values. By using functions like concat(), you can create new lists that incorporate both your existing data and the new elements you need.

Terraform is really powerful, but to achieve an end-to-end secure GitOps approach, you need to use a product that can run your Terraform workflows. Spacelift takes managing Terraform to the next level by giving you access to a powerful CI/CD workflow and unlocking features such as:

• Policies (based on Open Policy Agent)
• Multi-IaC workflows
• Self-service infrastructure
• Integrations with any third-party tools

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.