open-nomad/website/source/guides/namespaces.html.markdown

layout	page_title	sidebar_current	description
guides	Namespaces	guides-namespaces	Nomad Enterprise provides support for namespaces, which allows jobs and their associated objects to be segmented from each other and other users of the cluster.

Namespaces

Nomad Enterprise has support for namespaces, which allows jobs and their associated objects to be segmented from each other and other users of the cluster.

~> Enterprise Only! This functionality only exists in Nomad Enterprise. This is not present in the open source version of Nomad.

Use Case

Namespaces allow a single cluster to be shared by many teams and projects without conflict. Nomad requires job IDs to be unique within namespaces but not across namespaces. This allows each team to operate independently of others.

When combined with ACLs, the isolation of namespaces can be enforced, only allowing designated users access to read or modify the jobs and associated objects in a namespace.

When quotas are applied to a namespace they provide a means to limit resource consumption by the jobs in the namespace. This can prevent a single actor from consuming excessive cluster resources and negatively impacting other teams and applications sharing the cluster.

Namespaced Objects

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.

Working with Namespaces

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

Creating and viewing namespaces:

Namespaces can be interacted with using the nomad namespace subcommand. The following creates and lists the namespaces of a cluster:

$ nomad namespace apply -description "QA instances of webservers" web-qa
Successfully applied namespace "web-qa"!

$ 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

Running jobs

To run a job in a specific namespace, we 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"]
    ...
}

Specifying desired namespace

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:

$ 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 NOMAD_NAMESPACE=web-qa

$ nomad job status
ID         Type     Priority  Status   Submit Date
rails-www  service  50        running  09/17/17 19:17:46 UTC

ACLs

Access to namespaces can be restricted using ACLs. As an example we could create an ACL policy that allows full access to the QA environment for our 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"
}