Consul
Global rate limit configuration entry reference
This page provides reference information for rate limit configuration entries. Rate limits enable Consul operators to set global RPC caps, implement emergency throttling, exempt critical endpoints, and provide better observability across the entire cluster.
Enterprise
This feature requires Consul Enterprise. Refer to the enterprise feature matrix for additional information.
Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in the rate limit configuration entry. Click on a property name to view additional details, including default values.
Complete configuration
When every field is defined, a rate limit configuration entry has the following form:
Kind = "rate-limit" # required
Name = "global" # required
config { # required
readRate = 100
writeRate = 100
priority = true
excludeEndpoints = ["<excluded.endpoint.1>", "<excluded.endpoint.2>", "..."]
}
Specifications
This section provides details about the fields you can configure in the rete limit configuration entry.
Kind
Specifies the type of configuration entry to implement. Must be set to rate-limit.
Values
- Default: None
- This field is required.
- Data type: String value that must be set to
rate-limit.
Name
Specifies a name for the configuration entry that is used to identify the rate limit. Must be set to global to ensure only one active rate-limit configuration per cluster.
Values
- Default: None
- This field is required.
- Data type: String
Config
Map that contains the details about the rate-limit configuration entry.
Values
- Default: None
- This field is required.
- Data type: List that can contain maps of the following parameters:
Config[].ReadRate
Specifies the read limit applied to the cluster.
Values
- Default:
100 - Data type: Number
Config[].WriteRate
Specifies the write limit applied to the cluster.
Values
- Default:
100 - Data type: Number
Config[].Priority
Specifies if the rate limit must be enforced by the cluster. The limit is enforced only if priority flag is enabled. If the priority flag is false, then only other existing server-wide rate limiter are enforced: read/write server rate limits or IP-based rate limits.
The config entry limit is evaluated first and enforces limits only when priority flag is enabled. Priority endpoints like health checks always bypass rate limiting.
Values
- Default:
true - Data type: boolean
Config[].ExcludeEndpoints
Specifies an optional list of endpoints that will be excluded from the rate limit configuration.
Values
- Default: None
- Data type: List of strings
Kubernetes
Admin partitions and ACL environments
When admin partitions and ACLs are both enabled, you must provide a dedicated operator-level ACL token for the global config rate limiter controller. Without this token, reconciliation may fail even when consul config write succeeds.
Create a Kubernetes secret that holds the token.
apiVersion: v1
kind: Secret
metadata:
name: consul-global-config-acl-token
namespace: <namespace>
type: Opaque
stringData:
token: <operator-write-token>
Reference the secret in your Helm values.
connectInject:
globalConfigACLToken:
secretName: consul-global-config-acl-token
secretKey: token
Examples
The following examples demonstrate common rate limit configuration patterns for specific use cases.
Apply a global rate limit to all endpoints excluding the health checks
In the following example, the configuration entry defines a that applies a global rate limit of 200 write requests and 300 read requests.
Kind = "rate-limit"
Name = "global"
Config {
ReadRate = 100
WriteRate = 50
Priority = true
ExcludeEndpoints = ["Health.ServiceNodes"]