265 lines
15 KiB
Plaintext
265 lines
15 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: partition'
|
|
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`
|
|
|
|
<EnterpriseAlert />
|
|
|
|
The `partition` command enables you to create and manage Consul Enterprise administrative or admin partitions. Admin partitions are boundaries that allow multiple tenants to exist independently of each other on a shared set of Consul servers.
|
|
|
|
If ACLs are enabled then a token with operator privileges may be required in order to use this command.
|
|
|
|
You should only run the `partition` command in the primary datacenter.
|
|
|
|
## Usage
|
|
|
|
```shell-session
|
|
consul partition <SUBCOMMAND> <OPTIONS>
|
|
```
|
|
|
|
Issue the `consul partition -h` command to view the subcommands.
|
|
|
|
```shell-session
|
|
Usage: consul partition <subcommand> [options] [args]
|
|
|
|
This command has subcommands for interacting with Consul Enterprise
|
|
admin partitions. Here are some simple examples. More detailed
|
|
examples are available in the subcommands or the documentation.
|
|
|
|
Create an admin partition
|
|
|
|
$ consul partition create -name team1
|
|
|
|
Create or Update an admin partition from its full definition:
|
|
|
|
$ consul partition write part1
|
|
|
|
Read an admin partition:
|
|
|
|
$ consul partition read team1
|
|
|
|
List all admin partitions:
|
|
|
|
$ consul partition list
|
|
|
|
Update an admin partition
|
|
|
|
$ consul partition update -name team1 -description "first partition"
|
|
|
|
Delete an admin partition:
|
|
|
|
$ consul partition delete team1
|
|
|
|
For more examples, ask for subcommand help or view the documentation.
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
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:
|
|
|
|
| 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:
|
|
|
|
| Option | Description | Default | Required |
|
|
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
|
|
| `-name` | String value that specifies the name for the new partition. | none | Required |
|
|
| `-description` | String value that specifies a description of the new partition. | none | Optional |
|
|
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
|
|
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
|
|
|
|
In the following example, a partition named `webdev` is created:
|
|
|
|
```shell-session
|
|
$ consul partition create -name "webdev" -description "Partition for admin of webdev services" -format json -show-meta
|
|
|
|
{
|
|
"Name": "webdev",
|
|
"Description": "Partition for admin of webdev services",
|
|
"CreateIndex": 940,
|
|
"ModifyIndex": 940
|
|
}
|
|
```
|
|
|
|
### `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:
|
|
|
|
```shell-session
|
|
consul partition write <OPTIONS> <FILE>
|
|
```
|
|
|
|
Use the following syntax to write from `stdin`:
|
|
|
|
```shell-session
|
|
consul partition write <OPTIONS> -
|
|
```
|
|
|
|
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:
|
|
|
|
| Option | Description | Default | Required |
|
|
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
|
|
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
|
|
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
|
|
|
|
In the following example, the `webdev-bu` partition is written using `stdin` values:
|
|
|
|
```shell-session
|
|
$ consul partition write -format json -show-meta - <<< 'name = "webdev-bu" description = "backup webdev partition"'
|
|
|
|
{
|
|
"Name": "webdev-bu",
|
|
"Description": "backup webdev partition",
|
|
"CreateIndex": 1462,
|
|
"ModifyIndex": 1462
|
|
}
|
|
```
|
|
|
|
### `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:
|
|
|
|
| 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:
|
|
|
|
| Option | Description | Default | Required |
|
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
|
|
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
|
|
| `-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
|
|
|
|
In the following example, the configuration for the `webdev` partition is read:
|
|
|
|
```shell-session
|
|
consul partition read -format json -meta webdev
|
|
|
|
{
|
|
"Name": "webdev",
|
|
"CreateIndex": 940,
|
|
"ModifyIndex": 1458
|
|
}
|
|
```
|
|
|
|
### `list`
|
|
|
|
The `list` subcommand prints existing admin partitions to the console.
|
|
This subcommand has the following characteristics:
|
|
|
|
| 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:
|
|
|
|
| Option | Description | Default | Required |
|
|
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
|
|
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
|
|
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
|
|
|
|
The following example lists the admin partitions and their meta data in JSON format:
|
|
|
|
```shell-session
|
|
$ consul partition list -format json -show-meta
|
|
|
|
[
|
|
{
|
|
"Name": "default",
|
|
"Description": "Builtin Default Partition",
|
|
"CreateIndex": 4,
|
|
"ModifyIndex": 4
|
|
},
|
|
{
|
|
"Name": "webdev",
|
|
"CreateIndex": 940,
|
|
"ModifyIndex": 1458
|
|
},
|
|
{
|
|
"Name": "webdev-bu",
|
|
"Description": "backup webdev partition",
|
|
"CreateIndex": 1462,
|
|
"ModifyIndex": 1462
|
|
}
|
|
]
|
|
```
|
|
|
|
### `delete`
|
|
|
|
The `delete` subcommand sends a request to the server to remove the specified partition.
|
|
This subcommand has the following characteristics:
|
|
|
|
| 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:
|
|
|
|
```shell-session
|
|
consul partition delete webdev
|
|
```
|
|
|
|
## Admin Partition Definition
|
|
|
|
Admin partitions are managed exclusively through the HTTP API and the Consul CLI. The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
|
|
|
|
The following parameters are supported in admin partition definition files:
|
|
|
|
| Option | Description | Default | Required |
|
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
|
|
| `Name` | String value that specifies the name of partition you are creating or writing. <br/> The value must be valid DNS hostname value. | none | Required |
|
|
| `Description` | String value that specifies a description for the partition you are creating or writing. <br/> The value should provide human-readable information to help other users understand the purpose of the partition. | none | Optional |
|
|
|
|
### Example Definition File
|
|
|
|
The following example shows an admin partition definition file that could be used with the [`write`](#write) command to create a partition:
|
|
|
|
```hcl
|
|
Name = "dev-partition"
|
|
Description = "Partition for dev team"
|
|
```
|
|
|
|
## HTTP API Options
|
|
|
|
You can include the following options to interact with the HTTP API when using the `partition` command.
|
|
|
|
| Option | Description | Default | Required |
|
|
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------- |
|
|
| `-ca-file` | Specifies the path to a certificate authority (CA) file when TLS is enabled.<br/> You can also specify `CONSUL_CACERT` as the value if the environment variable is configured. | none | Required if TLS is enabled |
|
|
| `-ca-path` | Specifies the path to a client certificate file when TLS is enabled. <br/> You can also specify `CONSUL_CAPATH` as the value if the environment variable is configured. | none | Required if TLS is enabled |
|
|
| `-client-cert` | Specifies the path to a client certificate file when TLS and the `verify_incoming` option are enabled. <br/> You can also specify `CONSUL_CLIENT_CERT` as the value if the environment variable is configured. | none | Required if TLS and `verify_incoming` are enabled |
|
|
| `-client-key` | Specifies the path to a client key file when TLS and the `verify_incoming` option are enabled. <br/> You can also specify `CONSUL_CLIENT_KEY` as the value if the environment variable is configured. | none | Required if TLS and `verify_incoming` are enabled |
|
|
| `-datacenter` | Specifies the name of the datacenter to query. <br/> Non-default admin partitions are only supported in the primary datacenter. | Datacenter of the queried agent | Required if the agent is in a non-primary datacenter. |
|
|
| `-http-addr` | Specifies the address and port number of the Consul HTTP agent. <br/>IP and DNS addresses are supported. The address must also include the port. <br/>You can also specify `CONSUL_HTTP_ADDR` if the environment variable is configured. <br/>To use an HTTPS address, set the `CONSUL_HTTP_SSL` environment variable to `true`. | `http://127.0.0.1:8500` | Optional |
|
|
| `-stale` | Boolean value that enables any Consul server (non-leader) to respond to the request. <br/>This switch can lower latency and increase throughput, but may result in stale data. This option has no effect on non-read operations. | `false` | Optional |
|