From 7ab9c08fa04736d760c1cb8d8952de0498b5851f Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Tue, 3 Jul 2018 17:56:22 -0700 Subject: [PATCH] Added docs on vault API v2 template syntax --- .../docs/job-specification/template.html.md | 39 ++++++++++++++++++- .../docs/vault-integration/index.html.md | 25 ++++++++---- 2 files changed, 55 insertions(+), 9 deletions(-) diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index ed494a4fc..3b25f8777 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -99,11 +99,11 @@ README][ct]. Since Nomad v0.6.0, templates can be read as environment variables. lease is less than or equal to the configured grace, the template will request a new credential. This prevents Vault from revoking the secret at its expiration and the task having a stale secret. - + If the grace is set to a value that is higher than your default TTL or max TTL, the template will always read a new secret. **If secrets are being renewed constantly, decrease the `vault_grace`.** - + If the task defines several templates, the `vault_grace` will be set to the lowest value across all the templates. @@ -225,6 +225,8 @@ README](https://github.com/hashicorp/go-envparse#readme). ## Vault Integration +### PKI Certificate + This example acquires a PKI certificate from Vault in PEM format and stores it into your application's secret directory. ```hcl @@ -240,6 +242,39 @@ EOH } ``` +### Vault KV API v1 + +Under Vault KV API v1, paths start with `secret/`, and the response returns the +raw key/value data. This secret was set using +`vault kv put secret/aws/s3 aws_access_key_id=somekeyid`. + +```hcl + template { + data = < **Note:** Vault integration requires Vault version 0.6.2 or higher. + ## Vault Configuration To use the Vault integration, Nomad servers must be provided a Vault token. This token can either be a root token or a periodic token with permissions to create from a token role. The root token is the easiest way to get started, but we recommend a token role based token for production installations. Nomad servers -will renew the token automatically. **Note that the Nomad clients do not need to +will renew the token automatically. **Note that the Nomad clients do not need to be provided with a Vault token.** ### Root Token Integration @@ -179,14 +181,14 @@ documentation for all possible fields and more complete documentation. * `orphan` - Specifies whether tokens created against this token role will be orphaned and have no parents. Nomad does not enforce the value of this field but understanding the implications of each value is important. - + If set to false, all tokens will be revoked when the Vault token given to Nomad expires. This makes it easy to revoke all tokens generated by Nomad but forces all Nomad servers to use the same Vault token, even through upgrades of Nomad servers. If the Vault token that was given to Nomad and used to generate a tasks token expires, the token used by the task will also be revoked which is not ideal. - + When set to true, the tokens generated for tasks will not be revoked when Nomad's token is revoked. However Nomad will still revoke tokens when the allocation is no longer running, minimizing the lifetime of any task's token. @@ -322,14 +324,21 @@ path "sys/leases/renew" { This is included in Vault's "default" policy beginning with Vault 0.7.1 and is relied upon by Nomad's Vault integration beginning with Nomad 0.6.1. If you're using a newer Nomad version with an older Vault version, your default policy may not automatically include this and you will see "permission denied" errors in your Nomad logs similar to the following: ``` -Code: 403. Errors: -URL: PUT https://vault:8200/v1/sys/leases/renew +Code: 403. Errors: +URL: PUT https://vault:8200/v1/sys/leases/renew * permission denied ``` -## Assumptions +### No Secret Exists + +Vault has two APIs for secrets, [`v1` and `v2`][vault-secrets-version]. Each version +has different paths, and Nomad does not abstract this for you. As such you will +need to specify the path as reflected by Vault's HTTP API, rather than the path +used in the `vault kv` command. + +You can see examples of `v1` and `v2` syntax in the +[template documentation][vault-kv-templates]. -- Vault 0.6.2 or later is needed. [auth]: https://www.vaultproject.io/docs/auth/token.html "Vault Authentication Backend" [config]: /docs/agent/configuration/vault.html "Nomad Vault Configuration Block" @@ -338,3 +347,5 @@ URL: PUT https://vault:8200/v1/sys/leases/renew [vault]: https://www.vaultproject.io/ "Vault by HashiCorp" [vault-spec]: /docs/job-specification/vault.html "Nomad Vault Job Specification" [tokenhierarchy]: https://www.vaultproject.io/docs/concepts/tokens.html#token-hierarchies-and-orphan-tokens "Vault Tokens - Token Hierarchies and Orphan Tokens" +[vault-secrets-version]: https://www.vaultproject.io/docs/secrets/kv/index.html "KV Secrets Engine" +[vault-kv-templates]: /docs/job-specification/template.html#vault-kv-api-v1 "Vault KV API v1"