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

ScenarioUseReason
Resource name suffixrandom_uuidPersists in state, no churn
Log/output annotationuuid()Unique per run, not stored
Deploy markerrandom_uuid with keepersChanges only when keepers change
Taggingrandom_uuidStable across applies
Deterministic cross-stack IDExternal v5Same 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.