mirror of https://github.com/status-im/consul.git
Merge pull request #12045 from hashicorp/partition-cli-acl-info-and-api-crossref
Partitions: Include ACL Info and API cross-ref for CLI Commands
This commit is contained in:
Jared Kirschner
GitHub
commit
5a92e439e6
|
|
@ -4,6 +4,8 @@ page_title: Admin Partition - HTTP API
|
|||
description: The /partition endpoints allow for managing Consul Enterprise Admin Partitions.
|
||||
---
|
||||
|
||||
@include 'http_api_and_cli_characteristics_links.mdx'
|
||||
|
||||
# Admin Partition - HTTP API
|
||||
|
||||
<EnterpriseAlert />
|
||||
|
|
@ -13,23 +15,18 @@ The functionality described here is available only in
|
|||
|
||||
## Create a Partition
|
||||
|
||||
This endpoint creates a new Partition.
|
||||
This endpoint creates a new partition and has the following characteristics:
|
||||
|
||||
| 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).
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| HTTP method | `PUT` |
|
||||
| URL path | `/v1/partition` |
|
||||
| Response type | `application/json` |
|
||||
| [Required ACLs] | `operator:write` |
|
||||
| Corresponding CLI command | [`consul partition create`](/commands/partition#create) |
|
||||
| [Consistency modes] | N/A |
|
||||
| [Blocking queries] | N/A |
|
||||
| [Agent caching] | N/A |
|
||||
|
||||
### JSON Request Body Schema
|
||||
|
||||
|
|
@ -69,25 +66,18 @@ $ curl ---request PUT \
|
|||
|
||||
## Read a Partition
|
||||
|
||||
This endpoint reads a Partition with the given name.
|
||||
This endpoint reads a partition with the given name and has the following characteristics:
|
||||
|
||||
| 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).
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| HTTP method | `GET` |
|
||||
| URL path | `/v1/partition/:name` |
|
||||
| Response type | `application/json` |
|
||||
| [Required ACLs] | `operator:read`; however, a non-anonymous token can always read its own partition |
|
||||
| Corresponding CLI command | [`consul partition read`](/commands/partition#read) |
|
||||
| [Consistency modes] | `default`, `consistent` |
|
||||
| [Blocking queries] | No |
|
||||
| [Agent caching] | No |
|
||||
|
||||
### Path Parameters
|
||||
|
||||
|
|
@ -113,23 +103,18 @@ $ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
|
|||
|
||||
## Update a Partition
|
||||
|
||||
This endpoint updates a Partition description.
|
||||
This endpoint updates a partition description and has the following characteristics:
|
||||
|
||||
| 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).
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| HTTP method | `PUT` |
|
||||
| URL path | `/v1/partition/:name` |
|
||||
| Response type | `application/json` |
|
||||
| [Required ACLs] | `operator:write` |
|
||||
| Corresponding CLI command | [`consul partition write`](/commands/partition#write) |
|
||||
| [Consistency modes] | N/A |
|
||||
| [Blocking queries] | N/A |
|
||||
| [Agent caching] | N/A |
|
||||
|
||||
### Path Parameters
|
||||
|
||||
|
|
@ -173,31 +158,25 @@ $ curl --request PUT \
|
|||
|
||||
## Delete a Partition
|
||||
|
||||
This endpoint marks a Partition for deletion. Once marked Consul will
|
||||
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.
|
||||
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
|
||||
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 has the following characteristics:
|
||||
|
||||
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).
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| HTTP method | `DELETE` |
|
||||
| URL path | `/v1/partition/:name` |
|
||||
| Response type | none; success or failure is indicated by the HTTP response status code |
|
||||
| [Required ACLs] | `operator:write` |
|
||||
| Corresponding CLI command | [`consul partition delete`](/commands/partition#delete) |
|
||||
| [Consistency modes] | N/A |
|
||||
| [Blocking queries] | N/A |
|
||||
| [Agent caching] | N/A |
|
||||
|
||||
### Path Parameters
|
||||
|
||||
|
|
@ -225,23 +204,18 @@ $ curl --request DELETE \
|
|||
|
||||
## List all Partitions
|
||||
|
||||
This endpoint lists all the Partitions.
|
||||
This endpoint lists all the partitions and has the following characteristics:
|
||||
|
||||
| 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).
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| HTTP method | `GET` |
|
||||
| URL path | `/v1/partitions` |
|
||||
| Response type | `application/json` |
|
||||
| [Required ACLs] | `operator:read` |
|
||||
| Corresponding CLI command | [`consul partition list`](/commands/partition#list) |
|
||||
| [Consistency modes] | `default`, `consistent` |
|
||||
| [Blocking queries] | No |
|
||||
| [Agent caching] | No |
|
||||
|
||||
### Sample Request
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ description: |
|
|||
The partition command enables you create and manage Consul Enterprise admin partitions.
|
||||
---
|
||||
|
||||
@include 'http_api_and_cli_characteristics_links.mdx'
|
||||
|
||||
# Consul Admin Partition
|
||||
|
||||
Command: `consul partition`
|
||||
|
|
@ -66,10 +68,12 @@ You can issue the following subcommands with the `consul partition` command.
|
|||
### `create`
|
||||
|
||||
The `create` subcommand sends a request to the server to create a new admin partition.
|
||||
This subcommand has the following characteristics:
|
||||
|
||||
```shell-session
|
||||
consul partition create <OPTIONS>
|
||||
```
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| [Required ACLs] | `operator:write` |
|
||||
| Corresponding HTTP API endpoint | [\[PUT\] /v1/partition](/api-docs/admin-partitions#create-a-partition) |
|
||||
|
||||
The admin partition is created according to the values specified in the options. You can specify the following options:
|
||||
|
||||
|
|
@ -96,6 +100,12 @@ $ consul partition create -name "webdev" -description "Partition for admin of we
|
|||
### `write`
|
||||
|
||||
The `write` subcommand sends a request to the server to create a new admin partition or update an existing partition from its full definition. You can specify an admin partition definition file or use values from `stdin`.
|
||||
This subcommand has the following characteristics:
|
||||
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| [Required ACLs] | `operator:write` |
|
||||
| Corresponding HTTP API endpoint | [\[PUT\] /v1/partition/:name](/api-docs/admin-partitions#update-a-partition) |
|
||||
|
||||
Use the following syntax to write from file:
|
||||
|
||||
|
|
@ -109,7 +119,7 @@ Use the following syntax to write from `stdin`:
|
|||
consul partition write <OPTIONS> -
|
||||
```
|
||||
|
||||
The definition file or `stdin` values can be provided in JSON or HCL format. Refer to the [Admin Partition Definition](#partition-definition) section for details about the supported parameters.
|
||||
The definition file or `stdin` values can be provided in JSON or HCL format. Refer to the [Admin Partition Definition](#admin-partition-definition) section for details about the supported parameters.
|
||||
|
||||
You can specify the following options:
|
||||
|
||||
|
|
@ -134,10 +144,12 @@ $ consul partition write -format json -show-meta - <<< 'name = "webdev-bu" descr
|
|||
### `read`
|
||||
|
||||
The `read` subcommand sends a request to the server to read the configuration for the specified partition and print it to the console.
|
||||
This subcommand has the following characteristics:
|
||||
|
||||
```shell-session
|
||||
consul partition read <OPTIONS> <PARTITION_NAME>
|
||||
```
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| [Required ACLs] | `operator:read`; however, a non-anonymous token can always read its own partition |
|
||||
| Corresponding HTTP API endpoint | [\[GET\] /v1/partition/:name](/api-docs/admin-partitions#read-a-partition) |
|
||||
|
||||
The admin partition is created according to the values specified in the options. You can specify the following options:
|
||||
|
||||
|
|
@ -161,10 +173,12 @@ consul partition read -format json -meta webdev
|
|||
### `list`
|
||||
|
||||
The `list` subcommand prints existing admin partitions to the console.
|
||||
This subcommand has the following characteristics:
|
||||
|
||||
```shell-session
|
||||
consul partition list <OPTIONS>
|
||||
```
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| [Required ACLs] | `operator:read` |
|
||||
| Corresponding HTTP API endpoint | [\[GET\] /v1/partitions](/api-docs/admin-partitions#list-all-partitions) |
|
||||
|
||||
The admin partition is created according to the values specified in the options. You can specify the following options:
|
||||
|
||||
|
|
@ -202,10 +216,12 @@ $ consul partition list -format json -show-meta
|
|||
### `delete`
|
||||
|
||||
The `delete` subcommand sends a request to the server to remove the specified partition.
|
||||
This subcommand has the following characteristics:
|
||||
|
||||
```shell-session
|
||||
$ consul partition delete <PARTITION_NAME>
|
||||
```
|
||||
| Characteristic | Value |
|
||||
| -------------- | ----- |
|
||||
| [Required ACLs] | `operator:write` |
|
||||
| Corresponding HTTP API endpoint | [\[DELETE\] /v1/partitions](/api-docs/admin-partitions#delete-a-partition) |
|
||||
|
||||
In the following example, the `webdev-bu` partition is deleted:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,6 @@
|
|||
<!-- list of reference-style links (must have have an empty line beneath) -->
|
||||
|
||||
[Required ACLs]: /docs/security/acl
|
||||
[Blocking queries]: /api-docs/features/blocking
|
||||
[Consistency modes]: /api-docs/features/consistency
|
||||
[Agent caching]: /api-docs/features/caching
|
||||
Loading…
Reference in New Issue