mirror of https://github.com/hashicorp/consul
515 lines
15 KiB
Markdown
515 lines
15 KiB
Markdown
---
|
|
layout: api
|
|
page_title: Namespace - HTTP API
|
|
description: The /namespace endpoints allow for managing Consul Enterprise Namespaces.
|
|
---
|
|
|
|
# Namespace - HTTP API
|
|
|
|
<EnterpriseAlert />
|
|
|
|
The functionality described here is available only in
|
|
[Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.7.0 and later.
|
|
|
|
## Create a Namespace
|
|
|
|
This endpoint creates a new Namespace.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------ | ------------------ |
|
|
| `PUT` | `/namespace` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul namespace create`](/consul/commands/namespace/create).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `Name` `(string: <required>)` - The namespace's name.
|
|
This field must be a valid DNS hostname label.
|
|
|
|
- `Description` `(string: "")` - Free form namespaces description.
|
|
|
|
- `ACLs` `(object: <optional>)` - ACL configurations for this namespace. Rules from
|
|
default policies and roles will be used only when there are no rules from directly linked
|
|
policies, roles and service identities that are for the target resource and segment.
|
|
Therefore if a directly linked policy grants read access to some resource and a
|
|
default policy grants write access, the effective access for the token will be read
|
|
due to the default policies not being checked. When there is no rule concerning
|
|
the resource in either the directly linked policies, roles and service identities
|
|
nor in those linked by the defaults, then the agents default policy configuration
|
|
will be used for making the enforcement decision.
|
|
|
|
- `PolicyDefaults` `(array<ACLLink>)` - This is the list of default policies
|
|
that should be applied to all tokens created in this namespace. The ACLLink
|
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
|
and store that internally. The ACL token used in the API request
|
|
must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules)
|
|
to the linked policy.
|
|
|
|
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
|
|
that should be applied to all tokens created in this namespace. The ACLLink
|
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
|
and store that internally. The ACL token used in the API request
|
|
must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules)
|
|
access to the linked role.
|
|
|
|
- `Meta` `(map<string|string>: <optional>)` - Specifies arbitrary KV metadata
|
|
to associate with the namespace.
|
|
|
|
@include 'http-api-body-options-partition.mdx'
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
|
},
|
|
{
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
|
},
|
|
{
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request PUT \
|
|
--header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/namespace
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
|
"Name": "service-read"
|
|
},
|
|
{
|
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
|
"Name": "service-discovery"
|
|
},
|
|
{
|
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
},
|
|
"CreateIndex": 55,
|
|
"ModifyIndex": 55
|
|
}
|
|
```
|
|
|
|
## Read a Namespace
|
|
|
|
This endpoint reads a Namespace with the given name.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------ | ------------------ |
|
|
| `GET` | `/namespace/:name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
|
|
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1</sup> |
|
|
|
|
<sup>1</sup> Access can be granted to list the Namespace if the token used when making
|
|
the request has been granted any access in the namespace (read, list or write).
|
|
|
|
The corresponding CLI command is [`consul namespace read`](/consul/commands/namespace/read).
|
|
|
|
### Path Parameters
|
|
|
|
- `name` `(string: <required>)` - Specifies the namespace to read.
|
|
|
|
### Query Parameters
|
|
|
|
@include 'http-api-query-parms-partition.mdx'
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
|
http://127.0.0.1:8500/v1/namespace/team-1
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
|
"Name": "service-read"
|
|
},
|
|
{
|
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
|
"Name": "service-discovery"
|
|
},
|
|
{
|
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
},
|
|
"CreateIndex": 55,
|
|
"ModifyIndex": 55
|
|
}
|
|
```
|
|
|
|
## Update a Namespace
|
|
|
|
This endpoint updates a Namespace.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------ | ------------------ |
|
|
| `PUT` | `/namespace/:name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul namespace update`](/consul/commands/namespace/update) or [`consul namespace write`](/consul/commands/namespace/write).
|
|
|
|
### Path Parameters
|
|
|
|
- `name` `(string: <required>)` - The namespaces name. This must be a valid DNS hostname label.
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `Name` `(string: <optional>)` - If specified, this field must be an exact match
|
|
with the `name` path parameter.
|
|
|
|
- `Description` `(string: "")` - Free form namespaces description.
|
|
|
|
- `ACLs` `(object: <optional>)` - ACL configurations for this Namespace. Rules from
|
|
default policies and roles will be used only when there are no rules from directly linked
|
|
policies, roles and service identities that are for the target resource and segment.
|
|
Therefore if a directly linked policy grants read access to some resource and a
|
|
default policy grants write access, the effective access for the token will be read
|
|
due to the default policies not being checked. When there is no rule concerning
|
|
the resource in either the directly linked policies, roles and service identities
|
|
nor in those linked by the defaults, then the agents default policy configuration
|
|
will be used for making the enforcement decision.
|
|
|
|
- `PolicyDefaults` `(array<ACLLink>)` - This is the list of default policies
|
|
that should be applied to all tokens created in this namespace. The ACLLink
|
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
|
and store that internally. The ACL token used in the API request
|
|
must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules)
|
|
to the linked policy.
|
|
|
|
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
|
|
that should be applied to all tokens created in this namespace. The ACLLink
|
|
struct is an object with an "ID" and/or "Name" field to identify a policy.
|
|
When a name is used instead of an ID, Consul will resolve the name to an ID
|
|
and store that internally. The ACL token used in the API request
|
|
must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules)
|
|
to the linked role.
|
|
|
|
- `Meta` `(map<string|string>: <optional>)` - Specifies arbitrary KV metadata
|
|
to associate with the namespace.
|
|
|
|
@include 'http-api-body-options-partition.mdx'
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
|
},
|
|
{
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
|
},
|
|
{
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request PUT \
|
|
--header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/namespace/team-1
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
|
"Name": "service-read"
|
|
},
|
|
{
|
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
|
"Name": "service-discovery"
|
|
},
|
|
{
|
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
},
|
|
"CreateIndex": 55,
|
|
"ModifyIndex": 55
|
|
}
|
|
```
|
|
|
|
## Delete a Namespace
|
|
|
|
This endpoint marks a Namespace for deletion. Once marked, Consul deletes all the associated Namespaced data in the background. Only after all associated data has been deleted, Consul deletes the Namespace.
|
|
Until then, you can perform further reads on the namespace, and a `DeletedAt`
|
|
field is populated with the timestamp of when the Namespace was marked for deletion.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | ------------------ | -------- |
|
|
| `DELETE` | `/namespace/:name` | N/A |
|
|
|
|
This endpoint returns no data. Success or failure is indicated by the status
|
|
code returned.
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul namespace delete`](/consul/commands/namespace/delete).
|
|
|
|
### Path Parameters
|
|
|
|
- `name` `(string: <required>)` - Specifies the namespace to delete.
|
|
|
|
### Query Parameters
|
|
|
|
@include 'http-api-query-parms-partition.mdx'
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request DELETE \
|
|
--header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
|
http://127.0.0.1:8500/v1/namespace/team-1
|
|
```
|
|
|
|
### Sample Read Output After Deletion Prior to Removal
|
|
|
|
```json
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
|
"Name": "service-read"
|
|
},
|
|
{
|
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
|
"Name": "service-discovery"
|
|
},
|
|
{
|
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
},
|
|
"DeletedAt": "2019-12-02T23:00:00Z",
|
|
"CreateIndex": 55,
|
|
"ModifyIndex": 100
|
|
}
|
|
```
|
|
|
|
## List all Namespaces
|
|
|
|
This endpoint lists all the Namespaces. The output will be filtered based on the
|
|
privileges of the ACL token used for the request.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------- | ------------------ |
|
|
| `GET` | `/namespaces` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
|
|
| `YES` | `all` | `none` | `operator:read` or `namespace:*:read`<sup>1</sup> |
|
|
|
|
<sup>1</sup> Access can be granted to list the Namespace if the token used when making
|
|
the request has been granted any access in the namespace (read, list or write).
|
|
|
|
The corresponding CLI command is [`consul namespace list`](/consul/commands/namespace/list).
|
|
|
|
### Query Parameters
|
|
|
|
@include 'http-api-query-parms-partition.mdx'
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
|
|
http://127.0.0.1:8500/v1/namespaces
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Name": "default",
|
|
"Description": "Builtin Default Namespace",
|
|
"CreateIndex": 6,
|
|
"ModifyIndex": 6
|
|
},
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1",
|
|
"Name": "service-read"
|
|
},
|
|
{
|
|
"ID": "af937401-9950-fcae-8396-610ce047649a",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7",
|
|
"Name": "service-discovery"
|
|
},
|
|
{
|
|
"ID": "ae4b3542-d824-eb5f-7799-3fd657847e4e",
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
},
|
|
"CreateIndex": 55,
|
|
"ModifyIndex": 55
|
|
}
|
|
]
|
|
```
|