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