From d8fdae656484bef3249096bf31def3128314c9df Mon Sep 17 00:00:00 2001 From: Charlie Voiselle Date: Wed, 19 Jul 2017 17:58:51 -0400 Subject: [PATCH] More why for the -orphan flag Added a little more explanation about the why for creating the nomad service token with `-orphan` to recusce confusion about the orphan=false in the policy right above the example. --- website/source/docs/vault-integration/index.html.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/website/source/docs/vault-integration/index.html.md b/website/source/docs/vault-integration/index.html.md index 73f98e99a..a1a73a44f 100644 --- a/website/source/docs/vault-integration/index.html.md +++ b/website/source/docs/vault-integration/index.html.md @@ -62,7 +62,7 @@ occur: The token Nomad receives must have the capabilities listed below. An explanation for the use of each capability is given. -``` +```hcl # Allow creating tokens under "nomad-cluster" token role. The token role name # should be updated if "nomad-cluster" is not used. path "auth/token/create/nomad-cluster" { @@ -208,7 +208,7 @@ available for download. The below example assumes Vault is accessible, unsealed and the operator has appropriate permissions. -```shell +``` # Download the policy and token role $ curl https://nomadproject.io/data/vault/nomad-server-policy.hcl -O -s -L $ curl https://nomadproject.io/data/vault/nomad-cluster-role.json -O -s -L @@ -236,9 +236,11 @@ token_renewable true token_policies [default nomad-server] ``` -`-orphan` is included above to prevent revocation of the token when its parent expires. -See the [Vault token hierarchy](https://www.vaultproject.io/docs/concepts/tokens.html#token-hierarchies-and-orphan-tokens) -documentation for more information. +The `-orphan` flag is included when generating the Nomad server token above to prevent revocation of the token when its parent expires. Vault typically creates tokens with a parent-child relationship. When an ancestor token is revoked, all of its descendant tokens—and all of their leases—are revoked as well. + +When generating Nomad's vault token, we need to ensure that revocation of the parent token does not revoke Nomad's token. To prevent this behavior we specify the `-orphan` flag when we create the Nomad service vault token. All other tokens generated by Nomad for jobs will be generated using the policy default of `orphan = false` + +More general information about creating orphan tokens can be found in the Vault documentation, specifically at [Token Hierarchies and Orphan Tokens](https://www.vaultproject.io/docs/concepts/tokens.html#token-hierarchies-and-orphan-tokens). The token can then be set in the server configuration's [vault block][config], as a command-line flag, or via an environment variable.