github.com/smintz/nomad@v0.8.3/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 `secret/vault_token` and by injecting a VAULT_TOKEN
    51  environment variable.
    52  
    53  If Nomad is unable to renew the Vault token (perhaps due to a Vault outage or
    54  network error), the client will attempt to retrieve a new Vault token. If successful, the
    55  contents of the secrets file are updated on disk, and action will be taken
    56  according to the value set in the `change_mode` parameter.
    57  
    58  If a `vault` stanza is specified, the [`template`][template] stanza can interact
    59  with Vault as well.
    60  
    61  ## `vault` Parameters
    62  
    63  - `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take
    64    if the Vault token changes. The possible values are:
    65  
    66    - `"noop"` - take no action (continue running the task)
    67    - `"restart"` - restart the task
    68    - `"signal"` - send a configurable signal to the task
    69  
    70  - `change_signal` `(string: "")` - Specifies the signal to send to the task as a
    71    string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the
    72    `change_mode` is `signal`.
    73  
    74  - `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` environment variable
    75    should be set when starting the task.
    76  
    77  - `policies` `(array<string>: [])` - Specifies the set of Vault policies that
    78    the task requires. The Nomad client will generate a Vault token that is
    79    limited to those policies.
    80  
    81  ## `vault` Examples
    82  
    83  The following examples only show the `vault` stanzas. Remember that the
    84  `vault` stanza is only valid in the placements listed above.
    85  
    86  ### Retrieve Token
    87  
    88  This example tells the Nomad client to retrieve a Vault token. The token is
    89  available to the task via the canonical environment variable `VAULT_TOKEN` and
    90  written to disk at `secrets/vault_token`. The resulting token will have the
    91  "frontend" Vault policy attached.
    92  
    93  ```hcl
    94  vault {
    95    policies = ["frontend"]
    96  }
    97  ```
    98  
    99  ### Signal Task
   100  
   101  This example shows signaling the task instead of restarting it.
   102  
   103  ```hcl
   104  vault {
   105    policies = ["frontend"]
   106  
   107    change_mode   = "signal"
   108    change_signal = "SIGINT"
   109  }
   110  ```
   111  
   112  [restart]: /docs/job-specification/restart.html "Nomad restart Job Specification"
   113  [template]: /docs/job-specification/template.html "Nomad template Job Specification"
   114  [vault]: https://www.vaultproject.io/ "Vault by HashiCorp"