terraform/website/docs/language/functions/one.html.md

layout	page_title	sidebar_current	description
language	one - Functions - Configuration Language	docs-funcs-collection-one	The 'one' function transforms a list with either zero or one elements into either a null value or the value of the first element.

one Function

-> Note: This function is available only in Terraform v0.15 and later.

one takes a list, set, or tuple value with either zero or one elements. If the collection is empty, one returns null. Otherwise, one returns the first element. If there are two or more elements then one will return an error.

This is a specialized function intended for the common situation where a conditional item is represented as either a zero- or one-element list, where a module author wishes to return a single value that might be null instead.

For example:

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

resource "aws_instance" "example" {
  count = var.include_ec2_instance ? 1 : 0

  # (other resource arguments...)
}

output "instance_ip_address" {
  value = one(aws_instance.example[*].private_ip)
}

Because the aws_instance resource above has the count argument set to a conditional that returns either zero or one, the value of aws_instance.example is a list of either zero or one elements. The instance_ip_address output value uses the one function as a concise way to return either the private IP address of a single instance, or null if no instances were created.

Relationship to the "Splat" Operator

The Terraform language has a built-in operator [*], known as the splat operator, and one if its functions is to translate a primitive value that might be null into a list of either zero or one elements:

variable "ec2_instance_type" {
  description = "The type of instance to create. If set to null, no instance will be created."

  type    = string
  default = null
}

resource "aws_instance" "example" {
  count = length(var.ec2_instance_type[*])

  instance_type = var.ec2_instance_type
  # (other resource arguments...)
}

output "instance_ip_address" {
  value = one(aws_instance.example[*].private_ip)
}

In this case we can see that the one function is, in a sense, the opposite of applying [*] to a primitive-typed value. Splat can convert a possibly-null value into a zero-or-one list, and one can reverse that to return to a primitive value that might be null.

Examples

> one([])
null
> one(["hello"])
"hello"
> one(["hello", "goodbye"])

Error: Invalid function argument

Invalid value for "list" parameter: must be a list, set, or tuple value with
either zero or one elements.

Using one with sets

The one function can be particularly helpful in situations where you have a set that you know has only zero or one elements. Set values don't support indexing, so it's not valid to write var.set[0] to extract the "first" element of a set, but if you know that there's only one item then one can isolate and return that single item:

> one(toset([]))
null
> one(toset(["hello"]))
"hello"

Don't use one with sets that might have more than one element. This function will fail in that case:

> one(toset(["hello","goodbye"]))

Error: Invalid function argument

Invalid value for "list" parameter: must be a list, set, or tuple value with
either zero or one elements.