Terraform manages infrastructure state — every resource has a stable identity across plan/apply cycles. UUIDs appear in several Terraform contexts: as generated random identifiers for resources that need unique names, as deterministic identifiers derived from infrastructure parameters, and as tags applied to cloud resources for cost attribution and access control. This page covers the HashiCorp random provider’s random_uuid resource, the built-in uuidv5() function, and patterns for stable cross-environment UUID assignment.
The random_uuid resource
terraform {
required_providers {
random = {
source = "hashicorp/random"
version = "~> 3.6"
}
}
}
resource "random_uuid" "app_id" {}
resource "aws_s3_bucket" "data" {
bucket = "myapp-${random_uuid.app_id.result}"
tags = {
AppId = random_uuid.app_id.result
Environment = var.environment
}
}
output "app_id" {
value = random_uuid.app_id.result
}
The UUID is generated once and stored in terraform.tfstate. Subsequent terraform apply runs reuse the same value. Destroying and recreating the random_uuid resource generates a new UUID — use lifecycle { prevent_destroy = true } to prevent accidental regeneration.
The HashiCorp random provider documentation covers all random resource types including random_id, random_string, and random_uuid.
Deterministic UUIDs with uuidv5()
The uuidv5() built-in function creates reproducible UUIDs from a namespace and name — the same inputs always produce the same output, with no state required:
locals {
# Deterministic UUID for each environment — same value across team members
env_id = uuidv5("dns", "${var.app_name}.${var.environment}.internal")
# e.g. "a1b2c3d4-e5f6-5000-8789-0a1b2c3d4e5f"
}
resource "azurerm_resource_group" "main" {
name = "rg-${var.app_name}-${var.environment}"
location = var.region
tags = {
EnvironmentId = local.env_id # Stable across all team members' plans
}
}
uuidv5() uses the SHA-1 hash-based algorithm defined in RFC 9562 §5.5. It is deterministic: two Terraform configurations with the same var.app_name and var.environment will compute the same UUID without coordination. The Terraform uuidv5() documentation covers the four built-in namespace values.
UUID tagging strategy for cloud resources
A consistent UUID tagging strategy enables cross-service cost attribution and IAM policy scoping:
locals {
# One UUID per logical application, shared across all its resources
app_uuid = uuidv5("url", "https://myapp.example.com")
common_tags = {
AppUuid = local.app_uuid
Environment = var.environment
ManagedBy = "terraform"
}
}
resource "google_compute_instance" "web" {
name = "web-${var.environment}"
machine_type = "e2-medium"
zone = var.zone
labels = local.common_tags
}
resource "google_storage_bucket" "assets" {
name = "assets-${local.app_uuid}"
labels = local.common_tags
}
Using uuidv5("url", ...) with the canonical application URL produces a stable, globally unique identifier for the application that does not change between environments or deployments. The Terraform lifecycle documentation covers ignore_changes for tags that are managed externally.
Passing UUID v7 into Terraform from external systems
When application databases generate UUID v7 primary keys, those IDs sometimes need to be passed into Terraform for resource configuration (e.g. setting a fixed resource ID for a managed service):
variable "service_uuid" {
description = "UUID v7 generated by the application bootstrap script"
type = string
validation {
condition = can(regex("^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", var.service_uuid))
error_message = "service_uuid must be a valid UUID v7 string."
}
}
The regex validates the 8-4-4-4-12 format with a 7 version nibble and an 8, 9, a, or b variant nibble — matching the structure defined in RFC 9562.
Terraform Cloud workspace UUIDs
Terraform Cloud and HCP Terraform assign a UUID to every workspace, run, and state version. These UUIDs appear in API responses and can be used to correlate Terraform runs with application deployments. Use the HCP Terraform API documentation to retrieve workspace UUIDs programmatically for CI/CD pipeline integration.
Further reading
- UUID Namespaces — how UUID v5 namespace hashing works
- UUID v5 Deterministic — deterministic UUID generation
- UUID Generation Strategies — where to generate IDs
External references
- Terraform random_uuid resource
- Terraform uuidv5() function
- HashiCorp random provider
- RFC 9562 — UUID standard
- Terraform lifecycle documentation
Frequently asked questions
How do I generate a UUID in Terraform?
Use the random_uuid resource from the HashiCorp random provider: declare resource "random_uuid" "app_id" {} and reference it as random_uuid.app_id.result. The generated UUID is stored in Terraform state and remains stable across subsequent plan and apply cycles — it only regenerates if the resource is destroyed and recreated. The random provider generates UUID v4 values (122 bits of randomness per RFC 9562).
How do I create deterministic UUIDs in Terraform for repeatable infrastructure?
Use the uuidv5() Terraform built-in function, which generates a UUID v5 by hashing a namespace UUID and a name string with SHA-1. Example: uuidv5("dns", "myapp.example.com") always produces the same UUID for the same input. This is useful for creating stable resource identifiers that can be computed from known inputs without storing state. The Terraform uuidv5() function documentation lists the built-in namespace constants ("dns", "url", "oid", "x500").
Does Terraform support UUID v7 generation?
Not natively as of 2026. The random_uuid resource generates UUID v4. For UUID v7, use an external data source that calls a script generating a v7 value, or generate UUID v7 outside Terraform and pass it as a variable. The Terraform external data source documentation covers shell-script integration. UUID v5 (uuidv5()) is the idiomatic Terraform choice when you need deterministic, reproducible identifiers.