• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Language

  • Overview
  • Attributes as Blocks - Configuration Language
  • Terraform v1.0 Compatibility Promises
    • Overview
    • Override Files
    • Dependency Lock File
    • Overview
    • Configuration Syntax
    • JSON Configuration Syntax
    • Style Conventions
    • Overview
    • Resource Blocks
    • Resource Behavior
      • depends_on
      • count
      • for_each
      • provider
      • lifecycle
      • Declaring Provisioners
      • Provisioner Connections
      • Provisioners Without a Resource
      • file
      • local-exec
      • remote-exec

      • chef
      • habitat
      • puppet
      • salt-masterless
  • Data Sources
    • count
    • depends_on
    • for_each
    • lifecycle
    • providers
    • provider
    • Overview
    • Provider Configuration
    • Provider Requirements
    • Dependency Lock File
    • Overview
    • Input Variables
    • Output Values
    • Local Values
    • Overview
    • Module Blocks
    • Module Sources
      • providers
      • depends_on
      • count
      • for_each
      • Overview
      • Standard Module Structure
      • Providers Within Modules
      • Best Practices: Module Composition
      • Publishing Modules
      • Refactoring Modules
    • Module Testing Experiment
    • Overview
    • Types and Values
    • Strings and Templates
    • References to Values
    • Operators
    • Function Calls
    • Conditional Expressions
    • For Expressions
    • Splat Expressions
    • Dynamic Blocks
    • Custom Condition Checks
    • Type Constraints
    • Version Constraints
    • Overview
      • abs
      • ceil
      • floor
      • log
      • max
      • min
      • parseint
      • pow
      • signum
      • chomp
      • format
      • formatlist
      • indent
      • join
      • lower
      • regex
      • regexall
      • replace
      • split
      • strrev
      • substr
      • title
      • trim
      • trimprefix
      • trimsuffix
      • trimspace
      • upper
      • alltrue
      • anytrue
      • chunklist
      • coalesce
      • coalescelist
      • compact
      • concat
      • contains
      • distinct
      • element
      • flatten
      • index
      • keys
      • length
      • list
      • lookup
      • map
      • matchkeys
      • merge
      • one
      • range
      • reverse
      • setintersection
      • setproduct
      • setsubtract
      • setunion
      • slice
      • sort
      • sum
      • transpose
      • values
      • zipmap
      • base64decode
      • base64encode
      • base64gzip
      • csvdecode
      • jsondecode
      • jsonencode
      • textdecodebase64
      • textencodebase64
      • urlencode
      • yamldecode
      • yamlencode
      • abspath
      • dirname
      • pathexpand
      • basename
      • file
      • fileexists
      • fileset
      • filebase64
      • templatefile
      • formatdate
      • timeadd
      • timestamp
      • base64sha256
      • base64sha512
      • bcrypt
      • filebase64sha256
      • filebase64sha512
      • filemd5
      • filesha1
      • filesha256
      • filesha512
      • md5
      • rsadecrypt
      • sha1
      • sha256
      • sha512
      • uuid
      • uuidv5
      • cidrhost
      • cidrnetmask
      • cidrsubnet
      • cidrsubnets
      • can
      • defaults
      • nonsensitive
      • sensitive
      • tobool
      • tolist
      • tomap
      • tonumber
      • toset
      • tostring
      • try
      • type
    • abs
    • abspath
    • alltrue
    • anytrue
    • base64decode
    • base64encode
    • base64gzip
    • base64sha256
    • base64sha512
    • basename
    • bcrypt
    • can
    • ceil
    • chomp
    • chunklist
    • cidrhost
    • cidrnetmask
    • cidrsubnet
    • cidrsubnets
    • coalesce
    • coalescelist
    • compact
    • concat
    • contains
    • csvdecode
    • defaults
    • dirname
    • distinct
    • element
    • file
    • filebase64
    • filebase64sha256
    • filebase64sha512
    • fileexists
    • filemd5
    • fileset
    • filesha1
    • filesha256
    • filesha512
    • flatten
    • floor
    • format
    • formatdate
    • formatlist
    • indent
    • index
    • join
    • jsondecode
    • jsonencode
    • keys
    • length
    • list
    • log
    • lookup
    • lower
    • map
    • matchkeys
    • max
    • md5
    • merge
    • min
    • nonsensitive
    • one
    • parseint
    • pathexpand
    • pow
    • range
    • regex
    • regexall
    • replace
    • reverse
    • rsadecrypt
    • sensitive
    • setintersection
    • setproduct
    • setsubtract
    • setunion
    • sha1
    • sha256
    • sha512
    • signum
    • slice
    • sort
    • split
    • strrev
    • substr
    • sum
    • templatefile
    • textdecodebase64
    • textencodebase64
    • timeadd
    • timestamp
    • title
    • tobool
    • tolist
    • tomap
    • tonumber
    • toset
    • tostring
    • transpose
    • trim
    • trimprefix
    • trimspace
    • trimsuffix
    • try
    • type
    • upper
    • urlencode
    • uuid
    • uuidv5
    • values
    • yamldecode
    • yamlencode
    • zipmap
    • Overview
    • Terraform Cloud
      • Backend Configuration
        • local
        • remote
        • artifactory
        • azurerm
        • consul
        • cos
        • etcd
        • etcdv3
        • gcs
        • http
        • Kubernetes
        • manta
        • oss
        • pg
        • s3
        • swift
      • local
      • remote
      • artifactory
      • azurerm
      • consul
      • cos
      • etcd
      • etcdv3
      • gcs
      • http
      • Kubernetes
      • manta
      • oss
      • pg
      • s3
      • swift
    • Overview
    • Purpose
    • The terraform_remote_state Data Source
    • Backends: State Storage and Locking
    • Import Existing Resources
    • Locking
    • Workspaces
    • Remote State
    • Sensitive Data
    • Overview
    • Upgrading to Terraform v1.2
    • Upgrading to Terraform v1.1
    • Upgrading to Terraform v1.0
    • v1.0 Compatibility Promises
    • Upgrading to Terraform v0.15
    • Upgrading to Terraform v0.14
    • Upgrading to Terraform v0.13
    • Upgrading to Terraform v0.12
    • Upgrading to Terraform v0.11
    • Upgrading to Terraform v0.10
    • Upgrading to Terraform v0.9
    • Upgrading to Terraform v0.8
    • Upgrading to Terraform v0.7
    • Overview
    • Load Order and Semantics
    • Configuration Syntax
    • Interpolation Syntax
    • Overrides
    • Resources
    • Data Sources
    • Providers
    • Variables
    • Outputs
    • Local Values
    • Modules
    • Terraform
    • Provisioners
    • Providers
    • Terraform Push (deprecated)
    • Environment Variables

  • Terraform Internals

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»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)
}
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 of 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)
}
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.
> 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"
> 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.
> 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.
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager