The ACL system is designed to be intuitive, high-performance, and to provide administrative insight. At the highest level, there are four major components to the ACL system: tokens, policies, and capabilities. The components are illustrated in the diagram below.
NOTE: A similar, interactive lab is also available for this entire collection if you do not have a Nomad environment to perform the steps described in this tutorial. Click the Show Tutorial button to launch the lab experience.
»Core objects overview
Tokens - Requests to Nomad are authenticated using a bearer token. Each ACL token has a public Accessor ID which is used to name a token and a Secret ID which is used to make requests to Nomad. The Secret ID is provided using a request header (
X-Nomad-Token) and is used to authenticate the caller. Tokens are either
managementtokens are effectively "root" in the system and can perform any operation. The
clienttokens are associated with one or more ACL policies which grant specific capabilities.
Policies - Policies consist of a set of rules defining the capabilities or actions to be granted. For example, a "readonly" policy might only grant the ability to list and inspect running jobs, but not to submit new ones. No permissions are granted by default, making Nomad a default-deny system.
- Rules - Policies are comprised of one or more rules. The rules define the capabilities of a Nomad ACL token for accessing the objects in a Nomad cluster, objects like namespaces, node, agent, operator, quota, etc. The full set of rules are discussed in a later section.
Capabilities - Capabilities are the set of actions that can be performed. This includes listing jobs, submitting jobs, querying nodes, etc. A
managementtoken is granted all capabilities, while
clienttokens are granted specific capabilities via ACL policies. The full set of capabilities is discussed in the rule specifications.
An ACL policy is a named set of rules. Each policy must have a unique name, an optional description, and a rule set. A client ACL token can be associated with multiple policies; a request is allowed if any of the associated policies grant the capability. Management tokens cannot be associated with policies because they are granted all capabilities.
anonymous policy can be defined to grant capabilities to anonymous
requests. An anonymous request is a request made to Nomad without the
X-Nomad-Token header specified. This can be used to allow anonymous users to
list jobs and view their status, while requiring authenticated requests to
submit new jobs or modify existing jobs. By default, there is no
policy set meaning all anonymous requests are denied.
ACL tokens are used to authenticate requests and determine if the caller is
authorized to perform an action. Each ACL token has a public Accessor ID which
is used to identify the token, a Secret ID which is used to make requests to
Nomad, and an optional human readable name. All
client type tokens are
associated with one or more policies and can perform an action if any
associated policy allows it. Tokens can be associated with policies which do not
exist, which are the equivalent of granting no capabilities. The
type tokens cannot be associated with policies, but can perform any action.
When ACL tokens are created, they can be optionally marked as
causes them to be created in the authoritative region and replicated to all
other regions. Otherwise, tokens are created locally in the region the request
was made and not replicated. Local tokens cannot be used for cross-region
requests since they are not replicated between regions.
»Rules and scope
The following table summarizes the rules that are available for constructing ACL policies:
|agent||Utility operations in the Agent API|
|host_volume||Host Volume related operations|
|namespace||Job related operations by namespace|
|node||Node-level catalog operations|
|operator||Cluster-level operations in the Operator API|
|plugin||CSI Plugin related operations|
|quota||Quota specification related operations|
Constructing policies from these rules is covered in detail in the "Nomad ACL Policy Concepts" tutorial later in this collection.
Nomad supports multi-datacenter and multi-region configurations. A single region is able to service multiple datacenters, and all servers in a region replicate their state between each other. In a multi-region configuration, there is a set of servers per region. Each region operates independently and is loosely coupled to allow jobs to be scheduled in any region and requests to flow transparently to the correct region.
When ACLs are enabled, Nomad depends on an "authoritative region" to act as a
single source of truth for ACL policies and global ACL tokens. The authoritative
region is configured in the
server stanza of agents, and all regions must
share a single authoritative source. Any ACL policies or global ACL tokens are
created in the authoritative region first. All other regions replicate ACL
policies and global ACL tokens to act as local mirrors. This allows policies to
be administered centrally, and for enforcement to be local to each region for
Global ACL tokens are used to allow cross-region requests. Standard ACL tokens are created in a single target region and not replicated. This means if a request takes place between regions, global tokens must be used so that both regions will have the token registered.