diff --git a/website/content/api-docs/admin-partitions.mdx b/website/content/api-docs/admin-partitions.mdx index 4d87bde4d7..7078cbfbf0 100644 --- a/website/content/api-docs/admin-partitions.mdx +++ b/website/content/api-docs/admin-partitions.mdx @@ -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 @@ -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`1 | - -1 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 diff --git a/website/content/commands/partition.mdx b/website/content/commands/partition.mdx index ef9142097f..5b9fed9a39 100644 --- a/website/content/commands/partition.mdx +++ b/website/content/commands/partition.mdx @@ -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 -``` +| 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 - ``` -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 -``` +| 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 -``` +| 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 -``` +| 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: diff --git a/website/content/partials/http_api_and_cli_characteristics_links.mdx b/website/content/partials/http_api_and_cli_characteristics_links.mdx new file mode 100644 index 0000000000..0cbb237023 --- /dev/null +++ b/website/content/partials/http_api_and_cli_characteristics_links.mdx @@ -0,0 +1,6 @@ + + +[Required ACLs]: /docs/security/acl +[Blocking queries]: /api-docs/features/blocking +[Consistency modes]: /api-docs/features/consistency +[Agent caching]: /api-docs/features/caching