From d28468d9a338eec403855839a8e31560da19cbef Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Fri, 30 Sep 2016 18:27:05 -0700 Subject: [PATCH] website: documentation for the vault provider --- website/source/assets/stylesheets/_docs.scss | 1 + .../providers/vault/d/generic_secret.html.md | 81 ++++++++++ .../docs/providers/vault/index.html.markdown | 139 ++++++++++++++++++ .../providers/vault/r/generic_secret.html.md | 69 +++++++++ website/source/layouts/docs.erb | 4 + website/source/layouts/vault.erb | 40 +++++ 6 files changed, 334 insertions(+) create mode 100644 website/source/docs/providers/vault/d/generic_secret.html.md create mode 100644 website/source/docs/providers/vault/index.html.markdown create mode 100644 website/source/docs/providers/vault/r/generic_secret.html.md create mode 100644 website/source/layouts/vault.erb diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index af6776ad4..f01dad600 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -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, diff --git a/website/source/docs/providers/vault/d/generic_secret.html.md b/website/source/docs/providers/vault/d/generic_secret.html.md new file mode 100644 index 000000000..59ed9b2fe --- /dev/null +++ b/website/source/docs/providers/vault/d/generic_secret.html.md @@ -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. diff --git a/website/source/docs/providers/vault/index.html.markdown b/website/source/docs/providers/vault/index.html.markdown new file mode 100644 index 000000000..ab523dab5 --- /dev/null +++ b/website/source/docs/providers/vault/index.html.markdown @@ -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" +} +``` + diff --git a/website/source/docs/providers/vault/r/generic_secret.html.md b/website/source/docs/providers/vault/r/generic_secret.html.md new file mode 100644 index 000000000..39c1030ba --- /dev/null +++ b/website/source/docs/providers/vault/r/generic_secret.html.md @@ -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 = <UltraDNS + > + Vault + + > VMware vCloud Director diff --git a/website/source/layouts/vault.erb b/website/source/layouts/vault.erb new file mode 100644 index 000000000..1d7173fff --- /dev/null +++ b/website/source/layouts/vault.erb @@ -0,0 +1,40 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %>