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 EnterpriseEnterprise

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.