Skip to content

Commit feafc94

Browse files
apparentlymartapparentlymart
committed
website: docs for the "random" provider
1 parent eec6c88 commit feafc94

6 files changed

Lines changed: 235 additions & 0 deletions

File tree

‎website/source/assets/stylesheets/_docs.scss‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ body.layout-openstack,
3535
body.layout-packet,
3636
body.layout-postgresql,
3737
body.layout-powerdns,
38+
body.layout-random,
3839
body.layout-rundeck,
3940
body.layout-statuscake,
4041
body.layout-softlayer,

‎website/source/docs/providers/random/index.html.markdown‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
layout: "random"
3+
page_title: "Provider: Random"
4+
sidebar_current: "docs-random-index"
5+
description: |-
6+
The Random provider is used to generate randomness.
7+
---
8+
9+
# Random Provider
10+
11+
The "random" provider allows the use of randomness within Terraform
12+
configurations. This is a *logical provider*, which means that it works
13+
entirely within Terraform's logic, and doesn't interact with any other
14+
services.
15+
16+
Unconstrained randomness within a Terraform configuration would not be very
17+
useful, since Terraform's goal is to converge on a fixed configuration by
18+
applying a diff. Because of this, the "random" provider provides an idea of
19+
*managed randomness*: it provides resources that generate random values during
20+
their creation and then hold those values steady until the inputs are changed.
21+
22+
Even with these resources, it is advisable to keep the use of randomness within
23+
Terraform configuration to a minimum, and retain it for special cases only;
24+
Terraform works best when the configuration is well-defined, since its behavior
25+
can then be more readily predicted.
26+
27+
Unless otherwise stated within the documentation of a specific resource, this
28+
provider's results are **not** sufficiently random for cryptographic use.
29+
30+
For more information on the specific resources available, see the links in the
31+
navigation bar. Read on for information on the general patterns that apply
32+
to this provider's resources.
33+
34+
## Resource "Keepers"
35+
36+
As noted above, the random resources generate randomness only when they are
37+
created; the results produced are stored in the Terraform state and re-used
38+
until the inputs change, prompting the resource to be recreated.
39+
40+
The resources all provide a map argument called `keepers` that can be populated
41+
with arbitrary key/value pairs that should be selected such that they remain
42+
the same until new random values are desired.
43+
44+
For example:
45+
46+
```
47+
resource "random_id" "server" {
48+
keepers = {
49+
# Generate a new id each time we switch to a new AMI id
50+
ami_id = "${var.ami_id}"
51+
}
52+
53+
byte_length = 8
54+
}
55+
56+
resource "aws_instance" "server" {
57+
tags = {
58+
Name = "web-server ${random_id.server.hex}"
59+
}
60+
61+
# Read the AMI id "through" the random_id resource to ensure that
62+
# both will change together.
63+
ami = "${random_id.server.keepers.ami_id}"
64+
65+
# ... (other aws_instance arguments) ...
66+
}
67+
```
68+
69+
Resource "keepers" are optional. The other arguments to each resource must
70+
*also* remain constant in order to retain a random result.
71+
72+
To force a random result to be replaced, the `taint` command can be used to
73+
produce a new result on the next run.

‎website/source/docs/providers/random/r/id.html.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
layout: "random"
3+
page_title: "Random: random_id"
4+
sidebar_current: "docs-random-resource-id"
5+
description: |-
6+
Generates a random identifier.
7+
---
8+
9+
# random\_id
10+
11+
The resource `random_id` generates random numbers that are intended to be
12+
used as unique identifiers for other resources.
13+
14+
Unlike other resources in the "random" provider, this resource *does* use a
15+
cryptographic random number generator in order to minimize the chance of
16+
collisions, making the results of this resource when a 32-byte identifier
17+
is requested of equivalent uniqueness to a type-4 UUID.
18+
19+
This resource can be used in conjunction with resources that have,
20+
the `create_before_destroy` lifecycle flag set, to avoid conflicts with
21+
unique names during the brief period where both the old and new resources
22+
exist concurrently.
23+
24+
## Example Usage
25+
26+
The following example shows how to generate a unique name for an AWS EC2
27+
instance that changes each time a new AMI id is selected.
28+
29+
```
30+
resource "random_id" "server" {
31+
keepers = {
32+
# Generate a new id each time we switch to a new AMI id
33+
ami_id = "${var.ami_id}"
34+
}
35+
36+
byte_length = 8
37+
}
38+
39+
resource "aws_instance" "server" {
40+
tags = {
41+
Name = "web-server ${random_id.server.hex}"
42+
}
43+
44+
# Read the AMI id "through" the random_id resource to ensure that
45+
# both will change together.
46+
ami = "${random_id.server.keepers.ami_id}"
47+
48+
# ... (other aws_instance arguments) ...
49+
}
50+
```
51+
52+
## Argument Reference
53+
54+
The following arguments are supported:
55+
56+
* `byte_length` - (Required) The number of random bytes to produce. The
57+
minimum value is 1, which produces eight bits of randomness.
58+
59+
* `keepers` - (Optional) Arbitrary map of values that, when changed, will
60+
trigger a new id to be generated. See
61+
[the main provider documentation](../index.html) for more information.
62+
63+
## Attributes Reference
64+
65+
The following attributes are exported:
66+
67+
* `b64` - The generated id presented in base64, using the URL-friendly character set: case-sensitive letters, digits and the characters `_` and `-`.
68+
* `hex` - The generated id presented in padded hexadecimal digits. This result will always be twice as long as the requested byte length.
69+
* `decimal` - The generated id presented in non-padded decimal digits.

‎website/source/docs/providers/random/r/shuffle.html.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
layout: "random"
3+
page_title: "Random: random_shuffle"
4+
sidebar_current: "docs-random-resource-shuffle"
5+
description: |-
6+
Produces a random permutation of a given list.
7+
---
8+
9+
# random\_shuffle
10+
11+
The resource `random_shuffle` generates a random permutation of a list
12+
of strings given as an argument.
13+
14+
## Example Usage
15+
16+
```
17+
resource "random_shuffle" "az" {
18+
input = ["us-west-1a", "us-west-1c", "us-west-1d", "us-west-1e"]
19+
result_count = 2
20+
}
21+
22+
resource "aws_elb" "example" {
23+
# Place the ELB in any two of the given availability zones, selected
24+
# at random.
25+
availability_zones = ["${random_shuffle.az.result}"]
26+
27+
# ... and other aws_elb arguments ...
28+
}
29+
```
30+
31+
## Argument Reference
32+
33+
The following arguments are supported:
34+
35+
* `input` - (Required) The list of strings to shuffle.
36+
37+
* `result_count` - (Optional) The number of results to return. Defaults to
38+
the number of items in the `input` list. If fewer items are requested,
39+
some elements will be excluded from the result. If more items are requested,
40+
items will be repeated in the result but not more frequently than the number
41+
of items in the input list.
42+
43+
* `keepers` - (Optional) Arbitrary map of values that, when changed, will
44+
trigger a new id to be generated. See
45+
[the main provider documentation](../index.html) for more information.
46+
47+
* `seed` - (Optional) Arbitrary string with which to seed the random number
48+
generator, in order to produce less-volatile permutations of the list.
49+
**Important:** Even with an identical seed, it is not guaranteed that the
50+
same permutation will be produced across different versions of Terraform.
51+
This argument causes the result to be *less volatile*, but not fixed for
52+
all time.
53+
54+
## Attributes Reference
55+
56+
The following attributes are exported:
57+
58+
* `result` - Random permutation of the list of strings given in `input`.
59+

‎website/source/layouts/docs.erb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,10 @@
249249
<a href="/docs/providers/powerdns/index.html">PowerDNS</a>
250250
</li>
251251

252+
<li<%= sidebar_current("docs-providers-random") %>>
253+
<a href="/docs/providers/random/index.html">Random</a>
254+
</li>
255+
252256
<li<%= sidebar_current("docs-providers-rundeck") %>>
253257
<a href="/docs/providers/rundeck/index.html">Rundeck</a>
254258
</li>

‎website/source/layouts/random.erb‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<% wrap_layout :inner do %>
2+
<% content_for :sidebar do %>
3+
<div class="docs-sidebar hidden-print affix-top" role="complementary">
4+
<ul class="nav docs-sidenav">
5+
<li<%= sidebar_current("docs-home") %>>
6+
<a href="/docs/providers/index.html">&laquo; Documentation Home</a>
7+
</li>
8+
9+
<li<%= sidebar_current("docs-random-index") %>>
10+
<a href="/docs/providers/random/index.html">Random Provider</a>
11+
</li>
12+
13+
<li<%= sidebar_current(/^docs-random-resource/) %>>
14+
<a href="#">Resources</a>
15+
<ul class="nav nav-visible">
16+
<li<%= sidebar_current("docs-random-resource-id") %>>
17+
<a href="/docs/providers/random/r/id.html">random_id</a>
18+
</li>
19+
<li<%= sidebar_current("docs-random-resource-shuffle") %>>
20+
<a href="/docs/providers/random/r/shuffle.html">random_shuffle</a>
21+
</li>
22+
</ul>
23+
</li>
24+
</ul>
25+
</div>
26+
<% end %>
27+
28+
<%= yield %>
29+
<% end %>

0 commit comments

Comments
 (0)