github.com/ves/terraform@v0.8.0-beta2/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    Terraform will issue itself a new token that is a child of the one given,
    88    with a short TTL to limit the exposure of any requested secrets.
    89  
    90  * `ca_cert_file` - (Optional) Path to a file on local disk that will be
    91    used to validate the certificate presented by the Vault server.
    92    May be set via the `VAULT_CACERT` environment variable.
    93  
    94  * `ca_cert_dir` - (Optional) Path to a directory on local disk that
    95    contains one or more certificate files that will be used to validate
    96    the certificate presented by the Vault server. May be set via the
    97    `VAULT_CAPATH` environment variable.
    98  
    99  * `client_auth` - (Optional) A configuration block, described below, that
   100    provides credentials used by Terraform to authenticate with the Vault
   101    server. At present there is little reason to set this, because Terraform
   102    does not support the TLS certificate authentication mechanism.
   103  
   104  * `skip_tls_verify` - (Optional) Set this to `true` to disable verification
   105    of the Vault server's TLS certificate. This is strongly discouraged except
   106    in prototype or development environments, since it exposes the possibility
   107    that Terraform can be tricked into writing secrets to a server controlled
   108    by an intruder. May be set via the `VAULT_SKIP_VERIFY` environment variable.
   109  
   110  * `max_lease_ttl_seconds` - (Optional) Used as the duration for the
   111    intermediate Vault token Terraform issues itself, which in turn limits
   112    the duration of secret leases issued by Vault. Defaults to 20 minutes
   113    and may be set via the `TERRAFORM_VAULT_MAX_TTL` environment variable.
   114    See the section above on *Using Vault credentials in Terraform configuration*
   115    for the implications of this setting.
   116  
   117  The `client_auth` configuration block accepts the following arguments:
   118  
   119  * `cert_file` - (Required) Path to a file on local disk that contains the
   120    PEM-encoded certificate to present to the server.
   121  
   122  * `key_file` - (Required) Path to a file on local disk that contains the
   123    PEM-encoded private key for which the authentication certificate was issued.
   124  
   125  ## Example Usage
   126  
   127  ```
   128  provider "vault" {
   129    # It is strongly recommended to configure this provider through the
   130    # environment variables described below, so that each user can have
   131    # separate credentials set in the environment.
   132    address = "https://vault.example.net:8200"
   133  }
   134  
   135  data "vault_generic_secret" "example" {
   136    path = "secret/foo"
   137  }
   138  ```
   139