github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/website/source/docs/providers/vault/index.html.markdown (about)

     1  ---
     2  layout: "vault"
     3  page_title: "Provider: Vault"
     4  sidebar_current: "docs-vault-index"
     5  description: |-
     6    The Vault provider allows Terraform to read from, write to, and configure Hashicorp Vault
     7  ---
     8  
     9  # Vault Provider
    10  
    11  The Vault provider allows Terraform to read from, write to, and configure
    12  [Hashicorp Vault](https://vaultproject.io/).
    13  
    14  ~> **Important** Interacting with Vault from Terraform causes any secrets
    15  that you read and write to be persisted in both Terraform's state file
    16  *and* in any generated plan files. For any Terraform module that reads or
    17  writes Vault secrets, these files should be treated as sensitive and
    18  protected accordingly.
    19  
    20  This provider serves two pretty-distinct use-cases, which each have their
    21  own security trade-offs and caveats that are covered in the sections that
    22  follow. Consider these carefully before using this provider within your
    23  Terraform configuration.
    24  
    25  ## Configuring and Populating Vault
    26  
    27  Terraform can be used by the Vault adminstrators to configure Vault and
    28  populate it with secrets. In this case, the state and any plans associated
    29  with the configuration must be stored and communicated with care, since they
    30  will contain in cleartext any values that were written into Vault.
    31  
    32  Currently Terraform has no mechanism to redact or protect secrets
    33  that are provided via configuration, so teams choosing to use Terraform
    34  for populating Vault secrets should pay careful attention to the notes
    35  on each resource's documentation page about how any secrets are persisted
    36  to the state and consider carefully whether such usage is compatible with
    37  their security policies.
    38  
    39  Except as otherwise noted, the resources that write secrets into Vault are
    40  designed such that they require only the *create* and *update* capabilities
    41  on the relevant resources, so that distinct tokens can be used for reading
    42  vs. writing and thus limit the exposure of a compromised token.
    43  
    44  ## Using Vault credentials in Terraform configuration
    45  
    46  Most Terraform providers require credentials to interact with a third-party
    47  service that they wrap. This provider allows such credentials to be obtained
    48  from Vault, which means that operators or systems running Terraform need
    49  only access to a suitably-privileged Vault token in order to temporarily
    50  lease the credentials for other providers.
    51  
    52  Currently Terraform has no mechanism to redact or protect secrets that
    53  are returned via data sources, so secrets read via this provider will be
    54  persisted into the Terraform state, into any plan files, and in some cases
    55  in the console output produced while planning and applying. These artifacts
    56  must therefore all be protected accordingly.
    57  
    58  To reduce the exposure of such secrets, the provider requests a Vault token
    59  with a relatively-short TTL (20 minutes, by default) which in turn means
    60  that where possible Vault will revoke any issued credentials after that
    61  time, but in particular it is unable to retract any static secrets such as
    62  those stored in Vault's "generic" secret backend.
    63  
    64  The requested token TTL can be controlled by the `max_lease_ttl_seconds`
    65  provider argument described below. It is important to consider that Terraform
    66  reads from data sources during the `plan` phase and writes the result into
    67  the plan. Thus a subsequent `apply` will likely fail if it is run after the
    68  intermediate token has expired, due to the revocation of the secrets that
    69  are stored in the plan.
    70  
    71  Except as otherwise noted, the resources that read secrets from Vault
    72  are designed such that they require only the *read* capability on the relevant
    73  resources.
    74  
    75  ## Provider Arguments
    76  
    77  The provider configuration block accepts the following arguments.
    78  In most cases it is recommended to set them via the indicated environment
    79  variables in order to keep credential information out of the configuration.
    80  
    81  * `address` - (Required) Origin URL of the Vault server. This is a URL
    82    with a scheme, a hostname and a port but with no path. May be set
    83    via the `VAULT_ADDR` environment variable.
    84  
    85  * `token` - (Required) Vault token that will be used by Terraform to
    86    authenticate. May be set via the `VAULT_TOKEN` environment variable.
    87    If none is otherwise supplied, Terraform will attempt to read it from
    88    `~/.vault-token` (where the vault command stores its current token).
    89    Terraform will issue itself a new token that is a child of the one given,
    90    with a short TTL to limit the exposure of any requested secrets.
    91  
    92  * `ca_cert_file` - (Optional) Path to a file on local disk that will be
    93    used to validate the certificate presented by the Vault server.
    94    May be set via the `VAULT_CACERT` environment variable.
    95  
    96  * `ca_cert_dir` - (Optional) Path to a directory on local disk that
    97    contains one or more certificate files that will be used to validate
    98    the certificate presented by the Vault server. May be set via the
    99    `VAULT_CAPATH` environment variable.
   100  
   101  * `client_auth` - (Optional) A configuration block, described below, that
   102    provides credentials used by Terraform to authenticate with the Vault
   103    server. At present there is little reason to set this, because Terraform
   104    does not support the TLS certificate authentication mechanism.
   105  
   106  * `skip_tls_verify` - (Optional) Set this to `true` to disable verification
   107    of the Vault server's TLS certificate. This is strongly discouraged except
   108    in prototype or development environments, since it exposes the possibility
   109    that Terraform can be tricked into writing secrets to a server controlled
   110    by an intruder. May be set via the `VAULT_SKIP_VERIFY` environment variable.
   111  
   112  * `max_lease_ttl_seconds` - (Optional) Used as the duration for the
   113    intermediate Vault token Terraform issues itself, which in turn limits
   114    the duration of secret leases issued by Vault. Defaults to 20 minutes
   115    and may be set via the `TERRAFORM_VAULT_MAX_TTL` environment variable.
   116    See the section above on *Using Vault credentials in Terraform configuration*
   117    for the implications of this setting.
   118  
   119  The `client_auth` configuration block accepts the following arguments:
   120  
   121  * `cert_file` - (Required) Path to a file on local disk that contains the
   122    PEM-encoded certificate to present to the server.
   123  
   124  * `key_file` - (Required) Path to a file on local disk that contains the
   125    PEM-encoded private key for which the authentication certificate was issued.
   126  
   127  ## Example Usage
   128  
   129  ```hcl
   130  provider "vault" {
   131    # It is strongly recommended to configure this provider through the
   132    # environment variables described above, so that each user can have
   133    # separate credentials set in the environment.
   134    #
   135    # This will default to using $VAULT_ADDR
   136    # But can be set explicitly
   137    # address = "https://vault.example.net:8200"
   138  }
   139  
   140  resource "vault_generic_secret" "example" {
   141    path = "secret/foo"
   142  
   143    data_json = <<EOT
   144  {
   145    "foo":   "bar",
   146    "pizza": "cheese"
   147  }
   148  EOT
   149  }
   150  ```
   151