github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/vault.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: vault Stanza - Job Specification
     4  description: |-
     5    The "vault" stanza allows the task to specify that it requires a token from a
     6    HashiCorp Vault server. Nomad will automatically retrieve a Vault token for
     7    the task and handle token renewal for the task.
     8  ---
     9  
    10  # `vault` Stanza
    11  
    12  <Placement
    13    groups={[
    14      ['job', 'vault'],
    15      ['job', 'group', 'vault'],
    16      ['job', 'group', 'task', 'vault'],
    17    ]}
    18  />
    19  
    20  The `vault` stanza allows a task to specify that it requires a token from a
    21  [HashiCorp Vault][vault] server. Nomad will automatically retrieve a Vault token
    22  for the task and handle token renewal for the task. If specified at the `group`
    23  level, the configuration will apply to all tasks within the group. If specified
    24  at the `job` level, the configuration will apply to all tasks within the job. If
    25  multiple `vault` stanzas are specified, they are merged with the `task` stanza
    26  taking the highest precedence, then the `group`, then the `job`.
    27  
    28  ```hcl
    29  job "docs" {
    30    group "example" {
    31      task "server" {
    32        vault {
    33          policies = ["cdn", "frontend"]
    34  
    35          change_mode   = "signal"
    36          change_signal = "SIGUSR1"
    37        }
    38      }
    39    }
    40  }
    41  ```
    42  
    43  The Nomad client will make the Vault token available to the task by writing it
    44  to the secret directory at `secrets/vault_token` and by injecting a `VAULT_TOKEN`
    45  environment variable. If the Nomad cluster is [configured](/docs/configuration/vault#namespace)
    46  to use [Vault Namespaces](https://www.vaultproject.io/docs/enterprise/namespaces),
    47  a `VAULT_NAMESPACE` environment variable will be injected whenever `VAULT_TOKEN` is set.
    48  
    49  If Nomad is unable to renew the Vault token (perhaps due to a Vault outage or
    50  network error), the client will attempt to retrieve a new Vault token. If successful, the
    51  contents of the secrets file are updated on disk, and action will be taken
    52  according to the value set in the `change_mode` parameter.
    53  
    54  If a `vault` stanza is specified, the [`template`][template] stanza can interact
    55  with Vault as well.
    56  
    57  ## `vault` Parameters
    58  
    59  - `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take
    60    if the Vault token changes. The possible values are:
    61  
    62    - `"noop"` - take no action (continue running the task)
    63    - `"restart"` - restart the task
    64    - `"signal"` - send a configurable signal to the task
    65  
    66  - `change_signal` `(string: "")` - Specifies the signal to send to the task as a
    67    string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the
    68    `change_mode` is `signal`.
    69  
    70  - `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` and `VAULT_NAMESPACE`
    71    environment variables should be set when starting the task.
    72  
    73  - `namespace` `(string: "")` <EnterpriseAlert inline/> - Specifies the Vault Namespace
    74    to use for the task. The Nomad client will retrieve a Vault token that is scoped to
    75    this particular namespace.
    76  
    77  - `policies` `(array<string>: [])` - Specifies the set of Vault policies that
    78    the task requires. The Nomad client will retrieve 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  ### Vault Namespace
   113  
   114  This example shows specifying a particular Vault namespace for a given task.
   115  
   116  <EnterpriseAlert />
   117  
   118  ```hcl
   119  vault {
   120    policies = ["frontend"]
   121    namespace = "engineering/frontend"
   122  
   123    change_mode   = "signal"
   124    change_signal = "SIGINT"
   125  }
   126  ```
   127  
   128  [restart]: /docs/job-specification/restart "Nomad restart Job Specification"
   129  
   130  [template]: /docs/job-specification/template "Nomad template Job Specification"
   131  
   132  [vault]: https://www.vaultproject.io/ "Vault by HashiCorp"