This page documents the language specification for the random package. If you're looking for help working with the inputs, outputs, or functions of random resources in a Pulumi program, please see the resource documentation for examples and API reference.

Pulumi Random¶

This provider is a derived work of the Terraform Provider distributed under MPL 2.0. If you encounter a bug or missing feature, first check the pulumi/pulumi-random repo; however, if that doesn’t turn up anything, please consult the source terraform-providers/terraform-provider-random repo.

class pulumi_random.Provider(resource_name, opts=None, __props__=None, __name__=None, __opts__=None)¶

The provider type for the random package. By default, resources use package-wide configuration settings, however an explicit Provider instance may be created and passed during resource construction to achieve fine-grained programmatic control over provider settings. See the documentation for more information.

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomId(resource_name, opts=None, byte_length=None, keepers=None, prefix=None, __props__=None, __name__=None, __opts__=None)¶

The resource RandomId generates random numbers that are intended to be used as unique identifiers for other resources.

This resource does use a cryptographic random number generator in order to minimize the chance of collisions, making the results of this resource when a 16-byte identifier is requested of equivalent uniqueness to a type-4 UUID.

This resource can be used in conjunction with resources that have the create_before_destroy lifecycle flag set to avoid conflicts with unique names during the brief period where both the old and new resources exist concurrently.

The following example shows how to generate a unique name for an AWS EC2 instance that changes each time a new AMI id is selected.

import pulumi
import pulumi_aws as aws
import pulumi_random as random

server_random_id = random.RandomId("serverRandomId",
    byte_length=8,
    keepers={
        "ami_id": var["ami_id"],
    })
server_instance = aws.ec2.Instance("serverInstance",
    ami=server_random_id.keepers["amiId"],
    tags={
        "Name": server_random_id.hex.apply(lambda hex: f"web-server {hex}"),
    })

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.
byte_length (pulumi.Input[float]) – The number of random bytes to produce. The minimum value is 1, which produces eight bits of randomness.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
prefix (pulumi.Input[str]) – Arbitrary string to prefix the output value with. This string is supplied as-is, meaning it is not guaranteed to be URL-safe or base64 encoded.

b64_std: pulumi.Output[str] = None¶: The generated id presented in base64 without additional transformations.

b64_url: pulumi.Output[str] = None¶: The generated id presented in base64, using the URL-friendly character set: case-sensitive letters, digits and the characters _ and -.

byte_length: pulumi.Output[float] = None¶: The number of random bytes to produce. The minimum value is 1, which produces eight bits of randomness.

dec: pulumi.Output[str] = None¶: The generated id presented in non-padded decimal digits.

hex: pulumi.Output[str] = None¶: The generated id presented in padded hexadecimal digits. This result will always be twice as long as the requested byte length.

keepers: pulumi.Output[dict] = None¶: Arbitrary map of values that, when changed, will trigger a new id to be generated.

prefix: pulumi.Output[str] = None¶: Arbitrary string to prefix the output value with. This string is supplied as-is, meaning it is not guaranteed to be URL-safe or base64 encoded.

static get(resource_name, id, opts=None, b64=None, b64_std=None, b64_url=None, byte_length=None, dec=None, hex=None, keepers=None, prefix=None)¶

Get an existing RandomId resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.
b64_std (pulumi.Input[str]) – The generated id presented in base64 without additional transformations.
b64*url (pulumi.Input[str]) –
The generated id presented in base64, using the URL-friendly character set: case-sensitive letters, digits and the characters *``and`-`.
byte_length (pulumi.Input[float]) – The number of random bytes to produce. The minimum value is 1, which produces eight bits of randomness.
dec (pulumi.Input[str]) – The generated id presented in non-padded decimal digits.
hex (pulumi.Input[str]) – The generated id presented in padded hexadecimal digits. This result will always be twice as long as the requested byte length.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
prefix (pulumi.Input[str]) – Arbitrary string to prefix the output value with. This string is supplied as-is, meaning it is not guaranteed to be URL-safe or base64 encoded.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomInteger(resource_name, opts=None, keepers=None, max=None, min=None, seed=None, __props__=None, __name__=None, __opts__=None)¶

The resource RandomInteger generates random values from a given range, described by the min and max attributes of a given resource.

This resource can be used in conjunction with resources that have the create_before_destroy lifecycle flag set, to avoid conflicts with unique names during the brief period where both the old and new resources exist concurrently.

The following example shows how to generate a random priority between 1 and 50000 for a aws_alb_listener_rule resource:

import pulumi
import pulumi_aws as aws
import pulumi_random as random

priority = random.RandomInteger("priority",
    keepers={
        "listener_arn": var["listener_arn"],
    },
    max=50000,
    min=1)
main = aws.alb.ListenerRule("main",
    actions=[{
        "target_group_arn": var["target_group_arn"],
        "type": "forward",
    }],
    listener_arn=var["listener_arn"],
    priority=priority.result)

The result of the above will set a random priority.

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
max (pulumi.Input[float]) – The maximum inclusive value of the range.
min (pulumi.Input[float]) – The minimum inclusive value of the range.
seed (pulumi.Input[str]) – A custom seed to always produce the same value.

keepers: pulumi.Output[dict] = None¶: Arbitrary map of values that, when changed, will trigger a new id to be generated.

max: pulumi.Output[float] = None¶: The maximum inclusive value of the range.

min: pulumi.Output[float] = None¶: The minimum inclusive value of the range.

result: pulumi.Output[float] = None¶: (int) The random Integer result.

seed: pulumi.Output[str] = None¶: A custom seed to always produce the same value.

static get(resource_name, id, opts=None, keepers=None, max=None, min=None, result=None, seed=None)¶

Get an existing RandomInteger resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
max (pulumi.Input[float]) – The maximum inclusive value of the range.
min (pulumi.Input[float]) – The minimum inclusive value of the range.
result (pulumi.Input[float]) – (int) The random Integer result.
seed (pulumi.Input[str]) – A custom seed to always produce the same value.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomPassword(resource_name, opts=None, keepers=None, length=None, lower=None, min_lower=None, min_numeric=None, min_special=None, min_upper=None, number=None, override_special=None, special=None, upper=None, __props__=None, __name__=None, __opts__=None)¶

Identical to the RandomString resource with the exception that the result is treated as sensitive and, thus, not displayed in console output.

Note: All attributes including the generated password will be stored in the raw state as plain-text.

This resource does use a cryptographic random number generator.

import pulumi
import pulumi_aws as aws
import pulumi_random as random

password = random.RandomPassword("password",
    length=16,
    special=True,
    override_special="_%@")
example = aws.rds.Instance("example",
    instance_class="db.t3.micro",
    allocated_storage=64,
    engine="mysql",
    username="someone",
    password=random_string["password"]["result"])

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.

static get(resource_name, id, opts=None, keepers=None, length=None, lower=None, min_lower=None, min_numeric=None, min_special=None, min_upper=None, number=None, override_special=None, result=None, special=None, upper=None)¶

Get an existing RandomPassword resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomPet(resource_name, opts=None, keepers=None, length=None, prefix=None, separator=None, __props__=None, __name__=None, __opts__=None)¶

The resource RandomPet generates random pet names that are intended to be used as unique identifiers for other resources.

The following example shows how to generate a unique pet name for an AWS EC2 instance that changes each time a new AMI id is selected.

import pulumi
import pulumi_aws as aws
import pulumi_random as random

server_random_pet = random.RandomPet("serverRandomPet", keepers={
    "ami_id": var["ami_id"],
})
server_instance = aws.ec2.Instance("serverInstance",
    ami=server_random_pet.keepers["amiId"],
    tags={
        "Name": server_random_pet.id.apply(lambda id: f"web-server-{id}"),
    })

The result of the above will set the Name of the AWS Instance to web-server-simple-snake.

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
length (pulumi.Input[float]) – The length (in words) of the pet name.
prefix (pulumi.Input[str]) – A string to prefix the name with.
separator (pulumi.Input[str]) – The character to separate words in the pet name.

keepers: pulumi.Output[dict] = None¶: Arbitrary map of values that, when changed, will trigger a new id to be generated.

length: pulumi.Output[float] = None¶: The length (in words) of the pet name.

prefix: pulumi.Output[str] = None¶: A string to prefix the name with.

separator: pulumi.Output[str] = None¶: The character to separate words in the pet name.

static get(resource_name, id, opts=None, keepers=None, length=None, prefix=None, separator=None)¶

Get an existing RandomPet resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
length (pulumi.Input[float]) – The length (in words) of the pet name.
prefix (pulumi.Input[str]) – A string to prefix the name with.
separator (pulumi.Input[str]) – The character to separate words in the pet name.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomShuffle(resource_name, opts=None, inputs=None, keepers=None, result_count=None, seed=None, __props__=None, __name__=None, __opts__=None)¶

The resource RandomShuffle generates a random permutation of a list of strings given as an argument.

import pulumi
import pulumi_aws as aws
import pulumi_random as random

az = random.RandomShuffle("az",
    inputs=[
        "us-west-1a",
        "us-west-1c",
        "us-west-1d",
        "us-west-1e",
    ],
    result_count=2)
example = aws.elb.LoadBalancer("example", availability_zones=az.results)

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.
inputs (pulumi.Input[list]) – The list of strings to shuffle.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
result_count (pulumi.Input[float]) – The number of results to return. Defaults to the number of items in the input list. If fewer items are requested, some elements will be excluded from the result. If more items are requested, items will be repeated in the result but not more frequently than the number of items in the input list.
seed (pulumi.Input[str]) – Arbitrary string with which to seed the random number generator, in order to produce less-volatile permutations of the list. Important: Even with an identical seed, it is not guaranteed that the same permutation will be produced across different versions of the provider. This argument causes the result to be less volatile, but not fixed for all time.

inputs: pulumi.Output[list] = None¶: The list of strings to shuffle.

keepers: pulumi.Output[dict] = None¶: Arbitrary map of values that, when changed, will trigger a new id to be generated.

result_count: pulumi.Output[float] = None¶: The number of results to return. Defaults to the number of items in the input list. If fewer items are requested, some elements will be excluded from the result. If more items are requested, items will be repeated in the result but not more frequently than the number of items in the input list.

results: pulumi.Output[list] = None¶: Random permutation of the list of strings given in input.

seed: pulumi.Output[str] = None¶: Arbitrary string with which to seed the random number generator, in order to produce less-volatile permutations of the list. Important: Even with an identical seed, it is not guaranteed that the same permutation will be produced across different versions of the provider. This argument causes the result to be less volatile, but not fixed for all time.

static get(resource_name, id, opts=None, inputs=None, keepers=None, result_count=None, results=None, seed=None)¶

Get an existing RandomShuffle resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.
inputs (pulumi.Input[list]) – The list of strings to shuffle.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
result_count (pulumi.Input[float]) – The number of results to return. Defaults to the number of items in the input list. If fewer items are requested, some elements will be excluded from the result. If more items are requested, items will be repeated in the result but not more frequently than the number of items in the input list.
results (pulumi.Input[list]) – Random permutation of the list of strings given in input.
seed (pulumi.Input[str]) – Arbitrary string with which to seed the random number generator, in order to produce less-volatile permutations of the list. Important: Even with an identical seed, it is not guaranteed that the same permutation will be produced across different versions of the provider. This argument causes the result to be less volatile, but not fixed for all time.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomString(resource_name, opts=None, keepers=None, length=None, lower=None, min_lower=None, min_numeric=None, min_special=None, min_upper=None, number=None, override_special=None, special=None, upper=None, __props__=None, __name__=None, __opts__=None)¶

The resource RandomString generates a random permutation of alphanumeric characters and optionally special characters.

This resource does use a cryptographic random number generator.

Historically this resource’s intended usage has been ambiguous as the original example used it in a password. For backwards compatibility it will continue to exist. For unique ids please use the RandomId resource, for sensitive random values please use the RandomPassword resource.

import pulumi
import pulumi_random as random

random = random.RandomString("random",
    length=16,
    override_special="/@£$",
    special=True)

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
length (pulumi.Input[float]) – The length of the string desired
lower (pulumi.Input[bool]) – (default true) Include lowercase alphabet characters in random string.
min_lower (pulumi.Input[float]) – (default 0) Minimum number of lowercase alphabet characters in random string.
min_numeric (pulumi.Input[float]) – (default 0) Minimum number of numeric characters in random string.
min_special (pulumi.Input[float]) – (default 0) Minimum number of special characters in random string.
min_upper (pulumi.Input[float]) – (default 0) Minimum number of uppercase alphabet characters in random string.
number (pulumi.Input[bool]) – (default true) Include numeric characters in random string.
override*special (pulumi.Input[str]) –
Supply your own list of special characters to use for string generation. This overrides the default character list in the special argument. The special argument must still be set to true for any overwritten characters to be used in generation.
special (pulumi.Input[bool]) – (default true) Include special characters in random string. These are !@#$%&*()-*=+[]{}<>:?
upper (pulumi.Input[bool]) – (default true) Include uppercase alphabet characters in random string.

keepers: pulumi.Output[dict] = None¶: Arbitrary map of values that, when changed, will trigger a new id to be generated.

length: pulumi.Output[float] = None¶: The length of the string desired

lower: pulumi.Output[bool] = None¶: (default true) Include lowercase alphabet characters in random string.

min_lower: pulumi.Output[float] = None¶: (default 0) Minimum number of lowercase alphabet characters in random string.

min_numeric: pulumi.Output[float] = None¶: (default 0) Minimum number of numeric characters in random string.

min_special: pulumi.Output[float] = None¶: (default 0) Minimum number of special characters in random string.

min_upper: pulumi.Output[float] = None¶: (default 0) Minimum number of uppercase alphabet characters in random string.

number: pulumi.Output[bool] = None¶: (default true) Include numeric characters in random string.

override_special: pulumi.Output[str] = None¶: Supply your own list of special characters to use for string generation. This overrides the default character list in the special argument. The special argument must still be set to true for any overwritten characters to be used in generation.

result: pulumi.Output[str] = None¶: Random string generated.

special: pulumi.Output[bool] = None¶: (default true) Include special characters in random string. These are !@#$%&*()-_=+[]{}<>:?

upper: pulumi.Output[bool] = None¶: (default true) Include uppercase alphabet characters in random string.

Get an existing RandomString resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new id to be generated.
length (pulumi.Input[float]) – The length of the string desired
lower (pulumi.Input[bool]) – (default true) Include lowercase alphabet characters in random string.
min_lower (pulumi.Input[float]) – (default 0) Minimum number of lowercase alphabet characters in random string.
min_numeric (pulumi.Input[float]) – (default 0) Minimum number of numeric characters in random string.
min_special (pulumi.Input[float]) – (default 0) Minimum number of special characters in random string.
min_upper (pulumi.Input[float]) – (default 0) Minimum number of uppercase alphabet characters in random string.
number (pulumi.Input[bool]) – (default true) Include numeric characters in random string.
override*special (pulumi.Input[str]) –
Supply your own list of special characters to use for string generation. This overrides the default character list in the special argument. The special argument must still be set to true for any overwritten characters to be used in generation.
result (pulumi.Input[str]) – Random string generated.
special (pulumi.Input[bool]) – (default true) Include special characters in random string. These are !@#$%&*()-*=+[]{}<>:?
upper (pulumi.Input[bool]) – (default true) Include uppercase alphabet characters in random string.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

class pulumi_random.RandomUuid(resource_name, opts=None, keepers=None, __props__=None, __name__=None, __opts__=None)¶

The resource RandomUuid generates random uuid string that is intended to be used as unique identifiers for other resources.

This resource uses the hashicorp/go-uuid to generate a UUID-formatted string for use with services needed a unique string identifier.

The following example shows how to generate a unique name for an Azure Resource Group.

import pulumi
import pulumi_azure as azure
import pulumi_random as random

test_random_uuid = random.RandomUuid("testRandomUuid")
test_resource_group = azure.core.ResourceGroup("testResourceGroup", location="Central US")

Parameters

resource_name (str) – The name of the resource.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new uuid to be generated.

keepers: pulumi.Output[dict] = None¶: Arbitrary map of values that, when changed, will trigger a new uuid to be generated.

result: pulumi.Output[str] = None¶: The generated uuid presented in string format.

static get(resource_name, id, opts=None, keepers=None, result=None)¶

Get an existing RandomUuid resource’s state with the given name, id, and optional extra properties used to qualify the lookup.

Parameters

resource_name (str) – The unique name of the resulting resource.
id (str) – The unique provider ID of the resource to lookup.
opts (pulumi.ResourceOptions) – Options for the resource.
keepers (pulumi.Input[dict]) – Arbitrary map of values that, when changed, will trigger a new uuid to be generated.
result (pulumi.Input[str]) – The generated uuid presented in string format.

translate_output_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

translate_input_property(prop)¶

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

Parameters: prop (str) – A property name.
Returns: A potentially transformed property name.
Return type: str

The Pulumi Platform

Get Started

Migrate to Pulumi

Solutions for All Teams and Engineers

Any Code

Any Cloud

Pulumi Random¶

On This Page