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.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul partition create.

Parameters

• Name (string: <required>) - The partition name. This 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

SampleResponse

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

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul partition read.

Parameters

• name (string: <required>) - Specifies the partition to read. This is required and is specified as part of the URL path.

Sample Request

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

SampleResponse

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

Update a Partition

This endpoint updates a Partition description.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul partition write.

Parameters

• Name (string: <optional>) - The partition name. This must be a valid DNS hostname label. If present in the payload it must match what was given in the URL path.

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

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

SampleResponse

{
  "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 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, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul partition delete.

Parameters

• name (string: <required>) - Specifies the partition to delete. This is required and is specified as part of the URL path.

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.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul partition list.

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",
    "CreateIndex": 55,
    "ModifyIndex": 55
  }
]