website: docs for the "random" provider
This commit is contained in:
Martin Atkins
parent
eec6c88fd2
commit
feafc94dde
|
|
@ -35,6 +35,7 @@ body.layout-openstack,
|
|||
body.layout-packet,
|
||||
body.layout-postgresql,
|
||||
body.layout-powerdns,
|
||||
body.layout-random,
|
||||
body.layout-rundeck,
|
||||
body.layout-statuscake,
|
||||
body.layout-softlayer,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
layout: "random"
|
||||
page_title: "Provider: Random"
|
||||
sidebar_current: "docs-random-index"
|
||||
description: |-
|
||||
The Random provider is used to generate randomness.
|
||||
---
|
||||
|
||||
# Random Provider
|
||||
|
||||
The "random" provider allows the use of randomness within Terraform
|
||||
configurations. This is a *logical provider*, which means that it works
|
||||
entirely within Terraform's logic, and doesn't interact with any other
|
||||
services.
|
||||
|
||||
Unconstrained randomness within a Terraform configuration would not be very
|
||||
useful, since Terraform's goal is to converge on a fixed configuration by
|
||||
applying a diff. Because of this, the "random" provider provides an idea of
|
||||
*managed randomness*: it provides resources that generate random values during
|
||||
their creation and then hold those values steady until the inputs are changed.
|
||||
|
||||
Even with these resources, it is advisable to keep the use of randomness within
|
||||
Terraform configuration to a minimum, and retain it for special cases only;
|
||||
Terraform works best when the configuration is well-defined, since its behavior
|
||||
can then be more readily predicted.
|
||||
|
||||
Unless otherwise stated within the documentation of a specific resource, this
|
||||
provider's results are **not** sufficiently random for cryptographic use.
|
||||
|
||||
For more information on the specific resources available, see the links in the
|
||||
navigation bar. Read on for information on the general patterns that apply
|
||||
to this provider's resources.
|
||||
|
||||
## Resource "Keepers"
|
||||
|
||||
As noted above, the random resources generate randomness only when they are
|
||||
created; the results produced are stored in the Terraform state and re-used
|
||||
until the inputs change, prompting the resource to be recreated.
|
||||
|
||||
The resources all provide a map argument called `keepers` that can be populated
|
||||
with arbitrary key/value pairs that should be selected such that they remain
|
||||
the same until new random values are desired.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
resource "random_id" "server" {
|
||||
keepers = {
|
||||
# Generate a new id each time we switch to a new AMI id
|
||||
ami_id = "${var.ami_id}"
|
||||
}
|
||||
|
||||
byte_length = 8
|
||||
}
|
||||
|
||||
resource "aws_instance" "server" {
|
||||
tags = {
|
||||
Name = "web-server ${random_id.server.hex}"
|
||||
}
|
||||
|
||||
# Read the AMI id "through" the random_id resource to ensure that
|
||||
# both will change together.
|
||||
ami = "${random_id.server.keepers.ami_id}"
|
||||
|
||||
# ... (other aws_instance arguments) ...
|
||||
}
|
||||
```
|
||||
|
||||
Resource "keepers" are optional. The other arguments to each resource must
|
||||
*also* remain constant in order to retain a random result.
|
||||
|
||||
To force a random result to be replaced, the `taint` command can be used to
|
||||
produce a new result on the next run.
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
layout: "random"
|
||||
page_title: "Random: random_id"
|
||||
sidebar_current: "docs-random-resource-id"
|
||||
description: |-
|
||||
Generates a random identifier.
|
||||
---
|
||||
|
||||
# random\_id
|
||||
|
||||
The resource `random_id` generates random numbers that are intended to be
|
||||
used as unique identifiers for other resources.
|
||||
|
||||
Unlike other resources in the "random" provider, 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 32-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.
|
||||
|
||||
## Example Usage
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
resource "random_id" "server" {
|
||||
keepers = {
|
||||
# Generate a new id each time we switch to a new AMI id
|
||||
ami_id = "${var.ami_id}"
|
||||
}
|
||||
|
||||
byte_length = 8
|
||||
}
|
||||
|
||||
resource "aws_instance" "server" {
|
||||
tags = {
|
||||
Name = "web-server ${random_id.server.hex}"
|
||||
}
|
||||
|
||||
# Read the AMI id "through" the random_id resource to ensure that
|
||||
# both will change together.
|
||||
ami = "${random_id.server.keepers.ami_id}"
|
||||
|
||||
# ... (other aws_instance arguments) ...
|
||||
}
|
||||
```
|
||||
|
||||
## Argument Reference
|
||||
|
||||
The following arguments are supported:
|
||||
|
||||
* `byte_length` - (Required) The number of random bytes to produce. The
|
||||
minimum value is 1, which produces eight bits of randomness.
|
||||
|
||||
* `keepers` - (Optional) Arbitrary map of values that, when changed, will
|
||||
trigger a new id to be generated. See
|
||||
[the main provider documentation](../index.html) for more information.
|
||||
|
||||
## Attributes Reference
|
||||
|
||||
The following attributes are exported:
|
||||
|
||||
* `b64` - The generated id presented in base64, using the URL-friendly character set: case-sensitive letters, digits and the characters `_` and `-`.
|
||||
* `hex` - The generated id presented in padded hexadecimal digits. This result will always be twice as long as the requested byte length.
|
||||
* `decimal` - The generated id presented in non-padded decimal digits.
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
layout: "random"
|
||||
page_title: "Random: random_shuffle"
|
||||
sidebar_current: "docs-random-resource-shuffle"
|
||||
description: |-
|
||||
Produces a random permutation of a given list.
|
||||
---
|
||||
|
||||
# random\_shuffle
|
||||
|
||||
The resource `random_shuffle` generates a random permutation of a list
|
||||
of strings given as an argument.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
resource "random_shuffle" "az" {
|
||||
input = ["us-west-1a", "us-west-1c", "us-west-1d", "us-west-1e"]
|
||||
result_count = 2
|
||||
}
|
||||
|
||||
resource "aws_elb" "example" {
|
||||
# Place the ELB in any two of the given availability zones, selected
|
||||
# at random.
|
||||
availability_zones = ["${random_shuffle.az.result}"]
|
||||
|
||||
# ... and other aws_elb arguments ...
|
||||
}
|
||||
```
|
||||
|
||||
## Argument Reference
|
||||
|
||||
The following arguments are supported:
|
||||
|
||||
* `input` - (Required) The list of strings to shuffle.
|
||||
|
||||
* `result_count` - (Optional) 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.
|
||||
|
||||
* `keepers` - (Optional) Arbitrary map of values that, when changed, will
|
||||
trigger a new id to be generated. See
|
||||
[the main provider documentation](../index.html) for more information.
|
||||
|
||||
* `seed` - (Optional) 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 Terraform.
|
||||
This argument causes the result to be *less volatile*, but not fixed for
|
||||
all time.
|
||||
|
||||
## Attributes Reference
|
||||
|
||||
The following attributes are exported:
|
||||
|
||||
* `result` - Random permutation of the list of strings given in `input`.
|
||||
|
||||
|
|
@ -249,6 +249,10 @@
|
|||
<a href="/docs/providers/powerdns/index.html">PowerDNS</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-providers-random") %>>
|
||||
<a href="/docs/providers/random/index.html">Random</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-providers-rundeck") %>>
|
||||
<a href="/docs/providers/rundeck/index.html">Rundeck</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,29 @@
|
|||
<% wrap_layout :inner do %>
|
||||
<% content_for :sidebar do %>
|
||||
<div class="docs-sidebar hidden-print affix-top" role="complementary">
|
||||
<ul class="nav docs-sidenav">
|
||||
<li<%= sidebar_current("docs-home") %>>
|
||||
<a href="/docs/providers/index.html">« Documentation Home</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-random-index") %>>
|
||||
<a href="/docs/providers/random/index.html">Random Provider</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current(/^docs-random-resource/) %>>
|
||||
<a href="#">Resources</a>
|
||||
<ul class="nav nav-visible">
|
||||
<li<%= sidebar_current("docs-random-resource-id") %>>
|
||||
<a href="/docs/providers/random/r/id.html">random_id</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-random-resource-shuffle") %>>
|
||||
<a href="/docs/providers/random/r/shuffle.html">random_shuffle</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<% end %>
|
||||
|
||||
<%= yield %>
|
||||
<% end %>
|
||||
Loading…
Reference in New Issue