website: documentation for the vault provider
This commit is contained in:
Martin Atkins
parent
25f73dac83
commit
d28468d9a3
|
|
@ -50,6 +50,7 @@ body.layout-template,
|
||||||
body.layout-tls,
|
body.layout-tls,
|
||||||
body.layout-ultradns,
|
body.layout-ultradns,
|
||||||
body.layout-triton,
|
body.layout-triton,
|
||||||
|
body.layout-vault,
|
||||||
body.layout-vcd,
|
body.layout-vcd,
|
||||||
body.layout-vsphere,
|
body.layout-vsphere,
|
||||||
body.layout-docs,
|
body.layout-docs,
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,81 @@
|
||||||
|
---
|
||||||
|
layout: "vault"
|
||||||
|
page_title: "Vault: vault_generic_secret data source"
|
||||||
|
sidebar_current: "docs-vault-datasource-generic-secret"
|
||||||
|
description: |-
|
||||||
|
Reads arbitrary data from a given path in Vault
|
||||||
|
---
|
||||||
|
|
||||||
|
# vault\_generic\_secret
|
||||||
|
|
||||||
|
Reads arbitrary data from a given path in Vault.
|
||||||
|
|
||||||
|
This resource is primarily intended to be used with
|
||||||
|
[Vault's "generic" secret backend](https://www.vaultproject.io/docs/secrets/generic/index.html),
|
||||||
|
but it is also compatible with any other Vault endpoint that supports
|
||||||
|
the `vault read` command.
|
||||||
|
|
||||||
|
~> **Important** All data retrieved from Vault will be
|
||||||
|
written in cleartext to state file generated by Terraform, will appear in
|
||||||
|
the console output when Terraform runs, and may be included in plan files
|
||||||
|
if secrets are interpolated into any resource attributes.
|
||||||
|
Protect these artifacts accordingly. See
|
||||||
|
[the main provider documentation](../index.html)
|
||||||
|
for more details.
|
||||||
|
|
||||||
|
## Example Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
data "vault_generic_secret" "rundeck_auth" {
|
||||||
|
path = "secret/rundeck_auth"
|
||||||
|
}
|
||||||
|
|
||||||
|
# Rundeck Provider, for example
|
||||||
|
provider "rundeck" {
|
||||||
|
url = "http://rundeck.example.com/"
|
||||||
|
auth_token = "${data.vault_generic_secret.rundeck_auth.data["auth_token"]}"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Argument Reference
|
||||||
|
|
||||||
|
The following arguments are supported:
|
||||||
|
|
||||||
|
* `path` - (Required) The full logical path from which to request data.
|
||||||
|
To read data from the "generic" secret backend mounted in Vault by
|
||||||
|
default, this should be prefixed with `secret/`. Reading from other backends
|
||||||
|
with this data source is possible; consult each backend's documentation
|
||||||
|
to see which endpoints support the `GET` method.
|
||||||
|
|
||||||
|
## Required Vault Capabilities
|
||||||
|
|
||||||
|
Use of this resource requires the `read` capability on the given path.
|
||||||
|
|
||||||
|
## Attributes Reference
|
||||||
|
|
||||||
|
The following attributes are exported:
|
||||||
|
|
||||||
|
* `data_json` - A string containing the full data payload retrieved from
|
||||||
|
Vault, serialized in JSON format.
|
||||||
|
|
||||||
|
* `data` - A mapping whose keys are the top-level data keys returned from
|
||||||
|
Vault and whose values are the corresponding values. This map can only
|
||||||
|
represent string data, so any non-string values returned from Vault are
|
||||||
|
serialized as JSON.
|
||||||
|
|
||||||
|
* `lease_id` - The lease identifier assigned by Vault, if any.
|
||||||
|
|
||||||
|
* `lease_duration` - The duration of the secret lease, in seconds relative
|
||||||
|
to the time the data was requested. Once this time has passed any plan
|
||||||
|
generated with this data may fail to apply.
|
||||||
|
|
||||||
|
* `lease_start_time` - As a convenience, this records the current time
|
||||||
|
on the computer where Terraform is running when the data is requested.
|
||||||
|
This can be used to approximate the absolute time represented by
|
||||||
|
`lease_duration`, though users must allow for any clock drift and response
|
||||||
|
latency relative to to the Vault server.
|
||||||
|
|
||||||
|
* `lease_renewable` - `true` if the lease can be renewed using Vault's
|
||||||
|
`sys/renew/{lease-id}` endpoint. Terraform does not currently support lease
|
||||||
|
renewal, and so it will request a new lease each time this data source is
|
||||||
|
refreshed.
|
||||||
|
|
@ -0,0 +1,139 @@
|
||||||
|
---
|
||||||
|
layout: "vault"
|
||||||
|
page_title: "Provider: Vault"
|
||||||
|
sidebar_current: "docs-vault-index"
|
||||||
|
description: |-
|
||||||
|
The Vault provider allows Terraform to read from, write to, and configure Hashicorp Vault
|
||||||
|
---
|
||||||
|
|
||||||
|
# Vault Provider
|
||||||
|
|
||||||
|
The Vault provider allows Terraform to read from, write to, and configure
|
||||||
|
[Hashicorp Vault](https://vaultproject.io/).
|
||||||
|
|
||||||
|
~> **Important** Interacting with Vault from Terraform causes an secrets
|
||||||
|
that you read and write to be persisted in both Terraform's state file
|
||||||
|
*and* in any generated plan files. For any Terraform module that reads or
|
||||||
|
writes Vault secrets, these files should be treated as sensitive and
|
||||||
|
protected accordingly.
|
||||||
|
|
||||||
|
This provider serves two pretty-distinct use-cases, which each have their
|
||||||
|
own security trade-offs and caveats that are covered in the sections that
|
||||||
|
follow. Consider these carefully before using this provider within your
|
||||||
|
Terraform configuration.
|
||||||
|
|
||||||
|
## Configuring and Populating Vault
|
||||||
|
|
||||||
|
Terraform can be used by the Vault adminstrators to configure Vault and
|
||||||
|
populate it with secrets. In this case, the state and any plans associated
|
||||||
|
with the configuration must be stored and communicated with care, since they
|
||||||
|
will contain in cleartext any values that were written into Vault.
|
||||||
|
|
||||||
|
Currently Terraform has no mechanism to redact or protect secrets
|
||||||
|
that are provided via configuration, so teams choosing to use Terraform
|
||||||
|
for populating Vault secrets should pay careful attention to the notes
|
||||||
|
on each resource's documentation page about how any secrets are persisted
|
||||||
|
to the state and consider carefully whether such usage is compatible with
|
||||||
|
their security policies.
|
||||||
|
|
||||||
|
Except as otherwise noted, the resources that write secrets into Vault are
|
||||||
|
designed such that they require only the *create* and *update* capabilities
|
||||||
|
on the relevant resources, so that distinct tokens can be used for reading
|
||||||
|
vs. writing and thus limit the exposure of a compromised token.
|
||||||
|
|
||||||
|
## Using Vault credentials in Terraform configuration
|
||||||
|
|
||||||
|
Most Terraform providers require credentials to interact with a third-party
|
||||||
|
service that they wrap. This provider allows such credentials to be obtained
|
||||||
|
from Vault, which means that operators or systems running Terraform need
|
||||||
|
only access to a suitably-privileged Vault token in order to temporarily
|
||||||
|
lease the credentials for other providers.
|
||||||
|
|
||||||
|
Currently Terraform has no mechanism to redact or protect secrets that
|
||||||
|
are returned via data sources, so secrets read via this provider will be
|
||||||
|
persisted into the Terraform state, into any plan files, and in some cases
|
||||||
|
in the console output produced while planning and applying. These artifacts
|
||||||
|
must therefore all be protected accordingly.
|
||||||
|
|
||||||
|
To reduce the exposure of such secrets, the provider requests a Vault token
|
||||||
|
with a relatively-short TTL (20 minutes, by default) which in turn means
|
||||||
|
that where possible Vault will revoke any issued credentials after that
|
||||||
|
time, but in particular it is unable to retract any static secrets such as
|
||||||
|
those stored in Vault's "generic" secret backend.
|
||||||
|
|
||||||
|
The requested token TTL can be controlled by the `max_lease_ttl_seconds`
|
||||||
|
provider argument described below. It is important to consider that Terraform
|
||||||
|
reads from data sources during the `plan` phase and writes the result into
|
||||||
|
the plan. Thus a subsequent `apply` will likely fail if it is run after the
|
||||||
|
intermediate token has expired, due to the revocation of the secrets that
|
||||||
|
are stored in the plan.
|
||||||
|
|
||||||
|
Except as otherwise noted, the resources that read secrets from Vault
|
||||||
|
are designed such that they require only the *read* capability on the relevant
|
||||||
|
resources.
|
||||||
|
|
||||||
|
## Provider Arguments
|
||||||
|
|
||||||
|
The provider configuration block accepts the following arguments.
|
||||||
|
In most cases it is recommended to set them via the indicated environment
|
||||||
|
variables in order to keep credential information out of the configuration.
|
||||||
|
|
||||||
|
* `address` - (Required) Origin URL of the Vault server. This is a URL
|
||||||
|
with a scheme, a hostname and a port but with no path. May be set
|
||||||
|
via the `VAULT_ADDR` environment variable.
|
||||||
|
|
||||||
|
* `token` - (Required) Vault token that will be used by Terraform to
|
||||||
|
authenticate. May be set via the `VAULT_TOKEN` environment variable.
|
||||||
|
Terraform will issue itself a new token that is a child of the one given,
|
||||||
|
with a short TTL to limit the exposure of any requested secrets.
|
||||||
|
|
||||||
|
* `ca_cert_file` - (Optional) Path to a file on local disk that will be
|
||||||
|
used to validate the certificate presented by the Vault server.
|
||||||
|
May be set via the `VAULT_CACERT` environment variable.
|
||||||
|
|
||||||
|
* `ca_cert_dir` - (Optional) Path to a directory on local disk that
|
||||||
|
contains one or more certificate files that will be used to validate
|
||||||
|
the certificate presented by the Vault server. May be set via the
|
||||||
|
`VAULT_CAPATH` environment variable.
|
||||||
|
|
||||||
|
* `client_auth` - (Optional) A configuration block, described below, that
|
||||||
|
provides credentials used by Terraform to authenticate with the Vault
|
||||||
|
server. At present there is little reason to set this, because Terraform
|
||||||
|
does not support the TLS certificate authentication mechanism.
|
||||||
|
|
||||||
|
* `skip_tls_verify` - (Optional) Set this to `true` to disable verification
|
||||||
|
of the Vault server's TLS certificate. This is strongly discouraged except
|
||||||
|
in prototype or development environments, since it exposes the possibility
|
||||||
|
that Terraform can be tricked into writing secrets to a server controlled
|
||||||
|
by an intruder. May be set via the `VAULT_SKIP_VERIFY` environment variable.
|
||||||
|
|
||||||
|
* `max_lease_ttl_seconds` - (Optional) Used as the duration for the
|
||||||
|
intermediate Vault token Terraform issues itself, which in turn limits
|
||||||
|
the duration of secret leases issued by Vault. Defaults to 20 minutes
|
||||||
|
and may be set via the `TERRAFORM_VAULT_MAX_TTL` environment variable.
|
||||||
|
See the section above on *Using Vault credentials in Terraform configuration*
|
||||||
|
for the implications of this setting.
|
||||||
|
|
||||||
|
The `client_auth` configuration block accepts the following arguments:
|
||||||
|
|
||||||
|
* `cert_file` - (Required) Path to a file on local disk that contains the
|
||||||
|
PEM-encoded certificate to present to the server.
|
||||||
|
|
||||||
|
* `key_file` - (Required) Path to a file on local disk that contains the
|
||||||
|
PEM-encoded private key for which the authentication certificate was issued.
|
||||||
|
|
||||||
|
## Example Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
provider "vault" {
|
||||||
|
# It is strongly recommended to configure this provider through the
|
||||||
|
# environment variables described below, so that each user can have
|
||||||
|
# separate credentials set in the environment.
|
||||||
|
address = "https://vault.example.net:8200"
|
||||||
|
}
|
||||||
|
|
||||||
|
data "vault_generic_secret" "example" {
|
||||||
|
path = "secret/foo"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
@ -0,0 +1,69 @@
|
||||||
|
---
|
||||||
|
layout: "vault"
|
||||||
|
page_title: "Vault: vault_generic_secret resource"
|
||||||
|
sidebar_current: "docs-vault-resource-generic-secret"
|
||||||
|
description: |-
|
||||||
|
Writes arbitrary data to a given path in Vault
|
||||||
|
---
|
||||||
|
|
||||||
|
# vault\_generic\_secret
|
||||||
|
|
||||||
|
Writes and manages arbitrary data at a given path in Vault.
|
||||||
|
|
||||||
|
This resource is primarily intended to be used with
|
||||||
|
[Vault's "generic" secret backend](https://www.vaultproject.io/docs/secrets/generic/index.html),
|
||||||
|
but it is also compatible with any other Vault endpoint that supports
|
||||||
|
the `vault write` command to create and the `vault delete` command to
|
||||||
|
delete.
|
||||||
|
|
||||||
|
~> **Important** All data provided in the resource configuration will be
|
||||||
|
written in cleartext to state and plan files generated by Terraform, and
|
||||||
|
will appear in the console output when Terraform runs. Protect these
|
||||||
|
artifacts accordingly. See
|
||||||
|
[the main provider documentation](../index.html)
|
||||||
|
for more details.
|
||||||
|
|
||||||
|
## Example Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
resource "vault_generic_secret" "example" {
|
||||||
|
path = "secret/foo"
|
||||||
|
|
||||||
|
data_json = <<EOT
|
||||||
|
{
|
||||||
|
"foo": "bar",
|
||||||
|
"pizza": "cheese"
|
||||||
|
}
|
||||||
|
EOT
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Argument Reference
|
||||||
|
|
||||||
|
The following arguments are supported:
|
||||||
|
|
||||||
|
* `path` - (Required) The full logical path at which to write the given
|
||||||
|
data. To write data into the "generic" secret backend mounted in Vault by
|
||||||
|
default, this should be prefixed with `secret/`. Writing to other backends
|
||||||
|
with this resource is possible; consult each backend's documentation to
|
||||||
|
see which endpoints support the `PUT` and `DELETE` methods.
|
||||||
|
|
||||||
|
* `data_json` - (Required) String containing a JSON-encoded object that
|
||||||
|
will be written as the secret data at the given path.
|
||||||
|
|
||||||
|
## Required Vault Capabilities
|
||||||
|
|
||||||
|
Use of this resource requires the `create` or `update` capability
|
||||||
|
(depending on whether the resource already exists) on the given path,
|
||||||
|
along with the `delete` capbility if the resource is removed from
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
This resource does not *read* the secret data back from Terraform
|
||||||
|
on refresh. This avoids the need for `read` access on the given
|
||||||
|
path, but it means that Terraform is not able to detect and repair
|
||||||
|
"drift" on this resource should the data be updated or deleted outside
|
||||||
|
of Terraform.
|
||||||
|
|
||||||
|
## Attributes Reference
|
||||||
|
|
||||||
|
No additional attributes are exported by this resource.
|
||||||
|
|
@ -338,6 +338,10 @@
|
||||||
<a href="/docs/providers/ultradns/index.html">UltraDNS</a>
|
<a href="/docs/providers/ultradns/index.html">UltraDNS</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
|
<li<%= sidebar_current("docs-providers-vault") %>>
|
||||||
|
<a href="/docs/providers/vault/index.html">Vault</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("docs-providers-vcd") %>>
|
<li<%= sidebar_current("docs-providers-vcd") %>>
|
||||||
<a href="/docs/providers/vcd/index.html">VMware vCloud Director</a>
|
<a href="/docs/providers/vcd/index.html">VMware vCloud Director</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,40 @@
|
||||||
|
<% 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-vault-index") %>>
|
||||||
|
<a href="/docs/providers/vault/index.html">Vault Provider</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li<%= sidebar_current(/^docs-vault-datasource/) %>>
|
||||||
|
<a href="#">Data Sources</a>
|
||||||
|
<ul class="nav nav-visible">
|
||||||
|
|
||||||
|
<li<%= sidebar_current("docs-vault-datasource-generic-secret") %>>
|
||||||
|
<a href="/docs/providers/vault/d/generic_secret.html">vault_generic_secret</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li<%= sidebar_current(/^docs-vault-resource/) %>>
|
||||||
|
<a href="#">Resources</a>
|
||||||
|
<ul class="nav nav-visible">
|
||||||
|
|
||||||
|
<li<%= sidebar_current("docs-vault-resource-generic-secret") %>>
|
||||||
|
<a href="/docs/providers/vault/r/generic_secret.html">vault_generic_secret</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<% end %>
|
||||||
|
|
||||||
|
<%= yield %>
|
||||||
|
<% end %>
|
||||||
Loading…
Reference in New Issue