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

---
layout: "guides"
page_title: "Namespaces"
sidebar_current: "guides-namespaces"
description: |-
  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](/guides/acl.html), [Sentinel
policies](/guides/sentinel-policy.html), and quota specifications.

## Working with Namespaces

For specific details about working with namespaces, see the [namespace
commands](/docs/commands/namespace.html) and [HTTP API](/api/namespaces.html)
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 ommitted, 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 environmet
    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](/guides/acl.html). 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"
}
```