github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/job-specification/vault.mdx (about)

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