---
layout: docs
page_title: Create and use namespaces
description: |-
  Segment jobs and their associated objects from the jobs of other users of
  the cluster using Nomad namespaces.
---

# 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][acls], [Sentinel policies], and
[quota specifications][quotas].

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.

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

List the namespaces of a cluster.

```shell-session
$ 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:

```hcl
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.

```shell-session
$ 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.

```shell-session
$ export NOMAD_NAMESPACE=web-qa
```

Use the exported environment variable to request job status.

```shell-session
$ 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.

[![An image of the Nomad UI showing the location of the namespace drop-down.
The drop-down is open showing the "Default Namespace" option and an option for a
"web-qa" namespace.][img_ui_ns_dropdown]][img_ui_ns_dropdown]

## 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:

```hcl
# 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 <EnterpriseAlert inline/>

@include 'consul-namespaces.mdx'

Refer to the [Consul networking integration
guide](/nomad/docs/networking/consul) for Consul integration instructions.

## Resources

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


[acls]: /nomad/docs/secure/acl
[http api]: /nomad/api-docs/namespaces
[img_ui_ns_dropdown]: /img/govern/nomad-ui-namespace-dropdown.png
[namespace commands]: /nomad/commands/namespace
[quotas]: /nomad/docs/govern/resource-quotas
[sentinel policies]: /nomad/docs/govern/sentinel