mirror of
https://github.com/kemko/nomad.git
synced 2026-01-02 00:15:43 +03:00
4f7c38b2a7
Add structs and fields to support the Nomad Pools Governance Enterprise feature of controlling node pool access via namespaces. Nomad Enterprise allows users to specify a default node pool to be used by jobs that don't specify one. In order to accomplish this, it's necessary to distinguish between a job that explicitly uses the `default` node pool and one that did not specify any. If the `default` node pool is set during job canonicalization it's impossible to do this, so this commit allows a job to have an empty node pool value during registration but sets to `default` at the admission controller mutator. In order to guarantee state consistency the state store validates that the job node pool is set and exists before inserting it.
238 lines
6.6 KiB
Plaintext
238 lines
6.6 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Namespace - HTTP API
|
|
description: The /namespace endpoints are used to query for and interact with namespaces.
|
|
---
|
|
|
|
# Namespace HTTP API
|
|
|
|
The `/namespace` endpoints are used to query for and interact with namespaces.
|
|
|
|
## List Namespaces
|
|
|
|
This endpoint lists all namespaces.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------- | ------------------ |
|
|
| `GET` | `/v1/namespaces` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | -------------------------------------------------------------------------- |
|
|
| `YES` | `namespace:*`<br />Any capability on the namespace authorizes the endpoint |
|
|
|
|
### Parameters
|
|
|
|
- `prefix` `(string: "")`- Specifies a string to filter namespaces on based on
|
|
an index prefix. This is specified as a query string parameter.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/namespaces
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/namespaces?prefix=prod
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Capabilities": null,
|
|
"CreateIndex": 1,
|
|
"Description": "Default shared namespace",
|
|
"Meta": null,
|
|
"ModifyIndex": 1,
|
|
"Name": "default",
|
|
"Quota": ""
|
|
},
|
|
{
|
|
"Capabilities": null,
|
|
"CreateIndex": 17,
|
|
"Description": "Development Staging Namespace",
|
|
"Meta": {
|
|
"type": "dev",
|
|
"contact": "helpdesk@example.com"
|
|
},
|
|
"ModifyIndex": 17,
|
|
"Name": "staging",
|
|
"Quota": ""
|
|
}
|
|
]
|
|
```
|
|
|
|
## Read Namespace
|
|
|
|
This endpoint reads information about a specific namespace.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------------- | ------------------ |
|
|
| `GET` | `/v1/namespace/:namespace` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | -------------------------------------------------------------------------- |
|
|
| `YES` | `namespace:*`<br />Any capability on the namespace authorizes the endpoint |
|
|
|
|
### Parameters
|
|
|
|
- `:namespace` `(string: <required>)`- Specifies the namespace to query.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/namespace/staging
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Capabilities": null,
|
|
"CreateIndex": 17,
|
|
"Description": "Development Staging Namespace",
|
|
"Meta": {
|
|
"type": "dev",
|
|
"contact": "helpdesk@example.com"
|
|
},
|
|
"ModifyIndex": 17,
|
|
"Name": "staging",
|
|
"Quota": ""
|
|
}
|
|
```
|
|
|
|
## Create or Update Namespace
|
|
|
|
This endpoint is used to create or update a namespace.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------------------------- | ------------------ |
|
|
| `POST` | `/v1/namespace/:namespace` <br /> `/v1/namespace` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `Name` `(string: <required>)`- Specifies the namespace to create or
|
|
update.
|
|
|
|
- `Description` `(string: "")` - Specifies an optional human-readable
|
|
description of the namespace.
|
|
|
|
- `Meta` `(object: null)` - Optional object with string keys and values of
|
|
metadata to attach to the namespace. Namespace metadata is not used by Nomad
|
|
and is intended for use by operators and third party tools.
|
|
|
|
- `Quota` `(string: "")` <EnterpriseAlert inline /> - Specifies an quota to
|
|
attach to the namespace.
|
|
|
|
- `Capabilities` `(Capabilities: <optional>)` - Specifies capabilities allowed
|
|
in the namespace. These values are checked at job submission.
|
|
|
|
- `EnabledTaskDrivers` `(array<string>: [])` - List of task drivers allowed
|
|
in the namespace. If empty all task drivers are allowed.
|
|
|
|
- `DisabledTaskDrivers` `(array<string>: [])` - List of task drivers disabled
|
|
in the namespace.
|
|
|
|
- `NodePoolConfiguration` `(NodePoolConfiguration: <optional>)` <EnterpriseAlert inline /> -
|
|
Specifies node pool configurations. These values are checked at job
|
|
submission.
|
|
|
|
- `Default` `(string: "default")` - Specifies the node pool to use for jobs
|
|
in this namespace that don't define a node pool in their specification.
|
|
|
|
- `Allowed` `(array<string>: [])` - Specifies the node pools that are allowed
|
|
to be used by jobs in this namespace. This field supports wildcard globbing
|
|
through the use of `*` for multi-character matching. If specified, only the
|
|
node pools that match these patterns are allowed. This field cannot be used
|
|
with `Disabled`.
|
|
|
|
- `disabled` `(array<string>: [])` - Specifies the node pools that are not
|
|
allowed to be used by jobs in this namespace. This field supports wildcard
|
|
globbing through the use of `*` for multi-character matching. If specified,
|
|
any node pool is allowed except for those that match any of these patterns.
|
|
This field cannot be used with `Enabled`.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Name": "api-prod",
|
|
"Description": "Production API Servers",
|
|
"Meta": {
|
|
"contact": "platform-eng@example.com"
|
|
},
|
|
"Quota": "prod-quota",
|
|
"Capabilities": {
|
|
"DisabledTaskDrivers": ["raw_exec"]
|
|
},
|
|
"NodePoolConfiguration": {
|
|
"Default": "prod-pool",
|
|
"Allowed": ["default"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @namespace.json \
|
|
https://localhost:4646/v1/namespace/api-prod
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @namespace.json \
|
|
https://localhost:4646/v1/namespace
|
|
```
|
|
|
|
## Delete Namespace
|
|
|
|
This endpoint is used to delete a namespace.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | -------------------------- | ------------------ |
|
|
| `DELETE` | `/v1/namespace/:namespace` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `:namespace` `(string: <required>)`- Specifies the namespace to delete.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
https://localhost:4646/v1/namespace/api-prod
|
|
```
|