github.com/smintz/nomad@v0.8.3/website/source/api/namespaces.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Namespace - HTTP API
     4  sidebar_current: api-namespaces
     5  description: |-
     6    The /namespace endpoints are used to query for and interact with namespaces.
     7  ---
     8  
     9  # Namespace HTTP API
    10  
    11  The `/namespace` endpoints are used to query for and interact with namespaces.
    12  
    13  ~> **Enterprise Only!** This API endpoint and functionality only exists in
    14  Nomad Enterprise. This is not present in the open source version of Nomad.
    15  
    16  ## List Namespaces
    17  
    18  This endpoint lists all namespaces.
    19  
    20  | Method | Path              | Produces           |
    21  | ------ | ----------------- | ------------------ |
    22  | `GET`  | `/v1/namespaces`  | `application/json` |
    23  
    24  The table below shows this endpoint's support for
    25  [blocking queries](/api/index.html#blocking-queries) and
    26  [required ACLs](/api/index.html#acls).
    27  
    28  | Blocking Queries | ACL Required  |
    29  | ---------------- | ------------- |
    30  | `YES`            | `namespace:*`<br>Any capability on the namespace authorizes the endpoint |
    31  
    32  ### Parameters
    33  
    34  - `prefix` `(string: "")`- Specifies a string to filter namespaces on based on
    35    an index prefix. This is specified as a querystring parameter.
    36  
    37  ### Sample Request
    38  
    39  ```text
    40  $ curl \
    41      https://localhost:4646/v1/namespaces
    42  ```
    43  
    44  ```text
    45  $ curl \
    46      https://localhost:4646/v1/namespaces?prefix=prod
    47  ```
    48  
    49  ### Sample Response
    50  
    51  ```json
    52  [
    53      {
    54          "CreateIndex": 31,
    55          "Description": "Production API Servers",
    56          "ModifyIndex": 31,
    57          "Name": "api-prod"
    58      },
    59      {
    60          "CreateIndex": 5,
    61          "Description": "Default shared namespace",
    62          "ModifyIndex": 5,
    63          "Name": "default"
    64      }
    65  ]
    66  ```
    67  
    68  ## Read Namespace
    69  
    70  This endpoint reads information about a specific namespace.
    71  
    72  | Method | Path                        | Produces                   |
    73  | ------ | --------------------------- | -------------------------- |
    74  | `GET`  | `/v1/namespace/:namespace`  | `application/json`         |
    75  
    76  The table below shows this endpoint's support for
    77  [blocking queries](/api/index.html#blocking-queries) and
    78  [required ACLs](/api/index.html#acls).
    79  
    80  | Blocking Queries | ACL Required         |
    81  | ---------------- | -------------------- |
    82  | `YES`            | `namespace:*`<br>Any capability on the namespace authorizes the endpoint |
    83  
    84  ### Parameters
    85  
    86  - `:namespace` `(string: <required>)`- Specifies the namespace to query.
    87  
    88  ### Sample Request
    89  
    90  ```text
    91  $ curl \
    92      https://localhost:4646/v1/namespace/api-prod
    93  ```
    94  
    95  ### Sample Response
    96  
    97  ```json
    98  {
    99      "CreateIndex": 31,
   100      "Description": "Production API Servers",
   101      "Hash": "N8WvePwqkp6J354eLJMKyhvsFdPELAos0VuBfMoVKoU=",
   102      "ModifyIndex": 31,
   103      "Name": "api-prod"
   104  }
   105  ```
   106  
   107  ## Create or Update Namespace
   108  
   109  This endpoint is used to create or update a namespace.
   110  
   111  | Method  | Path                                            | Produces                   |
   112  | ------- | ----------------------------------------------- | -------------------------- |
   113  | `POST`  | `/v1/namespace/:namespace` <br> `/v1/namespace` | `application/json`         |
   114  
   115  The table below shows this endpoint's support for
   116  [blocking queries](/api/index.html#blocking-queries) and
   117  [required ACLs](/api/index.html#acls).
   118  
   119  | Blocking Queries | ACL Required |
   120  | ---------------- | ------------ |
   121  | `NO`             | `management` |
   122  
   123  ### Parameters
   124  
   125  - `Namespace` `(string: <required>)`- Specifies the namespace to create or
   126    update.
   127  
   128  - `Description` `(string: "")` - Specifies an optional human-readable
   129    description of the namespace.
   130  
   131  ### Sample Payload
   132  
   133  ```javascript
   134  {
   135    "Namespace": "api-prod",
   136    "Description": "Production API Servers"
   137  }
   138  ```      
   139  
   140  ### Sample Request
   141  
   142  ```text
   143  $ curl \
   144      --request POST \
   145      --data @namespace.json \
   146      https://localhost:4646/v1/namespace/api-prod
   147  ```
   148  
   149  ```text
   150  $ curl \
   151      --request POST \
   152      --data @namespace.json \
   153      https://localhost:4646/v1/namespace
   154  ```
   155  
   156  ## Delete Namespace
   157  
   158  This endpoint is used to delete a namespace.
   159  
   160  | Method   | Path                       | Produces                   |
   161  | -------  | -------------------------- | -------------------------- |
   162  | `DELETE` | `/v1/namespace/:namespace` | `application/json`         |
   163  
   164  The table below shows this endpoint's support for
   165  [blocking queries](/api/index.html#blocking-queries) and
   166  [required ACLs](/api/index.html#acls).
   167  
   168  | Blocking Queries | ACL Required |
   169  | ---------------- | ------------ |
   170  | `NO`             | `management` |
   171  
   172  ### Parameters
   173  
   174  - `:namespace` `(string: <required>)`- Specifies the namespace to delete.
   175  
   176  ### Sample Request
   177  
   178  ```text
   179  $ curl \
   180      --request DELETE \
   181      https://localhost:4646/v1/namespace/api-prod
   182  ```