resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website: documentation for the vault provider

This commit is contained in:
Martin Atkins 2016-09-30 18:27:05 -07:00
parent 25f73dac83
commit d28468d9a3
6 changed files with 334 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
website/source/assets/stylesheets/_docs.scss
View File

@ -50,6 +50,7 @@ body.layout-template,
body.layout-tls,
body.layout-ultradns,
body.layout-triton,
body.layout-vault,
body.layout-vcd,
body.layout-vsphere,
body.layout-docs,

81
website/source/docs/providers/vault/d/generic_secret.html.md Normal file
View File

@ -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.

139
website/source/docs/providers/vault/index.html.markdown Normal file
View File

@ -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"
}
```

69
website/source/docs/providers/vault/r/generic_secret.html.md Normal file
View File

@ -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.

4
website/source/layouts/docs.erb
View File

@ -338,6 +338,10 @@
<a href="/docs/providers/ultradns/index.html">UltraDNS</a>
</li>
<li<%= sidebar_current("docs-providers-vault") %>>
<a href="/docs/providers/vault/index.html">Vault</a>
</li>
<li<%= sidebar_current("docs-providers-vcd") %>>
<a href="/docs/providers/vcd/index.html">VMware vCloud Director</a>
</li>

40
website/source/layouts/vault.erb Normal file
View File

@ -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">&laquo; 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 %>