terraform/website/docs/configuration/functions/uuidv5.html.md

2.9 KiB

layout page_title sidebar_current description
functions uuidv5 - Functions - Configuration Language docs-funcs-crypto-uuidv5 The uuidv5 function generates a uuid v5 string representation of the value in the specified namespace.

uuidv5 Function

-> Note: This page is about Terraform 0.12 and later. For Terraform 0.11 and earlier, see 0.11 Configuration Language: Interpolation Syntax.

uuidv5 generates a name-based UUID, as described in RFC 4122 section 4.3, also known as a "version 5" UUID.

uuidv5(namespace, name)

Unlike the pseudo-random UUIDs generated by uuid, name-based UUIDs derive from namespace and an name, producing the same UUID value every time if the namespace and name are unchanged.

Name-based UUID namespaces are themselves UUIDs, but for readability this function accepts some keywords as aliases for the namespaces that were assigned by RFC 4122:

Keyword Namespace ID Name format
"dns" 6ba7b810-9dad-11d1-80b4-00c04fd430c8 A fully-qualified DNS domain name.
"url" 6ba7b811-9dad-11d1-80b4-00c04fd430c8 Any valid URL as defined in RFC 3986.
"oid" 6ba7b812-9dad-11d1-80b4-00c04fd430c8 An ISO/IEC object identifier
"x500" 6ba7b814-9dad-11d1-80b4-00c04fd430c8 X.500 Distinguished Name

To use any other namespace not included in the above table, pass its assigned namespace ID directly in the first argument in the usual UUID string format.

Examples

Use the namespace keywords where possible, to make the intent more obvious to a future reader:

> uuidv5("dns", "www.terraform.io")
a5008fae-b28c-5ba5-96cd-82b4c53552d6

> uuidv5("url", "https://www.terraform.io/")
9db6f67c-dd95-5ea0-aa5b-e70e5c5f7cf5

> uuidv5("oid", "1.3.6.1.4")
af9d40a5-7a36-5c07-b23a-851cd99fbfa5

> uuidv5("x500", "CN=Example,C=GB")
84e09961-4aa4-57f8-95b7-03edb1073253

The namespace keywords treated as equivalent to their corresponding namespace UUIDs, and in some special cases it may be more appropriate to use the UUID form:

> uuidv5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "www.terraform.io")
a5008fae-b28c-5ba5-96cd-82b4c53552d6

If you wish to use a namespace defined outside of RFC 4122, using the namespace UUID is required because no corresponding keyword is available:

> uuidv5("743ac3c0-3bf7-4a5b-9e6c-59360447c757", "LIBS:diskfont.library")
ede1a974-df7e-5f17-84b9-76208818b2c8

When using raw UUID namespaces, consider including a comment alongside the expression that indicates which namespace this repressents in a human-significant manner, such as by reference to the standard that defined it.

  • uuid, which generates pseudorandom UUIDs.