github.com/minamijoyo/terraform@v0.7.8-0.20161029001309-18b3736ba44b/website/source/docs/providers/random/index.html.markdown (about)

     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.