secret block in the job specification

The secret block allows a task to specify that it requires a secret from a specified location. Nomad automatically retrieves the contents of the secret, which you may reference as a variable within the task specification. If specified at the group level, the secret is available to every task within the group. If specified at the job level, every task in the job fetches the secret and is able to interpret it within the task specification.

job "docs" {
  group "example" {
    task "server" {
      secret "my_secret" {
        provider = "vault"
        path     = "path/to/secret"
        config {
          engine = "kv_v2"
        }
      }
    }
  }
}

Nomad parses the key value pairs in a secret and makes them available for variable interpolation in the following format: secret.<secret_name>.<secret_key>. To use the preceding task specification as an example, you would reference the value in the secret key "foo" as ${secret.my_secret.foo}.

Parameters

• provider (string: "") - Specifies the underlying implementation to use in order for Nomad to interact with a specific secret store.

• path (string: "") - Specifies the location of the secret within the given secret store.

• config (block: {}) - Specifies any custom attributes used by built-in providers order to fetch the secret. Only available for built-in vault and nomad providers.

• env (map[string]string) - Specifies any environment variables to pass to a custom plugin provider. Only available for custom providers.

Built-in providers

• nomad - Query variables from Nomad. Nomad uses the task's Workload Identity token in order to fetch the variable, so the task must have the necessary access via ACLs to read the variable.

  Config parameters:

  • namespace (string: "default") - Specifies the namespace where the variable is located.

• vault - Query secrets from Vault. Similar to the template block, making requests to Vault requires a vault token, which is generated via the vault block.

  Config parameters:

  • engine (string: "kv_v2") - Specifies what Vault storage engine to query. Options are kv_v1 and kv_v2.

Custom providers

Nomad extends the provider list via the use of custom providers plugins. Custom providers must implement both the fingerprint and fetch functionality. You must place custom providers in the common_plugin_dir/secrets/ subdirectory. On startup, the Nomad client fingerprints executables in the secrets directory by executing it with the first argument of fingerblock. When using a custom plugin "foo", Nomad looks for an executable "foo" and runs it with the first argument being "fetch", and the second argument being the secret's path parameter. Refer to the plugin authoring guide on secret providers for an example custom provider.

A custom provider should print to stdout a fingerprint response:

{
  "type": "secrets",
  "version": "0.0.1" (use appropriate version)
}

And a valid "fetch" response should have the form:

{
  "result": {
    "key1": "value1",
    "key2": "value2"
  },
  "error": ""
}