From 817805bdcf084b5fac12a4968e76024a243ad411 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Fri, 27 Jan 2017 12:24:59 -0800 Subject: [PATCH] new vault docs --- ...rver-role.json => nomad-cluster-role.json} | 4 +- .../source/data/vault/nomad-server-policy.hcl | 39 ++-- .../docs/agent/configuration/vault.html.md | 5 + .../docs/vault-integration/index.html.md | 183 ++++++++++++------ 4 files changed, 161 insertions(+), 70 deletions(-) rename website/source/data/vault/{nomad-server-role.json => nomad-cluster-role.json} (56%) diff --git a/website/source/data/vault/nomad-server-role.json b/website/source/data/vault/nomad-cluster-role.json similarity index 56% rename from website/source/data/vault/nomad-server-role.json rename to website/source/data/vault/nomad-cluster-role.json index 32284d389..37728363f 100644 --- a/website/source/data/vault/nomad-server-role.json +++ b/website/source/data/vault/nomad-cluster-role.json @@ -1,7 +1,7 @@ { - "allowed_policies": "nomad-server", + "disallowed_policies": "nomad-server", "explicit_max_ttl": 0, - "name": "nomad-server", + "name": "nomad-cluster", "orphan": false, "period": 259200, "renewable": true diff --git a/website/source/data/vault/nomad-server-policy.hcl b/website/source/data/vault/nomad-server-policy.hcl index d1190af7e..bd91b852d 100644 --- a/website/source/data/vault/nomad-server-policy.hcl +++ b/website/source/data/vault/nomad-server-policy.hcl @@ -1,20 +1,35 @@ -# Allow creating tokens under the role -path "auth/token/create/nomad-server" { +# Allow creating tokens under "nomad-cluster" role. The role name should be +# updated if "nomad-cluster" is not used. +path "auth/token/create/nomad-cluster" { capabilities = ["update"] } -# Allow looking up the role -path "auth/token/roles/nomad-server" { +# Allow looking up "nomad-cluster" role. The role name should be updated if +# "nomad-cluster" is not used. +path "auth/token/roles/nomad-cluster" { capabilities = ["read"] } -# Allow looking up incoming tokens to validate they have permissions to -# access the tokens they are requesting -path "auth/token/lookup/*" { - capabilities = ["read"] -} - -# Allow revoking tokens that should no longer exist -path "/auth/token/revoke-accessor/*" { +# Allow looking up incoming tokens to validate they have permissions to access +# the tokens they are requesting. This is only required if +# `allow_unauthenticated` is set to false. +path "auth/token/lookup" { + capabilities = ["update"] +} + +# Allow revoking tokens that should no longer exist. This allows revoking +# tokens for dead tasks. +path "auth/token/revoke-accessor" { + capabilities = ["update"] +} + +# Allow checking the capabilities of our own token. This is used to validate the +# token upon startup. +path "/sys/capabilities-self" { + capabilities = ["update"] +} + +# Allow our own token to be renewed. +path "auth/token/renew-self" { capabilities = ["update"] } diff --git a/website/source/docs/agent/configuration/vault.html.md b/website/source/docs/agent/configuration/vault.html.md index 9d1e012b2..e9ded6d79 100644 --- a/website/source/docs/agent/configuration/vault.html.md +++ b/website/source/docs/agent/configuration/vault.html.md @@ -119,6 +119,11 @@ vault { # should set the VAULT_TOKEN environment variable when starting the Nomad # agent token = "debecfdc-9ed7-ea22-c6ee-948f22cdd474" + + # Setting the create_from_role option causes Nomad to create tokens for tasks + # via the provided role. This allows the role to manage what policies are + # allowed and disallowed for use by tasks. + create_from_role = "nomad-server" } ``` diff --git a/website/source/docs/vault-integration/index.html.md b/website/source/docs/vault-integration/index.html.md index 7baff34b0..a57771090 100644 --- a/website/source/docs/vault-integration/index.html.md +++ b/website/source/docs/vault-integration/index.html.md @@ -13,7 +13,7 @@ Many workloads require access to tokens, passwords, certificates, API keys, and other secrets. To enable secure, auditable and easy access to your secrets, Nomad integrates with HashiCorp's [Vault][]. Nomad servers and clients coordinate with Vault to derive a Vault token that has access to only the Vault -policies the tasks needs. Nomad clients make the token avaliable to the task and +policies the tasks needs. Nomad clients make the token available to the task and handle the tokens renewal. Further, Nomad's [`template` block][template] can retrieve secrets from Vault making it easier than ever to secure your infrastructure. @@ -24,76 +24,144 @@ install Vault separately from Nomad. Nomad does not run Vault for you. ## 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 token from a role. The root token is the -easiest way to get started, but we recommend a role-based token for production -installations. Nomad servers will renew the token automatically. +token can either be a root token or a token with permissions to create from a +role. The root token is the easiest way to get started, but we recommend a +role-based token for production installations. Nomad servers will renew the +token automatically. -### Root Token +### Root Token Integration If Nomad is given a [root token](https://www.vaultproject.io/docs/concepts/tokens.html#root-tokens), no further configuration is needed as Nomad can derive a token for jobs using any Vault policies. -### Role based Token +### Role based Integration Vault's [Token Authentication Backend][auth] supports a concept called "roles". Roles allow policies to be grouped together and token creation to be delegated to a trusted service such as Nomad. By creating a role, the set of policies that tasks managed by Nomad can access may be limited compared to giving Nomad a root -token. +token. Roles allow both whitelist and blacklist management of polcies accessible +to the role. -When given a non-root token, Nomad queries the token to determine the role it -was generated from. It will then derive tokens for jobs based on that role. -Nomad expects the role to be created with several properties described below -when creating the role with the Vault endpoint `/auth/token/roles/`: +To configure Nomad and Vault to create tokens against a role, the following must +occur: + + 1. Create a set of Vault policies that can be used to generate a token for the + Nomad Servers that allow them to create from a role and manage created + tokens within the cluster. The required policies are described below. + + 2. Create a Vault role with the configuration described below. + + 3. Configure Nomad to use the created role. + + 4. Give Nomad servers a token with the policies created from step 1. The token + must also be periodic. + +#### Required Vault Policies + +The token Nomad receives must have the capabilities listed below. An explanation +for the use of each capability is given. + +``` +# Allow creating tokens under "nomad-cluster" role. The role name should be +# updated if "nomad-cluster" is not used. +path "auth/token/create/nomad-cluster" { + capabilities = ["update"] +} + +# Allow looking up "nomad-cluster" role. The role name should be updated if +# "nomad-cluster" is not used. +path "auth/token/roles/nomad-cluster" { + capabilities = ["read"] +} + +# Allow looking up incoming tokens to validate they have permissions to access +# the tokens they are requesting. This is only required if +# `allow_unauthenticated` is set to false. +path "auth/token/lookup" { + capabilities = ["update"] +} + +# Allow revoking tokens that should no longer exist. This allows revoking +# tokens for dead tasks. +path "auth/token/revoke-accessor" { + capabilities = ["update"] +} + +# Allow checking the capabilities of our own token. This is used to validate the +# token upon startup. +path "/sys/capabilities-self" { + capabilities = ["update"] +} + +# Allow our own token to be renewed. +path "auth/token/renew-self" { + capabilities = ["update"] +} +``` + +The above [`nomad-server` policy](/data/vault/nomad-server-policy.hcl) is +available for download. Below is an example of writing this policy to Vault: + +``` +# Download the policy +$ curl https://nomadproject.io/data/vault/nomad-server-policy.hcl -O -s -L + +# Write the policy to Vault +$ vault policy-write nomad-server nomad-server-policy.hcl +``` + +#### Vault Role Configuration + +A Vault role must be created for use by Nomad. The role can be used to manage +what Vault policies are accessible by jobs submitted to Nomad. The policies can +be managed as a whitelist by using `allowed_policies` in the role definition or +as a blacklist by using `disallowed_policies`. + +If using `allowed_policies`, task's may only request Vault policies that are in +the list. If `disallowed_policies` is used, task may request any policy that is +not in the `disallowed_policies` list. There are tradeoffs to both approaches +but generally it is easier to use the blacklist approach and add policies that +you would not like tasks to have access to into the `disallowed_policies` list. + +An example role definition is given below: ```json { - "allowed_policies": "", + "disallowed_policies": "nomad-server", "explicit_max_ttl": 0, - "name": "nomad", + "name": "nomad-cluster", "orphan": false, "period": 259200, "renewable": true } ``` -#### Parameters: +##### Role Requirements + +Nomad checks that role's have an appropriate configuration for use by the +cluster. Fields that are checked are documented below as well as descriptions of +the important fields. See Vault's [Token Authentication Backend][auth] +documentation for all possible fields and more complete documentation. * `allowed_policies` - Specifies the list of allowed policies as a - comma-seperated string This list should contain all policies that jobs running - under Nomad should have access to. Further, the list must contain one or more - policies that gives Nomad the following permissions: + comma-seperated string. This list should contain all policies that jobs running + under Nomad should have access to. - ```hcl - # Allow creating tokens under the role - path "auth/token/create/nomad-server" { - capabilities = ["update"] - } - - # Allow looking up the role - path "auth/token/roles/nomad-server" { - capabilities = ["read"] - } - - # Allow looking up incoming tokens to validate they have permissions to - # access the tokens they are requesting - path "auth/token/lookup/*" { - capabilities = ["read"] - } - - # Allow revoking tokens that should no longer exist - path "/auth/token/revoke-accessor/*" { - capabilities = ["update"] - } - ``` +* `disallowed_policies` - Specifies the list of disallowed policies as a + comma-seperated string. This list should contain all policies that jobs running + under Nomad should **not** have access to. The policy created above that + grants Nomad the ability to generate tokens from the role should be included + in list of disallowed policies. This prevents tokens created by Nomad from + generating new tokens with different policies than those granted by Nomad. * `explicit_max_ttl` - Specifies the max TTL of a token. Must be set to `0` to allow periodic tokens. * `name` - Specifies the name of the policy. We recommend using the name - `nomad-server`. If a different name is chosen, replace the role in the above + `nomad-cluster`. If a different name is chosen, replace the role in the above policy. * `orphan` - Specifies whether tokens created againsts this role will be @@ -108,14 +176,23 @@ when creating the role with the Vault endpoint `/auth/token/roles/`: * `renewable` - Specifies whether created tokens are renewable. Must be set to `true`. This allows Nomad to renew tokens for tasks. -See Vault's [Token Authentication Backend][auth] documentation for all possible -fields and more complete documentation. +The above [`nomad-cluster` role](/data/vault/nomad-cluster-role.hcl) is +available for download. Below is an example of writing this role to Vault: + +``` +# Download the role +$ curl https://nomadproject.io/data/vault/nomad-cluster-role.json -O -s -L + +# Create the role with Vault +$ vault write /auth/token/roles/nomad-cluster @nomad-cluster-role.json +``` + #### Example Configuration To make getting started easy, the basic [`nomad-server` policy](/data/vault/nomad-server-policy.hcl) and -[role](/data/vault/nomad-server-role.json) described above are available for +[role](/data/vault/nomad-cluster-role.json) described above are available for download. The below example assumes Vault is accessible, unsealed and the the operator has @@ -124,17 +201,13 @@ appropriate permissions. ```shell # Download the policy and role $ curl https://nomadproject.io/data/vault/nomad-server-policy.hcl -O -s -L -$ curl https://nomadproject.io/data/vault/nomad-server-role.json -O -s -L +$ curl https://nomadproject.io/data/vault/nomad-cluster-role.json -O -s -L # Write the policy to Vault $ vault policy-write nomad-server nomad-server-policy.hcl -# Edit the role to add any policies that you would like to be accessible to -# Nomad jobs in the list of allowed_policies. Do not remove `nomad-server`. -$ editor nomad-server-role.json - # Create the role with Vault -$ vault write /auth/token/roles/nomad-server @nomad-server-role.json +$ vault write /auth/token/roles/nomad-cluster @nomad-cluster-role.json ``` #### Retrieving the Role based Token @@ -143,23 +216,19 @@ After the role is created, a token suitable for the Nomad servers may be retrieved by issuing the following Vault command: ``` -$ vault token-create -role nomad-server +$ vault token-create -policy nomad-server -period 72h Key Value --- ----- token f02f01c2-c0d1-7cb7-6b88-8a14fada58c0 token_accessor 8cb7fcb3-9a4f-6fbf-0efc-83092bb0cb1c token_duration 259200s token_renewable true -token_policies [] +token_policies [default nomad-server] ``` The token can then be set in the server configuration's [vault block][config], as a command-line flag, or via an environment variable. -``` -$ nomad agent -config /path/to/config -vault-token=f02f01c2-c0d1-7cb7-6b88-8a14fada58c0 -``` - ``` $ VAULT_TOKEN=f02f01c2-c0d1-7cb7-6b88-8a14fada58c0 nomad agent -config /path/to/config ``` @@ -185,10 +254,12 @@ the reasons the token is invalid and disable Vault integration. - Vault 0.6.2 or later is needed. +# XXX - Nomad is given either a root token or a token created from an approriate role. [auth]: https://www.vaultproject.io/docs/auth/token.html "Vault Authentication Backend" -[config]: /docs/agent/configuration/vault.html "Nomad Vault configuration block" +[config]: /docs/agent/configuration/vault.html "Nomad Vault Configuration Block" +[createfromrole]: /docs/agent/configuration/vault.html#create_from_role "Nomad vault create_from_role Configuration Flag" [template]: /docs/job-specification/template.html "Nomad template Job Specification" [vault]: https://www.vaultproject.io/ "Vault by HashiCorp" [vault-spec]: /docs/job-specification/vault.html "Nomad Vault Job Specification"