How to Use Terraform Toset Function [Examples]

The Terraform toset() function converts a list or tuple into a set, removing duplicate values and discarding their order.

In this article, we will take a look at the type conversion function in Terraform, toset(), explaining what it can be used for, the difference between it and the tolist() function, and some useful examples showing how to use it within a for_each loop.

Terraform toset is a type conversion function. It can be used to convert supplied values to a set, ensuring uniqueness and an unordered nature. The syntax of this function is toset(value), where value is the input value you want to convert to a set.

In Terraform, a set is a collection type that represents an unordered collection of unique values. Sets are used to store and manage distinct elements and are commonly used in scenarios where uniqueness and order are not important. The set data type is useful when you want to ensure that each element in the collection is unique.

What is the difference between toset and tolist?

The toset() function converts a value to a set, that is an unordered collection of unique values, while tolist() converts a value to a list, preserving the order of elements.

A list in Terraform is a collection type that represents an ordered sequence of elements. Lists are used to store and manage a series of values, and the order in which elements are defined in the list is maintained. Elements in a list can be of various types, such as strings, numbers, or other complex data structures.

Read more about other Terraform functions.

In the example below, we have a list we convert into a set.

variable "my_list" {
  type    = list(string)
  default = ["yoda", "luke", "darth", "luke"]
}

locals {
  my_set = toset(var.my_list)
}

output "set_output" {
  value = local.my_set
}

The output would show:

Outputs:

set_output = toset([
  "darth",
  "luke",
  "yoda",
])

Two things happened here. The duplicate "luke" was removed, and the elements came back in alphabetical order rather than the order they were supplied.

You can also use the Terraform console to experiment with Terraform functions. For example, the simple test supplying the values directly to the toset()function on the terraform console shows the same output:

What happens when you pass mixed types to toset?

Since Terraform’s concept of a set requires all of the elements to be of the same type, mixed-typed elements will be converted to the most general type (for example, if strings and numbers are supplied in the list together). Also note that sets cannot contain duplicate values, and any duplicate values supplied are coalesced. Sets are also unordered, so any ordering when supplying the list is also lost.

For example:

Terraform for_each with toset

The for_each construct in Terraform is often used to iterate over a map or a set of values and create multiple instances of a resource or module. If you have a set of values and you want to use for_each in conjunction with toset(), you’ll need to convert your input data to a set.

variable "my_list" {
  type    = list(string)
  default = ["luke", "yoda", "darth"]
}

resource "example_resource" "my_resource" {
  for_each = toset(var.my_list)

  name = each.value
}

output "character_names" {
  value = values(example_resource.my_resource)[*].name
}

On running terraform apply, the output will show:

Outputs:

character_names = [
  "darth",
  "luke",
  "yoda",
]

Because for_each keys the instances by the set’s values, the results come back in alphabetical order.

Does the Terraform toset function preserve order?

The Terraform toset function doesn’t preserve order. A set is unordered, and Terraform displays its elements in sorted order no matter how you supply them: alphabetically for strings, numerically for numbers. Don’t rely on that display order in your logic.

When you need a stable, indexable order, convert the set back to a list and sort it:

locals {
  ordered_names = sort(tolist(toset(var.my_list)))
}

Use sort(tolist(...)) rather than tolist(...) alone, because set-to-list order is not guaranteed across runs.

The most common reason is for_each, which accepts a map or a set of strings but not a plain list. Converting a list of unique names with toset lets you create one resource per value:

variable "bucket_names" {
  type    = list(string)
  default = ["logs", "artifacts", "backups"]
}

resource "aws_s3_bucket" "main" {
  for_each = toset(var.bucket_names)
  bucket   = "myapp-${each.value}"
}

Without the toset call, Terraform rejects the list and the plan fails. toset is also useful for deduplicating values before you iterate over them.

In Terraform, type conversion functions are used to convert values from one data type to another. These functions allow you to handle and manipulate different types of data in your Terraform configurations. The toset() function allows you to convert supplied values to a set (ensuring uniqueness and unordered nature).

Terraform is powerful, but to achieve an end-to-end secure GitOps approach, you need 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: Terraform moved to the BUSL license starting with version 1.6, so version 1.5.x and earlier remains open source under MPL 2.0. OpenTofu is an open-source fork of Terraform, created from version 1.5.6, that expands on Terraform’s existing concepts. It is a viable alternative to HashiCorp’s Terraform.