The uuid() function
Terraform and OpenTofu include a built-in uuid() function that generates a UUID v4:
locals {
request_id = uuid()
}
output "request_id" {
value = local.request_id
}
Important: uuid() generates a new value on every evaluation — every plan and apply. This means if you use uuid() directly in a resource argument, Terraform will see a change on every run and want to update or recreate the resource. This is rarely what you want.
The random_uuid resource
For UUIDs that should persist across applies, use the random_uuid resource from the random provider:
resource "random_uuid" "bucket_suffix" {}
resource "aws_s3_bucket" "data" {
bucket = "my-app-data-${random_uuid.bucket_suffix.result}"
}
The UUID is generated once and stored in Terraform state. Subsequent plan and apply runs use the stored value — no resource churn.
Common patterns
Unique resource naming
resource "random_uuid" "db_name" {}
resource "aws_db_instance" "main" {
identifier = "prod-db-${substr(random_uuid.db_name.result, 0, 8)}"
# ...
}
Using substr to take the first 8 characters keeps names readable while maintaining sufficient uniqueness for most environments.
Idempotent deployments
resource "random_uuid" "deploy_id" {
keepers = {
ami_id = var.ami_id
}
}
The keepers argument forces regeneration when a specific input changes — in this case, a new deploy ID is generated only when the AMI changes. See Idempotency key for the broader pattern.
Namespace-based deterministic IDs with external data
# Generate a deterministic UUID v5 from a namespace and name
data "external" "uuid_v5" {
program = ["python3", "-c", "import uuid, json; print(json.dumps({'result': str(uuid.uuid5(uuid.NAMESPACE_DNS, '${var.service_name}.example.com'))}))"]
}
output "service_uuid" {
value = data.external.uuid_v5.result["result"]
}
This produces the same UUID v5 for the same input — useful for cross-stack references where resources need stable, predictable identifiers. See Name-based UUID.
When to use uuid() vs random_uuid
| Scenario | Use | Reason |
|---|---|---|
| Resource name suffix | random_uuid | Persists in state, no churn |
| Log/output annotation | uuid() | Unique per run, not stored |
| Deploy marker | random_uuid with keepers | Changes only when keepers change |
| Tagging | random_uuid | Stable across applies |
| Deterministic cross-stack ID | External v5 | Same input always produces same UUID |
OpenTofu compatibility
OpenTofu supports both uuid() and the random_uuid resource with identical behaviour to Terraform. The random provider works without modification.
Frequently asked questions
Does Terraform's uuid() function change on every plan?
Yes. uuid() generates a new value on every terraform plan and terraform apply. If you use it directly in a resource argument, Terraform sees the value as changed and wants to recreate or update the resource. Use random_uuid instead for values that should persist across applies.
What is the difference between uuid() and random_uuid in Terraform?
uuid() is a built-in function that generates a new UUID v4 every time it is evaluated — it is not stored in state. random_uuid is a resource from the random provider that generates a UUID once and stores it in Terraform state, keeping the same value across subsequent plans and applies.
Can I generate UUID v7 in Terraform?
Not natively. Terraform's uuid() generates v4 only. For v7, you would need to use an external data source or a local-exec provisioner calling a script. In most Terraform use cases (resource naming, unique suffixes), v4 is sufficient because chronological ordering is not needed.