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: Randomly generate 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. This will allow you to keep a consistent naming convention:

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

random_integer

The main use case for the random_integer resource is to create a random integer for testing scenarios and simulations.

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

random_string

The main use case for the random_string resource is to generate 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

The main use case for random_password is to generate random passwords or strings to improve security. Instead of relying on a human, this resource 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 main use case for random_shuffle is to randomly shuffle a list of inputs. A use case for this 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 main use case for this is to provide an easy way to generate unique, memorable names for resources without having to come up with them manually.

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

Nothing else is needed besides the resource when using random_UUID, as 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. The point is to make 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.