mirror of
https://github.com/kemko/nomad.git
synced 2026-01-09 20:05:42 +03:00
1aa416e2f2
Workflow identities currently support ACL policies being applied to a job ID within a namespace. With this update an ACL policy can be applied to a namespace. This results in the ACL policy being applied to all jobs within the namespace.
202 lines
6.6 KiB
Plaintext
202 lines
6.6 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Workload Identity
|
|
description: Nomad's workload identity feature isolates and uniquely identities each workload so you can associate Access Control List (ACL) policies to jobs. Learn about workload identity claims, claims attributes specific to Nomad Enterprise, default workload ACL policy, and workload identity for Consul and Vault.
|
|
---
|
|
|
|
# Workload Identity
|
|
|
|
This page provides conceptual information about Nomad's workload identity
|
|
feature, which isolates and uniquely identities each workload so you can associate Access Control List (ACL) policies to jobs. Learn about workload identity claims, claims attributes specific to Nomad Enterprise, default workload ACL policy, and workload identity for Consul and Vault.
|
|
|
|
Every workload running in Nomad is given a default identity. When an
|
|
[allocation][] is accepted by the [plan applier][], the leader generates a
|
|
Workload Identity for each task in the allocation. This workload identity is a
|
|
[JSON Web Token (JWT)][] that has been signed by the leader's keyring.
|
|
Additional workload identities may be defined in tasks and services using the
|
|
[`identity`][identity-block] block.
|
|
|
|
## Workload Identity Claims
|
|
|
|
Nomad workload identity for tasks include the following identity claims.
|
|
|
|
```json
|
|
{
|
|
"nomad_namespace": "default",
|
|
"nomad_job_id": "example",
|
|
"nomad_allocation_id": "5c6328f7-48c5-4d03-bada-91ef2e904d0d",
|
|
"nomad_task": "web"
|
|
}
|
|
```
|
|
|
|
Workload identities for Consul services have a claim with the service name
|
|
instead of the task name.
|
|
|
|
```json
|
|
{
|
|
"nomad_namespace": "default",
|
|
"nomad_job_id": "example",
|
|
"nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
|
|
"nomad_service": "example-cache-redis"
|
|
}
|
|
```
|
|
|
|
Workload identities for tasks that use Vault have an additional claim for
|
|
[`vault.role`][jobspec_vault_role] if a role is specified in the job.
|
|
|
|
-> **Note:** This claim will *not* be added if the role is inherited from
|
|
the [agent configuration][vault_role_agent_config] and is not present
|
|
in the Nomad job specification.
|
|
|
|
```json
|
|
{
|
|
"nomad_namespace": "default",
|
|
"nomad_job_id": "example",
|
|
"nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
|
|
"nomad_service": "example-cache-redis",
|
|
"vault_role": "nomad-jwt-login"
|
|
}
|
|
```
|
|
|
|
### Nomad Enterprise <EnterpriseAlert inline />
|
|
|
|
In Nomad Enterprise, tasks and services with a [`consul`][jobspec_consul] block
|
|
that defines a [`namespace`][jobspec_consul_ns] value, or inside a `group`
|
|
block that does it, have an additional claim called `consul_namespace`.
|
|
|
|
```json
|
|
{
|
|
"consul_namespace": "prod",
|
|
"nomad_namespace": "default",
|
|
"nomad_job_id": "example",
|
|
"nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
|
|
"nomad_service": "example-cache-redis"
|
|
}
|
|
```
|
|
|
|
Similarly, tasks with a [`vault.namespace`][jobspec_vault_ns] value have the additional claim
|
|
`vault_namespace`.
|
|
|
|
```json
|
|
{
|
|
"nomad_namespace": "default",
|
|
"nomad_job_id": "example",
|
|
"nomad_allocation_id": "8623ac7a-28ba-20c3-24a6-e615a39bbbf3",
|
|
"nomad_service": "example-cache-redis",
|
|
"vault_namespace": "prod"
|
|
}
|
|
```
|
|
|
|
## Workload Identity for Nomad
|
|
|
|
While Nomad always creates and uses workload identities internally, the JWT is
|
|
not exposed to tasks by default.
|
|
|
|
To expose Workload Identity to tasks, add an [`identity`][identity-block] block
|
|
to your jobspec:
|
|
|
|
```hcl
|
|
task "example" {
|
|
|
|
identity {
|
|
# Expose Workload Identity in NOMAD_TOKEN env var
|
|
env = true
|
|
|
|
# Expose Workload Identity in ${NOMAD_SECRETS_DIR}/nomad_token file
|
|
file = true
|
|
}
|
|
|
|
}
|
|
```
|
|
|
|
### Default Workload ACL Policy
|
|
|
|
By default, a Workload Identity has access to a implicit ACL policy. This policy
|
|
grants access to Nomad Variables associated with the job, group, and task, as
|
|
described in [Task Access to Variables][]. The implicit policy also allows
|
|
access to list or read any Nomad service registration as with the [List Services
|
|
API][] or [Read Service API][].
|
|
|
|
### Workload Associated ACL Policies
|
|
|
|
You can associate additional ACL policies with workload identities by passing
|
|
the `-job`, `-group`, and `-task` flags to `nomad acl policy apply`. When Nomad
|
|
resolves a workload identity claim, it will automatically include policies that
|
|
match. If no matching policies exist, the workload identity does not have any
|
|
additional capabilities.
|
|
|
|
For example, to allow a workload access to secrets from the namespace "shared",
|
|
you can create the following policy file:
|
|
|
|
```hcl
|
|
namespace "shared" {
|
|
variables {
|
|
path "*" {
|
|
capabilities = ["read"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
You can then apply this policy to a specific task:
|
|
|
|
```shell-session
|
|
nomad acl policy apply \
|
|
-namespace default -job example -group cache -task redis \
|
|
redis-policy ./policy.hcl
|
|
```
|
|
|
|
You can also apply this policy to all tasks in the group by omitting the `-task`
|
|
flag:
|
|
|
|
```shell-session
|
|
nomad acl policy apply \
|
|
-namespace default -job example -group cache \
|
|
redis-policy ./policy.hcl
|
|
```
|
|
|
|
You can apply this policy to all groups in the job by omitting both the
|
|
`-group` and `-task` flag:
|
|
|
|
```shell-session
|
|
nomad acl policy apply \
|
|
-namespace default -job example \
|
|
redis-policy ./policy.hcl
|
|
```
|
|
|
|
And you can apply this policy to all jobs in the namespace by omitting the
|
|
`-job`, `-group`, and `-task` flag:
|
|
|
|
```shell-session
|
|
nomad acl policy apply \
|
|
-namespace default redis-policy ./policy.hcl
|
|
```
|
|
|
|
### Task API
|
|
|
|
It can be convenient to combine workload identity with Nomad's [Task API]
|
|
[taskapi] for enabling tasks to access the Nomad API.
|
|
|
|
## Workload Identity for Consul and Vault
|
|
|
|
Consul and Vault can be configured to accept workload identities from Nomad for
|
|
authentication. Refer to the [Consul][consul_int] and [Vault][vault_int]
|
|
integration pages for more information.
|
|
|
|
[allocation]: /nomad/docs/glossary#allocation
|
|
[identity-block]: /nomad/docs/job-specification/identity
|
|
[jobspec_consul]: /nomad/docs/job-specification/consul
|
|
[jobspec_consul_ns]: /nomad/docs/job-specification/consul#namespace
|
|
[jobspec_vault_ns]: /nomad/docs/job-specification/vault#namespace
|
|
[jobspec_vault_role]: /nomad/docs/job-specification/vault#role
|
|
[vault_role_agent_config]: /nomad/docs/configuration/vault#create_from_role
|
|
[plan applier]: /nomad/docs/concepts/scheduling/scheduling
|
|
[JSON Web Token (JWT)]: https://datatracker.ietf.org/doc/html/rfc7519
|
|
[Task Access to Variables]: /nomad/docs/concepts/variables#task-access-to-variables
|
|
[List Services API]: /nomad/api-docs/services#list-services
|
|
[Read Service API]: /nomad/api-docs/services#read-service
|
|
[windows]: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/
|
|
[taskapi]: /nomad/api-docs/task-api
|
|
[consul_int]: /nomad/docs/integrations/consul-integration
|
|
[vault_int]: /nomad/docs/integrations/vault-integration
|