Terraform Random Provider

The "random" Terraform provider generates random values inside your Terraform or OpenTofu configurations. It's handy when you need a unique or arbitrary value but don't want to hardcode it. A few things people use it for:

• Creating unique names for resources
• Generating random passwords or API keys
• Selecting random elements from a list

There are seven resources that the random provider supports in the Terraform configuration:

• random_id: Generates a random identifier
• random_integer: Produces a random integer within a specified range
• random_string: Creates a random string of characters
• random_password: Generates a random password
• random_shuffle: Randomly shuffles a list of strings
• random_pet: Generates random names
• random_uuid: Randomly generates a UUID

The random values are generated during the plan phase and stay the same across applies, unless you tell them to regenerate with the keepers argument, which we'll get to later.

How Do You Set Up the Random Provider?

Before anything else, you need to declare the provider so you can pull the random resources into the Terraform run:

terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

What Do the Random Provider Resources Look Like in Practice?

Once the provider is set, you can start trying out the resources below:

random_id

The main use case for the random_id resource is to create random resource IDs, such as appending an ID to a name. That keeps your naming convention consistent:

resource "random_id" "bucket_suffix" {
  byte_length = 4
}
 
resource "aws_s3_bucket" "logs" {
  bucket = "app-logs-${random_id.bucket_suffix.hex}"
}

random_integer

The random_integer resource creates a random integer, mostly for testing scenarios and simulations.

resource "random_integer" "port" {
  min = 8000
  max = 8999
}
 
output "test_port" {
  value = random_integer.port.result
}

random_string

The random_string resource generates random strings for input. It's good for unique test values, as long as they're not sensitive. For sensitive values, use the random_password resource below.

resource "random_string" "label" {
  length  = 8
  special = false
  upper   = false
}
 
output "label" {
  value = random_string.label.result # e.g. "k3f9x2qa"
}

random_password

Use random_password to generate random passwords or strings for security-sensitive values. Instead of relying on a person to pick one, it creates strong, unique passwords based on the rules you set:

resource "random_password" "db" {
  length           = 24
  special          = true
  override_special = "!#$%&*()-_=+[]{}<>:?"
  min_upper        = 2
  min_lower        = 2
  min_numeric      = 2
  min_special      = 2
}
 
resource "aws_db_instance" "main" {
  # ...
  password = random_password.db.result
}

The result is marked sensitive, so it's redacted from plan output, but it still lives in state; protect the state file accordingly.

random_shuffle

The random_shuffle resource randomly shuffles a list of inputs. One use is distributing resources across different AZs for high availability:

resource "random_shuffle" "az" {
  input        = ["us-east-1a", "us-east-1b", "us-east-1c"]
  result_count = 2
}
 
resource "aws_subnet" "app" {
  count             = 2
  vpc_id            = aws_vpc.main.id
  cidr_block        = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index)
  availability_zone = random_shuffle.az.result[count.index]
}

random_pet

The random_pet resource generates unique, memorable names for resources so you don't have to come up with them by hand.

resource "random_pet" "server" {
  length    = 2
  separator = "-"
}
 
resource "aws_instance" "web" {
  # ...
  tags = {
    Name = "web-${random_pet.server.id}" # e.g. "web-eager-otter"
  }
}

random_uuid

The random_uuid resource needs nothing besides the resource block itself. It calls go-uuid to generate the UUID:

resource "random_uuid" "correlation" {}
 
output "correlation_id" {
  value = random_uuid.correlation.result
}

How Do Keepers Control When a Random Value Regenerates?

By design, the values from the random provider stay the same on every new Terraform plan and apply, unless a "keeper" in the config file says otherwise. A keeper references an attribute in your Terraform code, and if that attribute changes, the random value changes with it. That makes the random resource behave predictably. For example, you might want an ec2 instance name to stay the same unless the AMI, instance type, or environment type changes:

resource "random_pet" "instance_name" {
  length = 2
 
  keepers = {
    ami           = var.ami_id
    instance_type = var.instance_type
    environment   = var.environment
  }
}
 
resource "aws_instance" "app" {
  ami           = random_pet.instance_name.keepers.ami
  instance_type = random_pet.instance_name.keepers.instance_type
 
  tags = {
    Name = "app-${random_pet.instance_name.id}"
  }
}

Change any of the three variables and the pet name is regenerated on the next plan; leave them alone and it stays put through every apply.

When Should You Use the Terraform Random Provider?

The random Terraform provider is useful whenever you need generated values for testing and simulation, with the rules defined in code instead of left to a person. Once you've tried the basic resources, spend some time on the keepers argument. It's the piece that decides when a random value stays put and when it regenerates, and that behavior is easy to get wrong if you skip it. If providers are new to you in general, start with getting started with Terraform providers.