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. description: The /partition endpoints allow for managing Consul Enterprise Admin Partitions.
--- ---
@include 'http_api_and_cli_characteristics_links.mdx'
# Admin Partition - HTTP API # Admin Partition - HTTP API
<EnterpriseAlert /> <EnterpriseAlert />
@ -13,23 +15,18 @@ The functionality described here is available only in
## Create a Partition ## Create a Partition
This endpoint creates a new Partition. This endpoint creates a new partition and has the following characteristics:
| Method | Path | Produces | | Characteristic | Value |
| ------ | ------------ | ------------------ | | -------------- | ----- |
| `PUT` | `/partition` | `application/json` | | HTTP method | `PUT` |
| URL path | `/v1/partition` |
The table below shows this endpoint's support for | Response type | `application/json` |
[blocking queries](/api-docs/features/blocking), | [Required ACLs] | `operator:write` |
[consistency modes](/api-docs/features/consistency), | Corresponding CLI command | [`consul partition create`](/commands/partition#create) |
[agent caching](/api-docs/features/caching), and | [Consistency modes] | N/A |
[required ACLs](/api#authentication). | [Blocking queries] | N/A |
| [Agent caching] | N/A |
| 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 ### JSON Request Body Schema
@ -69,25 +66,18 @@ $ curl ---request PUT \
## Read a Partition ## 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 | | Characteristic | Value |
| ------ | ------------------ | ------------------ | | -------------- | ----- |
| `GET` | `/partition/:name` | `application/json` | | HTTP method | `GET` |
| URL path | `/v1/partition/:name` |
The table below shows this endpoint's support for | Response type | `application/json` |
[blocking queries](/api-docs/features/blocking), | [Required ACLs] | `operator:read`; however, a non-anonymous token can always read its own partition |
[consistency modes](/api-docs/features/consistency), | Corresponding CLI command | [`consul partition read`](/commands/partition#read) |
[agent caching](/api-docs/features/caching), and | [Consistency modes] | `default`, `consistent` |
[required ACLs](/api#authentication). | [Blocking queries] | No |
| [Agent caching] | No |
| 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 ### 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 http://127.0.0.1:8500/v1/partition/na-west
``` ```
### SampleResponse ### Sample Response
```json ```json
{ {
@ -113,23 +103,18 @@ $ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
## Update a Partition ## Update a Partition
This endpoint updates a Partition description. This endpoint updates a partition description and has the following characteristics:
| Method | Path | Produces | | Characteristic | Value |
| ------ | ------------------ | ------------------ | | -------------- | ----- |
| `PUT` | `/partition/:name` | `application/json` | | HTTP method | `PUT` |
| URL path | `/v1/partition/:name` |
The table below shows this endpoint's support for | Response type | `application/json` |
[blocking queries](/api-docs/features/blocking), | [Required ACLs] | `operator:write` |
[consistency modes](/api-docs/features/consistency), | Corresponding CLI command | [`consul partition write`](/commands/partition#write) |
[agent caching](/api-docs/features/caching), and | [Consistency modes] | N/A |
[required ACLs](/api#authentication). | [Blocking queries] | N/A |
| [Agent caching] | N/A |
| 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 ### Path Parameters
@ -173,31 +158,25 @@ $ curl --request PUT \
## Delete a Partition ## 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 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` 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. marked for deletion.
| Method | Path | Produces | This endpoint has the following characteristics:
| -------- | ------------------ | -------- |
| `DELETE` | `/partition/:name` | N/A |
This endpoint will return no data. Success or failure is indicated by the status | Characteristic | Value |
code returned. | -------------- | ----- |
| HTTP method | `DELETE` |
The table below shows this endpoint's support for | URL path | `/v1/partition/:name` |
[blocking queries](/api-docs/features/blocking), | Response type | none; success or failure is indicated by the HTTP response status code |
[consistency modes](/api-docs/features/consistency), | [Required ACLs] | `operator:write` |
[agent caching](/api-docs/features/caching), and | Corresponding CLI command | [`consul partition delete`](/commands/partition#delete) |
[required ACLs](/api#authentication). | [Consistency modes] | N/A |
| [Blocking queries] | N/A |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | [Agent caching] | N/A |
| ---------------- | ----------------- | ------------- | ---------------- |
| `NO` | `none` | `none` | `operator:write` |
The corresponding CLI command is [`consul partition delete`](/commands/partition#delete).
### Path Parameters ### Path Parameters
@ -225,23 +204,18 @@ $ curl --request DELETE \
## List all Partitions ## List all Partitions
This endpoint lists all the Partitions. This endpoint lists all the partitions and has the following characteristics:
| Method | Path | Produces | | Characteristic | Value |
| ------ | ------------- | ------------------ | | -------------- | ----- |
| `GET` | `/partitions` | `application/json` | | HTTP method | `GET` |
| URL path | `/v1/partitions` |
The table below shows this endpoint's support for | Response type | `application/json` |
[blocking queries](/api-docs/features/blocking), | [Required ACLs] | `operator:read` |
[consistency modes](/api-docs/features/consistency), | Corresponding CLI command | [`consul partition list`](/commands/partition#list) |
[agent caching](/api-docs/features/caching), and | [Consistency modes] | `default`, `consistent` |
[required ACLs](/api#authentication). | [Blocking queries] | No |
| [Agent caching] | No |
| 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 ### 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. The partition command enables you create and manage Consul Enterprise admin partitions.
--- ---
@include 'http_api_and_cli_characteristics_links.mdx'
# Consul Admin Partition # Consul Admin Partition
Command: `consul partition` Command: `consul partition`
@ -66,10 +68,12 @@ You can issue the following subcommands with the `consul partition` command.
### `create` ### `create`
The `create` subcommand sends a request to the server to create a new admin partition. The `create` subcommand sends a request to the server to create a new admin partition.
This subcommand has the following characteristics:
```shell-session | Characteristic | Value |
consul partition create <OPTIONS> | -------------- | ----- |
``` | [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: 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` ### `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`. 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: Use the following syntax to write from file:
@ -109,7 +119,7 @@ Use the following syntax to write from `stdin`:
consul partition write <OPTIONS> - 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: You can specify the following options:
@ -134,10 +144,12 @@ $ consul partition write -format json -show-meta - <<< 'name = "webdev-bu" descr
### `read` ### `read`
The `read` subcommand sends a request to the server to read the configuration for the specified partition and print it to the console. 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 | Characteristic | Value |
consul partition read <OPTIONS> <PARTITION_NAME> | -------------- | ----- |
``` | [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: 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` ### `list`
The `list` subcommand prints existing admin partitions to the console. The `list` subcommand prints existing admin partitions to the console.
This subcommand has the following characteristics:
```shell-session | Characteristic | Value |
consul partition list <OPTIONS> | -------------- | ----- |
``` | [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: 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` ### `delete`
The `delete` subcommand sends a request to the server to remove the specified partition. The `delete` subcommand sends a request to the server to remove the specified partition.
This subcommand has the following characteristics:
```shell-session | Characteristic | Value |
$ consul partition delete <PARTITION_NAME> | -------------- | ----- |
``` | [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: 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