Consul Admin Partition
Command: consul partition
This feature requires Consul Enterprise(opens in new tab).
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
Issue the consul partition -h
command to view the subcommands.
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 |
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. 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:
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 |
Use the following syntax to write from file:
Use the following syntax to write from stdin
:
The definition file or stdin
values can be provided in JSON or HCL format. Refer to the 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. 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:
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 |
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. 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:
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 |
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. 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:
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 |
In the following example, the webdev-bu
partition is deleted:
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. 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. 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
command to create a partition:
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. 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. 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. 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. 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. 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. IP and DNS addresses are supported. The address must also include the port. You can also specify CONSUL_HTTP_ADDR if the environment variable is configured. 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. 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 |