github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/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  - `namespace` `(string: "")` <EnterpriseAlert inline/> - Specifies the Vault Namespace
    75    to use for the task. The Nomad client will retrieve a Vault token that is scoped to
    76    this particular namespace.
    77  
    78  - `policies` `(array<string>: [])` - Specifies the set of Vault policies that
    79    the task requires. The Nomad client will retrieve a Vault token that is
    80    limited to those policies.
    81  
    82  ## `vault` Examples
    83  
    84  The following examples only show the `vault` stanzas. Remember that the
    85  `vault` stanza is only valid in the placements listed above.
    86  
    87  ### Retrieve Token
    88  
    89  This example tells the Nomad client to retrieve a Vault token. The token is
    90  available to the task via the canonical environment variable `VAULT_TOKEN` and
    91  written to disk at `secrets/vault_token`. The resulting token will have the
    92  "frontend" Vault policy attached.
    93  
    94  ```hcl
    95  vault {
    96    policies = ["frontend"]
    97  }
    98  ```
    99  
   100  ### Signal Task
   101  
   102  This example shows signaling the task instead of restarting it.
   103  
   104  ```hcl
   105  vault {
   106    policies = ["frontend"]
   107  
   108    change_mode   = "signal"
   109    change_signal = "SIGINT"
   110  }
   111  ```
   112  
   113  ### Vault Namespace
   114  
   115  This example shows specifying a particular Vault namespace for a given task.
   116  
   117  <EnterpriseAlert />
   118  
   119  ```hcl
   120  vault {
   121    policies = ["frontend"]
   122    namespace = "engineering/frontend"
   123  
   124    change_mode   = "signal"
   125    change_signal = "SIGINT"
   126  }
   127  ```
   128  
   129  [restart]: /docs/job-specification/restart 'Nomad restart Job Specification'
   130  [template]: /docs/job-specification/template 'Nomad template Job Specification'
   131  [vault]: https://www.vaultproject.io/ 'Vault by HashiCorp'