|
1 | 1 | --- |
2 | 2 | layout: docs |
3 | | -page_title: Nomad Variables |
| 3 | +page_title: Nomad variables |
4 | 4 | description: Nomad's variables feature lets you store and use encrypted configuration data in your job specifications. Learn how Access Control List (ACL) policies restrict access to variables within a namespace, how a job task's workload identity grants access to variables, and how locking a variable blocks access to that variable. |
5 | 5 | --- |
6 | 6 |
|
7 | | -# Nomad Variables |
| 7 | +# Nomad variables |
8 | 8 |
|
9 | 9 | This page contains conceptual information about the Nomad variables feature, |
10 | 10 | which lets you store and use encrypted configuration data in your job |
11 | 11 | specifications. Learn how Access Control List (ACL) policies restrict access to variables within a namespace, how a job task's workload identity grants access to variables, and how locking a variable blocks access to that variable. |
12 | 12 |
|
13 | | -Most Nomad workloads need access to config values or secrets. Nomad has a |
14 | | -`template` block to [provide such configuration to tasks](/nomad/docs/job-specification/template#nomad-variables), |
15 | | -but prior to Nomad 1.4 has left the role of storing that configuration to |
16 | | -external services such as [HashiCorp Consul] and [HashiCorp Vault]. |
| 13 | +## Introduction |
17 | 14 |
|
18 | | -Nomad variables provide the option to store configuration at file-like paths |
19 | | -directly in Nomad's state store. [Access these variables](/nomad/docs/job-specification/template#nomad-variables) directly from |
20 | | -your task templates. The contents of these variables are encrypted |
21 | | -and replicated between servers via raft. Access to variables is controlled by |
| 15 | +Most Nomad workloads need access to configuration values or secrets. Nomad has a |
| 16 | +`template` block to [provide these values to |
| 17 | +tasks](/nomad/docs/job-specification/template#nomad-variables). Nomad variables |
| 18 | +provide the option to store configuration at file-like paths |
| 19 | +directly in Nomad's state store so that you can access these variables directly from |
| 20 | +your task templates. Nomad encrypts and replicates the contents of these variables between servers with Raft communication. Access to variables is controlled by |
22 | 21 | ACL policies, and tasks have implicit ACL policies that allow them to access |
23 | 22 | their own variables. You can create, read, update, or delete variables via the |
24 | 23 | command line, the Nomad API, or in the Nomad web UI. |
25 | 24 |
|
26 | 25 | Note that the variables feature is intended for small pieces of configuration |
27 | 26 | data needed by workloads. Because writing to the Nomad state store uses |
28 | 27 | resources needed by Nomad, it is not well-suited for large or fast-changing |
29 | | -data. For example, do not store batch job results as variables - these should be |
| 28 | +data. For example, do not store batch job results as variables. These should be |
30 | 29 | stored in an external database. Variables are also not intended to be a full |
31 | 30 | replacement for HashiCorp Vault. Unlike Vault, Nomad stores the root encryption |
32 | | -key on the servers. See [Key Management][] for details. |
| 31 | +key on the servers. Refer to [Key Management][] for details. |
33 | 32 |
|
34 | | -## ACL for Variables |
| 33 | +## Policies |
35 | 34 |
|
36 | 35 | Every variable belongs to a specific Nomad namespace. ACL policies can restrict |
37 | 36 | access to variables within a namespace on a per-path basis, using a list of |
38 | | -`path` blocks, located under `namespace.variables`. See the [ACL policy |
39 | | -specification] docs for details about the syntax and structure of an ACL policy. |
| 37 | +`path` blocks, located under `namespace.variables`. Refer to the [ACL policy |
| 38 | +specification] for details about the syntax and structure of an ACL policy. |
40 | 39 |
|
41 | | -Path definitions may also include wildcard symbols, also called globs, allowing |
| 40 | +Path definitions may also include a wildcard symbol that allows |
42 | 41 | a single path policy definition to apply to a set of paths within that |
43 | | -namespace. For example, the policy below allows full access to variables at all |
44 | | -paths in the "dev" namespace that are prefixed with "project/" (including child |
45 | | -paths) but only read access to paths prefixed with "system/". Note that the glob |
| 42 | +namespace. |
| 43 | + |
| 44 | +In the following example, the policy allows full access to variables at all |
| 45 | +paths in the `dev` namespace that are prefixed with `project/`, including child |
| 46 | +paths, but only read access to paths prefixed with `system/`. Note that the wildcard |
46 | 47 | can match an empty string and all other characters. This policy grants read |
47 | | -access to paths prefixed with "system/" but not a path named "system" (without a |
| 48 | +access to paths prefixed with `system/` but not a path named `system` (without a |
48 | 49 | trailing slash). |
49 | 50 |
|
50 | 51 | ```hcl |
@@ -76,7 +77,7 @@ The available capabilities for variables are as follows: |
76 | 77 | | list | List the metadata but not contents of variables at this path. | |
77 | 78 | | destroy | Delete variables at this path. | |
78 | 79 |
|
79 | | -## Task Access to Variables |
| 80 | +## Task access to variables |
80 | 81 |
|
81 | 82 | Tasks can access variables with the [`template`] block or using the [Task API]. |
82 | 83 | The [workload identity] for each task grants it automatic read and list access to |
@@ -210,7 +211,7 @@ and no renew or release calls were made, the variable will remain locked for at |
210 | 211 | least the lock delay duration, to avoid a possible split-brain situation, where |
211 | 212 | there are two holders at the same time. |
212 | 213 |
|
213 | | -### Leader election backed by Nomad Variable Locks |
| 214 | +### Leader election backed by Nomad variable locks |
214 | 215 |
|
215 | 216 | For some applications, like HDFS or the Nomad Autoscaler, it is necessary to |
216 | 217 | have multiple instances running to ensure redundancy in case of a failure, but |
|
0 commit comments