HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul Home

Consul Operator Feature

Command: consul operator feature

The consul operator feature command lists, inspects, and changes the feature gates in a Consul datacenter. A feature gate is a datacenter-wide switch, similar to a feature flag, that turns experimental Consul functionality on or off without restarting agents. For conceptual information, refer to Feature gates.

Usage: consul operator feature <subcommand> [options]

  Inspect or update cluster-wide feature gates. A token with operator
  privileges is required when ACLs are enabled.

Subcommands:
    get     Get a cluster feature gate
    list    List cluster feature gates
    set     Set a cluster feature gate

Refer to the following sections for information, examples, and usage for each subcommand:

list

Corresponding HTTP API Endpoint: [GET] /v1/operator/features

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

The following table shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.

ACL Required
operator:read

Usage: consul operator feature list [options]

The following example shows the command output:

$ consul operator feature list
Name                          Stage         Desired  Effective  Eligible  Source            Reason            Min Version  Policy Index  Status Index
api-gateway-upstream-routing  experimental  false    false      true      registry-default  default-disabled  2.1.0        24            24
consul-ai                     experimental  false    false      true      registry-default  default-disabled  2.1.0        24            24
localized-dns                 experimental  false    false      true      registry-default  default-disabled  2.1.0        24            24
peering-multiport-upstreams   experimental  true     true       true      operator          operator-enabled  2.1.0        24            24

If the leader has not yet committed the first feature gate policy, the command prints no gates and displays the following warning:

No feature gates found. The leader may not have initialized the feature-gate policy yet; retry in a few seconds.

This situation occurs on a new datacenter or immediately after you upgrade the servers. Wait several seconds and run the command again.

Command options

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

get

Corresponding HTTP API Endpoint: [GET] /v1/operator/feature/:name

This command displays the desired state, eligibility, and effective state of one feature gate.

The following table shows this command's required ACLs.

ACL Required
operator:read

Usage: consul operator feature get [options] <name>

The following example shows the command output:

$ consul operator feature get peering-multiport-upstreams
Name                         Stage         Desired  Effective  Eligible  Source    Reason            Min Version  Policy Index  Status Index
peering-multiport-upstreams  experimental  true     true       true      operator  operator-enabled  2.1.0        24            24

To display every field that the command returns, including the gate's description and owner, use the -format=json option. The JSON output is a list that contains one object:

$ consul operator feature get -format=json peering-multiport-upstreams
[
  {
    "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
  }
]

Refer to Feature gate states for a description of each field.

Command options

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

set

Corresponding HTTP API Endpoint: [PUT] /v1/operator/feature/:name

This command enables or disables a feature gate for the datacenter. Consul records your choice as the desired state and resolves the effective state in the same operation. Refer to Feature gate states for more information.

The following table shows this command's required ACLs.

ACL Required
operator:write

Usage: consul operator feature set [options] <name> <enabled|disabled>

The value must be enabled or disabled. The command also accepts true and false. You can place options before or after the positional arguments.

The following example enables the peering-multiport-upstreams feature gate:

$ consul operator feature set peering-multiport-upstreams enabled
Name                         Stage         Desired  Effective  Eligible  Source    Reason            Min Version  Policy Index  Status Index
peering-multiport-upstreams  experimental  true     true       true      operator  operator-enabled  2.1.0        24            24

If an operator already set the gate to the value you specify, the command succeeds and does not create a new policy generation.

If you enable a gate before every server in the datacenter runs the gate's minimum version, Consul records the desired state, but the effective state remains false until the servers meet the minimum version. The Reason column displays below-minimum-version.

Command options

  • -cas=<index> - Perform a check-and-set (CAS) operation that applies the change only if the current policy index matches this value. The default is no check.

  • -format={pretty|json} - Command output format. The default value is pretty.

Prevent conflicting updates

Use the -cas option to apply a change only if no one else has modified the feature gate policy since you read it. The value is the PolicyIndex that consul operator feature get returns. If the index does not match, Consul does not change the gate and the command exits with an error.

The following example reads the current policy index and then uses it to update the gate:

$ INDEX=$(consul operator feature get -format=json peering-multiport-upstreams | jq '.[0].PolicyIndex')

$ consul operator feature set -cas=$INDEX peering-multiport-upstreams disabled

If another change has already moved the policy index, the command exits with a non-zero status and displays the following message:

$ consul operator feature set -cas=1 peering-multiport-upstreams disabled
Feature gate was not updated because policy index 1 did not match

An empty or 0 value, or the string null, disables the check.

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

Edit this page on GitHub