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