mirror of https://github.com/hashicorp/consul
271 lines
7.4 KiB
Markdown
271 lines
7.4 KiB
Markdown
---
|
|
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-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul partition create`](/commands/partition#create).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `Name` `(string: <required>)` - The partition name. This field 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 ---request PUT \
|
|
--header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/partition
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```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-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/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.
|
|
|
|
The corresponding CLI command is [`consul partition read`](/commands/partition#read).
|
|
|
|
### Path Parameters
|
|
|
|
- `name` `(string: <required>)` - Specifies the partition to read.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --header "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-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul partition write`](/commands/partition#write).
|
|
|
|
### Path Parameters
|
|
|
|
- `name` `(string: <required>)` - Specifies the partition to update.
|
|
This parameter 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 partition description.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Description": "North America West Partition"
|
|
}
|
|
```
|
|
|
|
### 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/partition/na-west
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```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-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul partition delete`](/commands/partition#delete).
|
|
|
|
### Path Parameters
|
|
|
|
- `name` `(string: <required>)` - Specifies the partition to delete.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request DELETE \
|
|
--header "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-docs/features/blocking),
|
|
[consistency modes](/api-docs/features/consistency),
|
|
[agent caching](/api-docs/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | --------------- |
|
|
| `NO` | `consistent` | `none` | `operator:read` |
|
|
|
|
The corresponding CLI command is [`consul partition list`](/commands/partition#list).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --header "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
|
|
}
|
|
]
|
|
```
|