daf5e3ea10
Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
271 lines
7.4 KiB
Plaintext
271 lines
7.4 KiB
Plaintext
---
|
|
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
|
|
}
|
|
]
|
|
```
|