github.com/ferranbt/nomad@v0.9.3-0.20190607002617-85c449b7667c/website/source/docs/job-specification/vault.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "vault Stanza - Job Specification"
     4  sidebar_current: "docs-job-specification-vault"
     5  description: |-
     6     The "vault" stanza allows the task to specify that it requires a token from a
     7     HashiCorp Vault server. Nomad will automatically retrieve a Vault token for
     8     the task and handle token renewal for the task.
     9  ---
    10  
    11  # `vault` Stanza
    12  
    13  <table class="table table-bordered table-striped">
    14    <tr>
    15      <th width="120">Placement</th>
    16      <td>
    17        <code>job -> **vault**</code>
    18        <br>
    19        <code>job -> group -> **vault**</code>
    20        <br>
    21        <code>job -> group -> task -> **vault**</code>
    22      </td>
    23    </tr>
    24  </table>
    25  
    26  The `vault` stanza allows a task to specify that it requires a token from a
    27  [HashiCorp Vault][vault] server. Nomad will automatically retrieve a Vault token
    28  for the task and handle token renewal for the task. If specified at the `group`
    29  level, the configuration will apply to all tasks within the group. If specified
    30  at the `job` level, the configuration will apply to all tasks within the job. If
    31  multiple `vault` stanzas are specified, they are merged with the `task` stanza
    32  taking the highest precedence, then the `group`, then the `job`.
    33  
    34  ```hcl
    35  job "docs" {
    36    group "example" {
    37      task "server" {
    38        vault {
    39          policies = ["cdn", "frontend"]
    40  
    41          change_mode   = "signal"
    42          change_signal = "SIGUSR1"
    43        }
    44      }
    45    }
    46  }
    47  ```
    48  
    49  The Nomad client will make the Vault token available to the task by writing it
    50  to the secret directory at `secrets/vault_token` and by injecting a `VAULT_TOKEN`
    51  environment variable. If the Nomad cluster is [configured](http://localhost:4567/docs/configuration/vault.html#namespace)
    52  to use [Vault Namespaces](https://www.vaultproject.io/docs/enterprise/namespaces/index.html), 
    53  a `VAULT_NAMESPACE` environment variable will be injected whenever `VAULT_TOKEN` is.
    54  
    55  If Nomad is unable to renew the Vault token (perhaps due to a Vault outage or
    56  network error), the client will attempt to retrieve a new Vault token. If successful, the
    57  contents of the secrets file are updated on disk, and action will be taken
    58  according to the value set in the `change_mode` parameter.
    59  
    60  If a `vault` stanza is specified, the [`template`][template] stanza can interact
    61  with Vault as well.
    62  
    63  ## `vault` Parameters
    64  
    65  - `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take
    66    if the Vault token changes. The possible values are:
    67  
    68    - `"noop"` - take no action (continue running the task)
    69    - `"restart"` - restart the task
    70    - `"signal"` - send a configurable signal to the task
    71  
    72  - `change_signal` `(string: "")` - Specifies the signal to send to the task as a
    73    string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the
    74    `change_mode` is `signal`.
    75  
    76  - `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` and `VAULT_NAMESPACE`
    77    environment variables should be set when starting the task.
    78  
    79  - `policies` `(array<string>: [])` - Specifies the set of Vault policies that
    80    the task requires. The Nomad client will retrieve a Vault token that is
    81    limited to those policies.
    82  
    83  ## `vault` Examples
    84  
    85  The following examples only show the `vault` stanzas. Remember that the
    86  `vault` stanza is only valid in the placements listed above.
    87  
    88  ### Retrieve Token
    89  
    90  This example tells the Nomad client to retrieve a Vault token. The token is
    91  available to the task via the canonical environment variable `VAULT_TOKEN` and
    92  written to disk at `secrets/vault_token`. The resulting token will have the
    93  "frontend" Vault policy attached.
    94  
    95  ```hcl
    96  vault {
    97    policies = ["frontend"]
    98  }
    99  ```
   100  
   101  ### Signal Task
   102  
   103  This example shows signaling the task instead of restarting it.
   104  
   105  ```hcl
   106  vault {
   107    policies = ["frontend"]
   108  
   109    change_mode   = "signal"
   110    change_signal = "SIGINT"
   111  }
   112  ```
   113  
   114  [restart]: /docs/job-specification/restart.html "Nomad restart Job Specification"
   115  [template]: /docs/job-specification/template.html "Nomad template Job Specification"
   116  [vault]: https://www.vaultproject.io/ "Vault by HashiCorp"