Feature gate operator HTTP API

The Consul feature gate HTTP API lists, reads, and updates feature gates. A feature gate is a datacenter-wide switch, similar to a feature flag, that turns experimental Consul functionality on or off without restarting agents. Use the /operator/features endpoint to list every gate, and use the /operator/feature/:name endpoint to read or update one gate. For conceptual information, refer to Feature gates.

The corresponding CLI command is consul operator feature.

List feature gates

This endpoint lists every feature gate that the Consul servers in the datacenter register, along with the desired and effective state of each gate.

Method	Path	Produces
`GET`	`/operator/features`	`application/json`

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`operator:read`

Query parameters

dc (string: "") - Specifies the datacenter to query. This defaults to the datacenter of the agent that receives the request.
stale (bool: false) - If the datacenter has no leader, the endpoint returns an error. You can use the ?stale query parameter to read the feature gates from any of the Consul servers.

Sample request

$ curl \
    http://127.0.0.1:8500/v1/operator/features

Sample response

[
  {
    "Name": "api-gateway-upstream-routing",
    "Stage": "experimental",
    "MinVersion": "2.1.0",
    "DefaultEnabled": false,
    "BeforeMinimumVersion": "disabled",
    "Description": "Compose API Gateway HTTPRoutes with upstream routing policy",
    "Owner": "proxycfg",
    "DesiredEnabled": false,
    "EffectiveEnabled": false,
    "Eligible": true,
    "Source": "registry-default",
    "Reason": "default-disabled",
    "PolicyIndex": 24,
    "StatusIndex": 24
  },
  {
    "Name": "consul-ai",
    "Stage": "experimental",
    "MinVersion": "2.1.0",
    "DefaultEnabled": false,
    "BeforeMinimumVersion": "disabled",
    "Description": "Enable Consul AI Features",
    "Owner": "camp",
    "DesiredEnabled": false,
    "EffectiveEnabled": false,
    "Eligible": true,
    "Source": "registry-default",
    "Reason": "default-disabled",
    "PolicyIndex": 24,
    "StatusIndex": 24
  },
  {
    "Name": "localized-dns",
    "Stage": "experimental",
    "MinVersion": "2.1.0",
    "DefaultEnabled": false,
    "BeforeMinimumVersion": "disabled",
    "Description": "Add inline virtual DNS and egress recursor DNS listeners to connect-proxy sidecars",
    "Owner": "proxycfg",
    "DesiredEnabled": false,
    "EffectiveEnabled": false,
    "Eligible": true,
    "Source": "registry-default",
    "Reason": "default-disabled",
    "PolicyIndex": 24,
    "StatusIndex": 24
  },
  {
    "Name": "peering-multiport-upstreams",
    "Stage": "experimental",
    "MinVersion": "2.1.0",
    "DefaultEnabled": false,
    "BeforeMinimumVersion": "disabled",
    "Description": "Enable multiport peering upstream expansion for proxycfg/xDS",
    "Owner": "xds",
    "DesiredEnabled": true,
    "EffectiveEnabled": true,
    "Eligible": true,
    "Source": "operator",
    "Reason": "operator-enabled",
    "PolicyIndex": 24,
    "StatusIndex": 24
  }
]

If the leader has not yet committed the first feature gate policy, the endpoint returns an empty list and sets the X-Consul-Feature-Gates-Uninitialized: true response header. The X-Consul-Index header lets you block until the leader commits the policy. Refer to Blocking queries for more information.

Refer to Feature gate response fields for a description of each field.

Read a feature gate

This endpoint returns the state of one feature gate.

Method	Path	Produces
`GET`	`/operator/feature/:name`	`application/json`

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`operator:read`

Path parameters

name (string: <required>) - Specifies the name of the feature gate to read.

Query parameters

dc (string: "") - Specifies the datacenter to query. This defaults to the datacenter of the agent that receives the request.
stale (bool: false) - If the datacenter has no leader, the endpoint returns an error. You can use the ?stale query parameter to read the feature gate from any of the Consul servers.

Sample request

$ curl \
    http://127.0.0.1:8500/v1/operator/feature/peering-multiport-upstreams

Sample response

{
  "Name": "peering-multiport-upstreams",
  "Stage": "experimental",
  "MinVersion": "2.1.0",
  "DefaultEnabled": false,
  "BeforeMinimumVersion": "disabled",
  "Description": "Enable multiport peering upstream expansion for proxycfg/xDS",
  "Owner": "xds",
  "DesiredEnabled": true,
  "EffectiveEnabled": true,
  "Eligible": true,
  "Source": "operator",
  "Reason": "operator-enabled",
  "PolicyIndex": 24,
  "StatusIndex": 24
}

The endpoint returns the following status codes:

Status	Description
`200`	The request succeeded.
`404`	The name does not match a registered feature gate.
`503`	The leader has not yet committed the first feature gate policy. Retry the request.

Update a feature gate

This endpoint enables or disables a feature gate. Consul records the value as the desired state and resolves the effective state in the same operation.

Method	Path	Produces
`PUT`	`/operator/feature/:name`	`application/json`

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`operator:write`

Path parameters

name (string: <required>) - Specifies the name of the feature gate to update.

Query parameters

dc (string: "") - Specifies the datacenter to update. This defaults to the datacenter of the agent that receives the request.
cas (int: 0) - Performs a check-and-set (CAS) operation that applies the change only if the current policy index matches this value. The value is the PolicyIndex that the read endpoints return. If the index does not match, Consul does not change the gate and the response sets Applied to false. A value of 0 or no value skips the check.

JSON request body schema

Enabled (bool: <required>) - Specifies whether to enable the feature gate.

Sample payload

{
  "Enabled": false
}

Sample request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/operator/feature/peering-multiport-upstreams

Sample response

{
  "Applied": true,
  "Feature": {
    "Name": "peering-multiport-upstreams",
    "Stage": "experimental",
    "MinVersion": "2.1.0",
    "DefaultEnabled": false,
    "BeforeMinimumVersion": "disabled",
    "Description": "Enable multiport peering upstream expansion for proxycfg/xDS",
    "Owner": "xds",
    "DesiredEnabled": false,
    "EffectiveEnabled": false,
    "Eligible": true,
    "Source": "operator",
    "Reason": "operator-disabled",
    "PolicyIndex": 25,
    "StatusIndex": 25
  }
}

The response contains the following fields:

Applied is true when Consul commits the change and false when a cas check failed. When Applied is false, Feature contains the current state.
Feature is the resulting state of the feature gate. Refer to Feature gate response fields.

If you specify a cas value that does not match the current policy index, the endpoint returns a 200 status code, Applied is false, and Feature shows the unchanged state. For example, the following request uses cas=1 when the current policy index is 25:

$ curl \
    --request PUT \
    --data @payload.json \
    "http://127.0.0.1:8500/v1/operator/feature/peering-multiport-upstreams?cas=1"

The endpoint returns the following response:

{
  "Applied": false,
  "Feature": {
    "Name": "peering-multiport-upstreams",
    "Stage": "experimental",
    "MinVersion": "2.1.0",
    "DefaultEnabled": false,
    "BeforeMinimumVersion": "disabled",
    "Description": "Enable multiport peering upstream expansion for proxycfg/xDS",
    "Owner": "xds",
    "DesiredEnabled": false,
    "EffectiveEnabled": false,
    "Eligible": true,
    "Source": "operator",
    "Reason": "operator-disabled",
    "PolicyIndex": 25,
    "StatusIndex": 25
  }
}

The endpoint returns the following status codes:

Status	Description
`200`	The request was processed. Check `Applied` to determine whether Consul committed the change.
`400`	The request body or the `cas` value is not valid. For example, `error parsing cas value: strconv.ParseUint: parsing "abc": invalid syntax`.
`404`	The name does not match a registered feature gate.
`503`	The leader has not yet committed the first feature gate policy. Retry the request.

Feature gate response fields

Name - The name of the feature gate.
Stage - The maturity of the feature. The value is experimental for all feature gates.
MinVersion - The Consul version that every server in the datacenter must run before the gate can take effect.
DefaultEnabled - Whether the gate is on when no operator or bootstrap setting exists.
BeforeMinimumVersion - The state of the gate while the servers do not meet MinVersion. The value is disabled.
Description - A short description of the functionality that the gate controls.
Owner - The Consul component that owns the feature.
DesiredEnabled - The state that the operator or the bootstrap configuration requested. If neither set a value, the value is DefaultEnabled.
EffectiveEnabled - The state that Consul applies. Agents use this value.
Eligible - Whether every server in the datacenter meets MinVersion.
Source - Where DesiredEnabled came from. The value is registry-default, bootstrap, or operator.
Reason - The reason for the effective state. Refer to Feature gate states for the possible values.
PolicyIndex - The Raft index of the policy that holds the desired state. Use this value as the cas parameter.
StatusIndex - The Raft index of the resolved state.