Admin Partition - HTTP API

The functionality described here is available only in Consul Enterprise version 1.11.0 and later.

Create a Partition

This endpoint creates a new partition and has the following characteristics:

JSON Request Body Schema

• Name (string: <required>) - The partition name. This field must be a valid DNS hostname label.

• Description (string: "") - Free form partition description.

Sample Payload

{
  "Name": "na-west",
  "Description": "Partition for North America West"
}

Sample Request

$ curl ---request PUT \
   --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   --data @payload.json \
   http://127.0.0.1:8500/v1/partition

Sample Response

{
  "Name": "na-west",
  "Description": "Partition for North America West",
  "CreateIndex": 55,
  "ModifyIndex": 55
}

Read a Partition

This endpoint reads a partition with the given name and has the following characteristics:

Path Parameters

• name (string: <required>) - Specifies the partition to read.

Sample Request

$ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
   http://127.0.0.1:8500/v1/partition/na-west

Sample Response

{
  "Name": "na-west",
  "Description": "Partition for North America West",
  "CreateIndex": 55,
  "ModifyIndex": 55
}

Update a Partition

This endpoint updates a partition description and has the following characteristics:

Path Parameters

• name (string: <required>) - Specifies the partition to update. This parameter must be a valid DNS hostname label.

JSON Request Body Schema

• Name (string: <optional>) - If specified, this field must be an exact match with the name path parameter.

• Description (string: "") - Free form partition description.

• DisableGossip (bool: false) - Disable gossip support for this partition. When set to true this will save on CPU and network resources on the servers but client agents will be unable to join the partition.

Sample Payload

{
  "Description": "North America West Partition"
}

Sample Request

$ curl --request PUT \
   --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   --data @payload.json \
   http://127.0.0.1:8500/v1/partition/na-west

Sample Response

{
  "Name": "na-west",
  "Description": "North America West Partition",
  "CreateIndex": 55,
  "ModifyIndex": 60
}

Delete a Partition

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. 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 marked for deletion.

This endpoint has the following characteristics:

Path Parameters

• name (string: <required>) - Specifies the partition to delete.

Sample Request

$ curl --request DELETE \
   --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \
   http://127.0.0.1:8500/v1/partition/na-west

Sample Read Output After Deletion Prior to Removal

{
  "Name": "na-west",
  "Description": "North America West Partition",
  "DeletedAt": "2021-12-14T23:00:00Z",
  "CreateIndex": 55,
  "ModifyIndex": 100
}

List all Partitions

This endpoint lists all the partitions and has the following characteristics:

Sample Request

$ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \
   http://127.0.0.1:8500/v1/partitions

Sample Response

[
  {
    "Name": "default",
    "Description": "Builtin Default Partition",
    "CreateIndex": 6,
    "ModifyIndex": 6
  },
  {
    "Name": "na-west",
    "Description": "North America West Partition",
    "DisableGossip": true,
    "CreateIndex": 55,
    "ModifyIndex": 55
  }
]