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"
}

Learn more about namespaces

For specific details about working with namespaces, consult the namespace commands and HTTP API documentation.