Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
  • Commands (CLI)
    • Overview
      • Overview
      • create
      • delete
      • list
      • read
      • update
      • Overview
      • create
      • delete
      • list
      • read
      • update
    • bootstrap
      • Overview
      • create
      • delete
      • list
      • read
      • update
      • Overview
      • create
      • delete
      • list
      • read
      • update
    • set-agent-token
      • Overview
      • clone
      • create
      • delete
      • list
      • read
      • update
    • translate-rules
  • agent
    • Overview
    • datacenters
    • nodes
    • services
    • Overview
    • delete
    • list
    • read
    • write
    • Overview
    • ca
    • proxy
    • envoy
    • expose
    • redirect-traffic
  • debug
  • event
  • exec
  • force-leave
  • info
    • Overview
    • check
    • create
    • delete
    • get
    • list
    • match
  • join
  • keygen
  • keyring
    • Overview
    • delete
    • export
    • get
    • import
    • put
  • leave
  • license
  • lock
  • login
  • logout
  • maint
  • members
  • monitor
    • Overview
    • create
    • delete
    • list
    • read
    • update
    • write
    • Overview
    • area
    • autopilot
    • raft
  • partition
  • reload
  • rtt
    • Overview
    • register
    • deregister
    • Overview
    • agent
    • inspect
    • restore
    • save
    • Overview
    • ca
    • cert
  • validate
  • version
  • watch
Type '/' to Search

»Consul Admin Partition

Command: consul partition

Enterprise

This feature requires Consul Enterprise.

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

consul partition <SUBCOMMAND> <OPTIONS>
consul partition <SUBCOMMAND> <OPTIONS>

Issue the consul partition -h command to view the subcommands.

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

consul partition create <OPTIONS>
consul partition create <OPTIONS>

The admin partition is created according to the values specified in the options. You can specify the following options:

OptionDescriptionDefaultRequired
-nameString value that specifies the name for the new partition.noneRequired
-description        String value that specifies a description of the new partition.noneOptional
-formatSpecifies how to format the output of the operation in the console.noneOptional
-show-metaPrints 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.
DisabledOptional

In the following example, a partition named webdev is created:

$ 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
}
$ 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.

Use the following syntax to write from file:

consul partition write <OPTIONS> <FILE>
consul partition write <OPTIONS> <FILE>

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 section for details about the supported parameters.

You can specify the following options:

OptionDescriptionDefaultRequired
-formatSpecifies how to format the output of the operation in the console.noneOptional
-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.
DisabledOptional

In the following example, the webdev-bu partition is written using stdin values:

$ 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
}
$ 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.

consul partition read <OPTIONS> <PARTITION_NAME>
consul partition read <OPTIONS> <PARTITION_NAME>

The admin partition is created according to the values specified in the options. You can specify the following options:

OptionDescriptionDefaultRequired
-format    Specifies how to format the output of the operation in the console.noneOptional
-metaPrints 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.
DisabledOptional

In the following example, the configuration for the webdev partition is read:

consul partition read -format json -meta webdev

{
   "Name": "webdev",
   "CreateIndex": 940,
   "ModifyIndex": 1458
}
consul partition read -format json -meta webdev

{
   "Name": "webdev",
   "CreateIndex": 940,
   "ModifyIndex": 1458
}

»list

The list subcommand prints existing admin partitions to the console.

consul partition list <OPTIONS>
consul partition list <OPTIONS>

The admin partition is created according to the values specified in the options. You can specify the following options:

OptionDescriptionDefaultRequired
-formatSpecifies how to format the output of the operation in the console.noneOptional
-show-metaPrints 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.
DisabledOptional

The following example lists the admin partitions and their meta data in JSON format:

$ 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
   }
]
$ 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.

$ consul partition delete <PARTITION_NAME>
$ consul partition delete <PARTITION_NAME>

In the following example, the webdev-bu partition is deleted:

consul partition delete webdev
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:

OptionDescriptionDefaultRequired
NameString value that specifies the name of partition you are creating or writing.
The value must be valid DNS hostname value.
noneRequired
DescriptionString 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.
noneOptional

»Example Definition File

The following example shows an admin partition definition file that could be used with the write command to create a partition:

Name = "dev-partition"
Description = "Partition for dev team"
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.

OptionDescriptionDefaultRequired
-ca-fileSpecifies 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.
noneRequired if TLS is enabled
-ca-pathSpecifies 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.
noneRequired if TLS is enabled
-client-certSpecifies 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.
noneRequired if TLS and verify_incoming are enabled
-client-keySpecifies 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.
noneRequired if TLS and verify_incoming are enabled
-datacenterSpecifies the name of the datacenter to query.
Non-default admin partitions are only supported in the primary datacenter.
Datacenter of the queried agentRequired if the agent is in a non-primary datacenter.
-http-addrSpecifies 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:8500Optional
-staleBoolean 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.
falseOptional
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager