github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/namespaces.mdx (about)

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