github.com/smintz/nomad@v0.8.3/website/source/guides/namespaces.html.markdown (about) 1 --- 2 layout: "guides" 3 page_title: "Namespaces" 4 sidebar_current: "guides-namespaces" 5 description: |- 6 Nomad Enterprise provides support for namespaces, which allow jobs and their 7 associated objects to be segmented from each other and other users of the 8 cluster. 9 --- 10 11 # Namespaces 12 13 [Nomad Enterprise](https://www.hashicorp.com/products/nomad/) has support for 14 namespaces, which allow jobs and their associated objects to be segmented from 15 each other and other users of the cluster. 16 17 ~> **Enterprise Only!** This functionality only exists in Nomad Enterprise. 18 This is not present in the open source version of Nomad. 19 20 ## Use Case 21 22 Namespaces allow a single cluster to be shared by many teams and projects 23 without conflict. Nomad requires job IDs to be unique within namespaces but not 24 across namespaces. This allows each team to operate independently of others. 25 26 When combined with ACLs, the isolation of namespaces can be enforced, only 27 allowing designated users access to read or modify the jobs and associated 28 objects in a namespace. 29 30 When [resource quotas](/guides/quotas.html) are applied to a namespace they 31 provide a means to limit resource consumption by the jobs in the namespace. This 32 can prevent a single actor from consuming excessive cluster resources and 33 negatively impacting other teams and applications sharing the cluster. 34 35 ## Namespaced Objects 36 37 Nomad places all jobs and their derived objects into namespaces. These include 38 jobs, allocations, deployments, and evaluations. 39 40 Nomad does not namespace objects that are shared across multiple namespaces. 41 This includes nodes, [ACL policies](/guides/acl.html), [Sentinel 42 policies](/guides/sentinel-policy.html), and [quota 43 specifications](/guides/quotas.html). 44 45 ## Working with Namespaces 46 47 For specific details about working with namespaces, see the [namespace 48 commands](/docs/commands/namespace.html) and [HTTP API](/api/namespaces.html) 49 documentation. 50 51 ### Creating and viewing namespaces: 52 53 Namespaces can be interacted with using the `nomad namespace` subcommand. The 54 following creates and lists the namespaces of a cluster: 55 56 ``` 57 $ nomad namespace apply -description "QA instances of webservers" web-qa 58 Successfully applied namespace "web-qa"! 59 60 $ nomad namespace list 61 Name Description 62 default Default shared namespace 63 api-prod Production instances of backend API servers 64 api-qa QA instances of backend API servers 65 web-prod Production instances of webservers 66 web-qa QA instances of webservers 67 ``` 68 69 ### Running jobs 70 71 To run a job in a specific namespace, we annotate the job with the `namespace` 72 parameter. If omitted, the job will be run in the `default` namespace. Below is 73 an example of running the job in the newly created `web-qa` namespace: 74 75 ``` 76 job "rails-www" { 77 78 # Run in the QA environments 79 namespace = "web-qa" 80 81 # Only run in one datacenter when QAing 82 datacenters = ["us-west1"] 83 ... 84 } 85 ``` 86 87 ### Specifying desired namespace 88 89 When using commands that operate on objects that are namespaced, the namespace 90 can be specified either with the flag `-namespace` or read from the 91 `NOMAD_NAMESPACE` environment variable: 92 93 ``` 94 $ nomad job status -namespace=web-qa 95 ID Type Priority Status Submit Date 96 rails-www service 50 running 09/17/17 19:17:46 UTC 97 98 $ export NOMAD_NAMESPACE=web-qa 99 100 $ nomad job status 101 ID Type Priority Status Submit Date 102 rails-www service 50 running 09/17/17 19:17:46 UTC 103 ``` 104 105 ### ACLs 106 107 Access to namespaces can be restricted using [ACLs](/guides/acl.html). As an 108 example we could create an ACL policy that allows full access to the QA 109 environment for our web namespaces but restrict the production access by 110 creating the following policy: 111 112 ``` 113 # Allow read only access to the production namespace 114 namespace "web-prod" { 115 policy = "read" 116 } 117 118 # Allow writing to the QA namespace 119 namespace "web-qa" { 120 policy = "write" 121 } 122 ```