status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

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 2022-07-25 19:10:55 -04:00 committed by GitHub
parent 8c5b70d227 51f0a64b6b
commit 5a92e439e6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 96 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
website/content/api-docs/admin-partitions.mdx
View File

@ -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
@ -100,7 +90,7 @@ $ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
http://127.0.0.1:8500/v1/partition/na-west
```
### SampleResponse
### Sample Response
```json
{
@ -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

42
website/content/commands/partition.mdx
View File

@ -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:

6
website/content/partials/http_api_and_cli_characteristics_links.mdx Normal file
View File

@ -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