github.com/adityamillind98/nomad@v0.11.8/website/pages/api-docs/namespaces.mdx (about)

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