kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-04 01:15:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added docs on vault API v2 template syntax

Browse Source
This commit is contained in:
Chris Bednarski
2018-07-03 17:56:22 -07:00
parent 22fd627535
commit 7ab9c08fa0
2 changed files with 55 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
website/source/docs/job-specification/template.html.md
View File

@@ -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 = <<EOF
AWS_ACCESS_KEY_ID = "{{with secret "secret/aws/s3"}}{{.Data.aws_access_key_id}}{{end}}"
EOF
}
```
### Vault KV API v2
Under Vault KV API v2, paths start with `secret/data/`, and the response returns
metadata in addition to key/value data. This secret was set using
`vault kv put secret/aws/s3 aws_access_key_id=somekeyid`.
```hcl
template {
data = <<EOF
AWS_ACCESS_KEY_ID = "{{with secret "secret/data/aws/s3"}}{{.Data.data.aws_access_key_id}}{{end}}"
EOF
}
```
Notice the addition of `data` in both the path and the field accessor string.
Additionally, when using the Vault v2 API, the Vault policies applied to your
Nomad jobs will need to grant permissions to `read` under `secret/data/...`
rather than `secret/...`.
## Client Configuration
The `template` block has the following [client configuration

25
website/source/docs/vault-integration/index.html.md
View File

@@ -21,13 +21,15 @@ infrastructure.
Note that in order to use Vault with Nomad, you will need to configure and
install Vault separately from Nomad. Nomad does not run Vault for you.
-> **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"