mirror of https://github.com/status-im/consul.git
docs: Add API docs for Admin Partitions (#11834)
This commit is contained in:
Chris S. Kim
GitHub
parent
ef3a32b4ad
commit
729ff425ff
|
|
@ -0,0 +1,258 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Admin Partition - HTTP API
|
||||
description: The /partition endpoints allow for managing Consul Enterprise Admin Partitions.
|
||||
---
|
||||
|
||||
# Admin Partition - HTTP API
|
||||
|
||||
<EnterpriseAlert />
|
||||
|
||||
The functionality described here is available only in
|
||||
[Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.11.0 and later.
|
||||
|
||||
## Create a Partition
|
||||
|
||||
This endpoint creates a new Partition.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------ | ------------------ |
|
||||
| `PUT` | `/partition` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/features/blocking),
|
||||
[consistency modes](/api/features/consistency),
|
||||
[agent caching](/api/features/caching), and
|
||||
[required ACLs](/api#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Name` `(string: <required>)` - The partition name. This must be a valid
|
||||
DNS hostname label.
|
||||
|
||||
- `Description` `(string: "")` - Free form partition description.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "na-west",
|
||||
"Description": "Partition for North America West",
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl -X PUT \
|
||||
-H "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8500/v1/partition
|
||||
```
|
||||
|
||||
### SampleResponse
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "na-west",
|
||||
"Description": "Partition for North America West",
|
||||
"CreateIndex": 55,
|
||||
"ModifyIndex": 55
|
||||
}
|
||||
```
|
||||
|
||||
## Read a Partition
|
||||
|
||||
This endpoint reads a Partition with the given name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `GET` | `/partition/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/features/blocking),
|
||||
[consistency modes](/api/features/consistency),
|
||||
[agent caching](/api/features/caching), and
|
||||
[required ACLs](/api#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ------------------------------------- |
|
||||
| `NO` | `consistent` | `none` | `operator:read` or `none`<sup>1</sup> |
|
||||
|
||||
<sup>1</sup> A non-anonymous token can read its own partition.
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Specifies the partition to read. This
|
||||
is required and is specified as part of the URL path.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl -H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
||||
http://127.0.0.1:8500/v1/partition/na-west
|
||||
```
|
||||
|
||||
### SampleResponse
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "na-west",
|
||||
"Description": "Partition for North America West",
|
||||
"CreateIndex": 55,
|
||||
"ModifyIndex": 55
|
||||
}
|
||||
```
|
||||
|
||||
## Update a Partition
|
||||
|
||||
This endpoint updates a Partition description.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------ | ------------------ |
|
||||
| `PUT` | `/partition/:name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/features/blocking),
|
||||
[consistency modes](/api/features/consistency),
|
||||
[agent caching](/api/features/caching), and
|
||||
[required ACLs](/api#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Name` `(string: <optional>)` - The partition name. This must be a valid
|
||||
DNS hostname label. If present in the payload it must match what was given
|
||||
in the URL path.
|
||||
|
||||
- `Description` `(string: "")` - Free form partition description.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"Description": "North America West Partition"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl -X PUT \
|
||||
-H "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8500/v1/partition/na-west
|
||||
```
|
||||
|
||||
### SampleResponse
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "na-west",
|
||||
"Description": "North America West Partition",
|
||||
"CreateIndex": 55,
|
||||
"ModifyIndex": 60
|
||||
}
|
||||
```
|
||||
|
||||
## Delete a Partition
|
||||
|
||||
This endpoint marks a Partition for deletion. Once marked Consul will
|
||||
deleted all the associated partitioned data in the background. Only once
|
||||
all associated data has been deleted will the Partition actually disappear.
|
||||
Until then, further reads can be performed on the partition and a `DeletedAt`
|
||||
field will now be populated with the timestamp of when the Partition was
|
||||
marked for deletion.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ------------------ | -------- |
|
||||
| `DELETE` | `/partition/:name` | N/A |
|
||||
|
||||
This endpoint will return no data. Success or failure is indicated by the status
|
||||
code returned.
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/features/blocking),
|
||||
[consistency modes](/api/features/consistency),
|
||||
[agent caching](/api/features/caching), and
|
||||
[required ACLs](/api#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | ---------------- |
|
||||
| `NO` | `none` | `none` | `operator:write` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Specifies the partition to delete. This
|
||||
is required and is specified as part of the URL path.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl -X DELETE \
|
||||
-H "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
||||
http://127.0.0.1:8500/v1/partition/na-west
|
||||
```
|
||||
|
||||
### Sample Read Output After Deletion Prior to Removal
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "na-west",
|
||||
"Description": "North America West Partition",
|
||||
"DeletedAt": "2021-12-14T23:00:00Z",
|
||||
"CreateIndex": 55,
|
||||
"ModifyIndex": 100
|
||||
}
|
||||
```
|
||||
|
||||
## List all Partitions
|
||||
|
||||
This endpoint lists all the Partitions.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `GET` | `/partitions` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/features/blocking),
|
||||
[consistency modes](/api/features/consistency),
|
||||
[agent caching](/api/features/caching), and
|
||||
[required ACLs](/api#authentication).
|
||||
|
||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ---------------- | ----------------- | ------------- | --------------- |
|
||||
| `NO` | `consistent` | `none` | `operator:read` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl -H "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
|
||||
http://127.0.0.1:8500/v1/partitions
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"Name": "default",
|
||||
"Description": "Builtin Default Partition",
|
||||
"CreateIndex": 6,
|
||||
"ModifyIndex": 6
|
||||
},
|
||||
{
|
||||
"Name": "na-west",
|
||||
"Description": "North America West Partition",
|
||||
"CreateIndex": 55,
|
||||
"ModifyIndex": 55
|
||||
}
|
||||
]
|
||||
```
|
||||
|
|
@ -60,6 +60,10 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Admin Partitions",
|
||||
"path": "admin-partitions"
|
||||
},
|
||||
{
|
||||
"title": "Agent",
|
||||
"routes": [
|
||||
|
|
|
|||
Loading…
Reference in New Issue