Nomad
Create and use namespaces
Nomad has support for namespaces, which allow jobs and their associated objects to be segmented from each other and other users of the cluster.
Nomad places all jobs and their derived objects into namespaces. These include jobs, allocations, deployments, and evaluations.
Nomad does not namespace objects that are shared across multiple namespaces. This includes nodes, ACL policies, Sentinel policies, and quota specifications.
In this guide, you'll create and manage a namespace with the CLI. After creating the namespace, you then learn how to deploy and manage a job within that namespace. Finally, you practice securing the namespace.
Create and view a namespace
You can manage namespaces with the nomad namespace
subcommand.
Create the namespace of a cluster.
$ nomad namespace apply -description "QA instances of webservers" web-qa
Successfully applied namespace "web-qa"!
List the namespaces of a cluster.
$ nomad namespace list
Name Description
default Default shared namespace
api-prod Production instances of backend API servers
api-qa QA instances of backend API servers
web-prod Production instances of webservers
web-qa QA instances of webservers
Run a job in a namespace
To run a job in a specific namespace, annotate the job with the namespace
parameter. If omitted, the job will be run in the default
namespace. Below is
an example of running the job in the newly created web-qa
namespace:
job "rails-www" {
## Run in the QA environments
namespace = "web-qa"
## Only run in one datacenter when QAing
datacenters = ["us-west1"]
# ...
}
Use namespaces in the CLI and UI
Nomad CLI
When using commands that operate on objects that are namespaced, the namespace
can be specified either with the flag -namespace
or read from the
NOMAD_NAMESPACE
environment variable.
Request job status using the -namespace
flag.
$ nomad job status -namespace=web-qa
ID Type Priority Status Submit Date
rails-www service 50 running 09/17/17 19:17:46 UTC
Export the NOMAD_NAMESPACE
environment variable.
$ export NOMAD_NAMESPACE=web-qa
Use the exported environment variable to request job status.
$ nomad job status
ID Type Priority Status Submit Date
rails-www service 50 running 09/17/17 19:17:46 UTC
Nomad UI
The Nomad UI provides a drop-down menu to allow operators to select the namespace that they would like to control. The drop-down will appear once there are namespaces defined. It is located in the top section of the left-hand column of the interface under the "WORKLOAD" label.
Secure a namespace
Access to namespaces can be restricted using ACLs. As an example, you could create an ACL policy that allows full access to the QA environment for the web namespaces but restrict the production access by creating the following policy:
# Allow read only access to the production namespace
namespace "web-prod" {
policy = "read"
}
# Allow writing to the QA namespace
namespace "web-qa" {
policy = "write"
}
Consul namespaces Enterprise
Nomad provides integration with Consul Namespaces for
service registrations specified in service
blocks and Consul KV reads in
template
blocks.
By default, Nomad will not specify a Consul namespace on service registrations
or KV store reads, which Consul then implicitly resolves to the "default"
namespace. This default namespace behavior can be modified by setting the
namespace
field in the Nomad agent Consul
configuration block.
For more control over Consul namespaces, Nomad Enterprise supports configuring
the Consul namespace at the group or task level in
the Nomad job spec as well as the -consul-namespace
command line argument for job run
.
The Consul namespace used for a set of group or task service registrations
within a group, as well as template
KV store access is determined from the
following hierarchy from highest to lowest precedence:
group and task configuration: Consul namespace field defined in the job at the task or group level.
job run command option: Consul namespace defined in the
-consul-namespace
command line option on job submission.job run command environment various: Consul namespace defined as the
CONSUL_NAMESPACE
environment variable on job submission.agent configuration: Consul namespace defined in the
namespace
Nomad agent Consul configuration parameter.Consul default: If no Consul namespace options are configured, Consul will automatically make use of the
"default"
namespace.
Refer to the Consul networking integration guide for Consul integration instructions.
Resources
For specific details about working with namespaces, consult the namespace commands and HTTP API documentation.