diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 9c7afec524..733206d808 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -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, diff --git a/website/source/docs/providers/random/index.html.markdown b/website/source/docs/providers/random/index.html.markdown new file mode 100644 index 0000000000..32bf038d89 --- /dev/null +++ b/website/source/docs/providers/random/index.html.markdown @@ -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. diff --git a/website/source/docs/providers/random/r/id.html.md b/website/source/docs/providers/random/r/id.html.md new file mode 100644 index 0000000000..2fdcdd4a4b --- /dev/null +++ b/website/source/docs/providers/random/r/id.html.md @@ -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. diff --git a/website/source/docs/providers/random/r/shuffle.html.md b/website/source/docs/providers/random/r/shuffle.html.md new file mode 100644 index 0000000000..bfae65bca0 --- /dev/null +++ b/website/source/docs/providers/random/r/shuffle.html.md @@ -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`. + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index bb94f405ba..e73072791a 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -249,6 +249,10 @@ PowerDNS + > + Random + + > Rundeck diff --git a/website/source/layouts/random.erb b/website/source/layouts/random.erb new file mode 100644 index 0000000000..224559c850 --- /dev/null +++ b/website/source/layouts/random.erb @@ -0,0 +1,29 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %>