website: documentation for the vault provider

website/source/assets/stylesheets/_docs.scss

@@ -48,6 +48,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,

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.

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

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

website/source/layouts/docs.erb

@@ -330,6 +330,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>

website/source/layouts/vault.erb

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