From 0779a5bc106f0462cea63a21df8fea37193fe2ee Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Thu, 6 Oct 2022 13:17:26 -0700 Subject: [PATCH] docs: clarify nomad vars vs vault (#14831) * docs: clarify nomad vars vs vault I think we should make the difference in root key management between Nomad and Vault clear in the concept docs. I didn't see anywhere else in the docs we compared it. I also s/secrets/variables everywhere except the first sentence since the feature is intended to be more generic than secrets. Right now it's more of a compliment to Consul's kv than Vault due to root key handling and featureset. * Update website/content/docs/concepts/variables.mdx Co-authored-by: Tim Gross --- website/content/docs/concepts/variables.mdx | 29 +++++++++++---------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/website/content/docs/concepts/variables.mdx b/website/content/docs/concepts/variables.mdx index 93f290092..ebd89db33 100644 --- a/website/content/docs/concepts/variables.mdx +++ b/website/content/docs/concepts/variables.mdx @@ -7,24 +7,24 @@ description: Learn about the Nomad Variables feature # Nomad Variables Most Nomad workloads need access to config values or secrets. Nomad has a -`template` block to provide such configuration to tasks, but has left the role -of storing that configuration to external services such as [HashiCorp Consul] -and [HashiCorp Vault]. +`template` block to provide such configuration to tasks, but prior to Nomad 1.4 +has left the role of storing that configuration to external services such as +[HashiCorp Consul] and [HashiCorp Vault]. -Nomad Variables provide the option to securely store configuration at file-like -paths directly in Nomad's state store. The contents of these secrets are -encrypted and replicated between servers via raft. Access to secrets is -controlled by ACL policies, and tasks have implicit ACL policies that allow them -to access their own secrets. You can create, read, update, or delete secrets via -the command line, the Nomad API, or in the Nomad web UI. +Nomad Variables provide the option to store configuration at file-like paths +directly in Nomad's state store. The contents of these variables are encrypted +and replicated between servers via raft. Access to variables is controlled by +ACL policies, and tasks have implicit ACL policies that allow them to access +their own variables. You can create, read, update, or delete variables via the +command line, the Nomad API, or in the Nomad web UI. Note that the Variables feature is intended for small pieces of configuration data needed by workloads. Because writing to the Nomad state store uses resources needed by Nomad, it is not well-suited for large or fast-changing data. For example, do not store batch job results as Variables - these should be stored in an external database. Variables are also not intended to be a full -replacement for HashiCorp Vault. If you need powerful options like dynamic -secrets or transit encryption, continue using Vault. +replacement for HashiCorp Vault. Unlike Vault, Nomad stores the root encryption +key on the servers. See [Key Management][] for details. ## ACL for Variables @@ -49,7 +49,7 @@ namespace "dev" { variables { - # full access to secrets in all "project" paths + # full access to variables in all "project" paths path "project/*" { capabilities = ["write", "read", "destroy", "list"] } @@ -129,9 +129,9 @@ namespace "default" { } ``` -You can provide access to additional secrets by creating policies associated +You can provide access to additional variables by creating policies associated with the task's [workload identity]. For example, to give the task above access -to all secrets in the "shared" namespace, you can create the following policy +to all variables in the "shared" namespace, you can create the following policy file: ```hcl @@ -156,6 +156,7 @@ See [Workload Associated ACL Policies] for more details. [HashiCorp Consul]: https://www.consul.io/ [HashiCorp Vault]: https://vaultproject.io +[Key Management]: /docs/operations/key-management [ACL policy specification]: /docs/other-specifications/acl-policy [`template`]: /docs/job-specification/template [workload identity]: /docs/concepts/workload-identity