HTTP route configuration entry reference

This topic provides reference information for the gateway routes configuration entry. Refer to Route Resource Configuration for information about configuring API gateway routes in Kubernetes environments.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in an http-route configuration entry. Click on a property name to view additional details, including default values.

• Kind: string | must be http-route
• Name: string | no default
• Namespace: string | no default
  Enterprise
• Partition: string | no default
  Enterprise
• Meta: map | no default
• Hostnames: list | no default
• Parents: list | no default
  • Kind: string | must be api-gateway
  • Name: string | no default
  • Namespace: string | no default
    Enterprise
  • Partition: string | no default
    Enterprise
  • SectionName: string | no default
• Rules: list | no default
  • Filters: map | no default
    • ExtAuthz: map | none
      Enterprise
      • Enabled: boolean | no default
  • ResponseFilters: map | no default
  • Matches: list | no default
    • Headers: list | no default
      • Name: string | no default
      • Match: string | no default
      • Value: string | no default
      • Invert: boolean | false
  • Services: list | no default
    • Name: string | no default
    • Namespace: string
      Enterprise
    • Partition: string
      Enterprise
    • Weight: number | 1
    • Limits: map | none
      • MaxConnections: number | none
      • MaxPendingRequests: number | none
      • MaxConcurrentRequests: number | none
      • PassiveHealthCheck: map | none
        • Interval: string | none
        • MaxFailures: number | none
        • Consecutive5xx: number | none
        • ConsecutiveGatewayFailure: number | none
        • EnforcingConsecutive5xx: number | none
        • EnforcingConsecutiveGatewayFailure: number | none
        • MaxEjectionPercent: number | none
        • BaseEjectionTime: string | none
    • Filters: map | no default
    • ResponseFilters: map | no default
    • TLS: map | no default
      • SDS: map | no default
        • ClusterName: string | inherited when omitted
        • CertResource: string | required when SDS is set

TLS SDS precedence and validation

For downstream certificate selection on API Gateway, Consul resolves TLS/SDS in this order:

1. http-route service override (Rules[].Services[].TLS.SDS)
2. API gateway listener TLS.SDS
3. API gateway top-level TLS.SDS

Validation notes for HTTP route service SDS:

• Rules[].Services[].TLS.SDS.CertResource is required when SDS is configured.
• Hostnames must be set when any service-level TLS.SDS override is configured.
• If Rules[].Services[].TLS.SDS.ClusterName is omitted, Consul inherits from effective listener TLS/SDS config.
• Conflicting hostname-to-SDS mappings on the same listener are rejected.

Complete configuration

When every field is defined, an http-route configuration entry has the following form:

Kind = "http-route"
Name = "<name of the route>"
Namespace = "<enterprise: namespace of the service>"
Partition = "<enterprise: partition of the service>"
Meta = {
  "<any key>" = "<any value>"
}
Hostnames = ["<hostnames for which this HTTPRoute should respond to requests>"]

Parents = [
  {
    Kind = "api-gateway"
    Name = "<name of the api-gateway to bind to>"
    Namespace = "<enterprise: namespace of the service>"
    Partition = "<enterprise: partition of the service>"
    SectionName = "<optional name of a specific listener on the api-gateway to bind to>"
  }
]

Rules = [
  {
    Filters = {
      Headers = [
        {
          Add = {
            "<name of header to add>" = "<value of header to add>"
          }
          Remove = [
            "<name of header to remove from request>"
          ]
          Set = {
            "<name of header to set>" = "<value of header to set>"
          }
        }
      ]
      URLRewrite = {
        Path = "<path to rewrite request to>"
      }
      RetryFilter = {
        NumRetries = 1
        RetryOnConnectionFailure = false
        RetryOn = ["5xx"]
        RetryOnStatusCodes = [429]
      }
      TimeoutFilter = {
        IdleTimeout = "0s"
        RequestTimeout = "0s"
      }
      JWT = {
        Providers = [
          {
            Name = "<name of the provider>"
            VerifyClaims = {
              Path = ["<path to claim>"]
              Value = "<value of claim>"
            }
          }
        ]
      }
      ExtAuthz = {
        Enabled = true
      }
    }
    ResponseFilters = {
      Headers = [
        {
          Add = {
            "<name of header to add>" = "<value of header to add>"
          }
          Remove = [
            "<name of header to remove from response>"
          ]
          Set = {
            "<name of header to set>" = "<value of header to set>"
          }
        }
      ]
    }
    Matches = [
      {
        Headers = [
          {
            Match = "<type of match: exact, prefix or regex>"
            Name = "<name of header to match on>"
            Value = "<value of header to match on>"
            Invert = false
          }
        ]
        Method = "<method type to match on>"
        Path = {
          Match = "<type of match: exact, prefix or regex>"
          Value = "<value to match on>"
        }
        Query = [
          {
            Match = "<type of match: exact, present or regex>"
            Name = "<name of query parameter to match on>"
            Value = "<value of query parameter to match on>"
          }
        ]
      }
    ]
    Services = [
      {
        Name = "<name of Consul service to route to>"
        Namespace = "<enterprise: namespace of the service>"
        Partition = "<enterprise: partition of the service>"
        Weight = 1
        Limits = {
          MaxConnections = <number>
          MaxPendingRequests = <number>
          MaxConcurrentRequests = <number>
          PassiveHealthCheck = {
            Interval = "<time between ejection analysis sweeps>"
            MaxFailures = <number>
            EnforcingConsecutive5xx = <percentage>
            MaxEjectionPercent = <percentage>
            BaseEjectionTime = "<base ejection duration>"
          }
        }
        Filters = {
          Headers = [
            {
              Add = {
                "<name of header to add>" = "<value of header to add>"
              }
              Remove = [
                "<name of header to remove from request>"
              ]
              Set = {
                "<name of header to set>" = "<value of header to set>"
              }
            }
          ]
          URLRewrite = {
            Path = "<path to rewrite request to>"
          }
        }
        ResponseFilters = {
          Headers = [
            {
              Add = {
                "<name of header to add>" = "<value of header to add>"
              }
              Remove = [
                "<name of header to remove from response>"
              ]
              Set = {
                "<name of header to set>" = "<value of header to set>"
              }
            }
          ]
        }
        TLS = {
          SDS = {
            ClusterName = "<optional service override sds cluster>"
            CertResource = "<service override cert resource>"
          }
        }
      }
    ]
  }
]

{
  "Kind": "http-route",
  "Name": "<name of the route>",
  "Namespace": "<enterprise: namespace of the route>",
  "Partition": "<enterprise: partition of the route>",
  "Meta": {
    "<any key>": "<any value>"
  },
  "Hostnames": [
    "<hostnames for which this HTTPRoute should respond to requests>"
  ],
  "Parents": [
    {
      "Kind": "api-gateway",
      "Name": "<name of the api-gateway to bind to>",
      "Namespace": "<enterprise: namespace of the route>",
      "Partition": "<enterprise: partition of the route>",
      "SectionName": "<optional name of a specific listener on the api-gateway to bind to>"
    }
  ],
  "Rules": [
    {
      "Filters": {
        "Headers": [
          {
            "Add": {
              "<name of header to add>": "<value of header to add>"
            },
            "Remove": ["<header to remove from request>"],
            "Set": {
              "<name of header to set>": "<value of header to set>"
            }
          }
        ],
        "URLRewrite": {
          "Path": "<path to rewrite request to>"
        },
        "RetryFilter": {
          "NumRetries": 1,
          "RetryOnConnectionFailure": false,
          "RetryOn": ["5xx"],
          "RetryOnStatusCodes": [429]
        },
        "TimeoutFilter": {
          "IdleTimeout": "0s",
          "RequestTimeout": "0s"
        },
        "JWT": {
          "Providers": [
            {
              "Name": "okta",
              "VerifyClaims": {
                "Path": ["perms", "role"],
                "Value": "user"
              }
            }
          ]
        },
        "ExtAuthz": {
          "Enabled": true
        }
      },
      "Matches": [
        {
          "Headers": [
            {
              "Invert": false,
              "Match": "<type of match: exact, prefix or regex>",
              "Name": "<name of header to match on>",
              "Value": "<value of header to match on>"
            }
          ],
          "Method": "<method type to match on>",
          "Path": {
            "Match": "<type of match: exact, prefix or regex>",
            "Value": "<value to match on>"
          },
          "Query": [
            {
              "Match": "<type of match: exact, present or regex>",
              "Name": "<name of query parameter to match on>",
              "Value": "<value of query parameter to match on>"
            }
          ]
        }
      ],
      "Services": [
        {
          "Name": "<name of Consul service to route to>",
          "Namespace": "<enterprise: namespace of the route>",
          "Partition": "<enterprise: partition of the route>",
          "Weight": 1,
          "Limits": {
            "MaxConnections": <number>,
            "MaxPendingRequests": <number>,
            "MaxConcurrentRequests": <number>,
            "PassiveHealthCheck": {
              "Interval": "<time between ejection analysis sweeps>",
              "MaxFailures": <number>,
              "EnforcingConsecutive5xx": <percentage>,
              "MaxEjectionPercent": <percentage>,
              "BaseEjectionTime": "<base ejection duration>"
            }
          },
          "TLS": {
            "SDS": {
              "ClusterName": "<optional service override sds cluster>",
              "CertResource": "<service override cert resource>"
            }
          }
        }
      ]
    }
  ]
}

Specification

This section provides details about the fields you can configure in the http-route configuration entry.

Kind

Specifies the type of configuration entry to implement. For HTTP routes, this must be http-route.

Values

• Default: none
• This field is required.
• Data type: string value that must be set to "http-route".

Name

Specifies a name for the configuration entry.

Values

• Default: none
• This field is required.
• Data type: string

Hostnames[]

Specifies the hostnames for which this route responds.

Values

• Default: none
• Data type: list of strings

Parents[]

Specifies the list of gateways this route binds to.

An http-route can bind to API gateway listeners that use the http, http2, or grpc protocol. Refer to Listeners[].Protocol in the API gateway configuration reference for more information.

Values

• Default: none
• Data type: list of maps with Kind, Name, Namespace, Partition, SectionName

Rules[]

Specifies the list of HTTP routing rules used to construct the route table.

Values

• Default: none
• Data type: list of maps containing Filters, ResponseFilters, Matches, and Services

Rules[].Matches[]

Specifies the conditions that a request must meet to match the rule. A request matches the rule when it meets all conditions in any one of the Matches entries.

Values

• Default: none
• Data type: list of maps that can contain Headers, Method, Path, and Query

Rules[].Matches[].Headers[]

Specifies HTTP header conditions that a request must meet to match the rule. A request must meet every condition in the list. The following table describes the fields you can configure for each header condition:

You can specify the following values in the Match field:

• exact: The header value must equal Value.
• prefix: The header value must start with Value.
• suffix: The header value must end with Value.
• regex: The header value must match the regular expression in Value.
• present: The request must include the header, regardless of its value.

Values

• Default: none
• Data type: list of maps

Rules[].Matches[].Headers[].Invert

Negates the header condition. When set to true, the condition matches requests that do not meet the Match and Value criteria. Use Invert to route requests when a header is absent or when a header value does not equal a specific value.

The following table describes how Invert affects each match type:

For exact, prefix, suffix, and regex matches, an inverted condition does not match requests that do not include the header. To match requests that do not include a header, use the present match type with Invert = true.

Values

• Default: false
• Data type: boolean

Rules[].Services[]

Specifies services the gateway routes matching requests to.

When a rule has one service, Consul API Gateway evaluates the service's discovery chain. When the service uses a service-router to route requests to a service-resolver subset, Consul preserves the subset destination when it synthesizes the API gateway discovery chain. Consul combines the http-route match and service-router match, so requests must satisfy both sets of criteria to use the subset route.

Values

• Default: none
• Data type: list of maps with service details and optional per-service overrides.

Rules[].Services[].TLS

Specifies optional service-level TLS override configuration for API Gateway.

Values

• Default: none
• Data type: map containing SDS

Rules[].Services[].TLS.SDS

Specifies service-level SDS certificate override.

Values

• Default: none
• Data type: map containing:
  • ClusterName (optional, inherited when omitted)
  • CertResource (required)

Rules[].Services[].TLS.SDS.CertResource

Specifies the SDS certificate resource name to use for this service override.

Values

• Default: none
• This field is required when SDS is set.
• Data type: string

Rules[].Services[].TLS.SDS.ClusterName

Specifies the SDS cluster name for this service override.

Values

• Default: inherited from effective listener TLS/SDS when omitted
• Data type: string

Rules[].Filters{}.JWT

Specifies route-level JWT verification settings. These settings take precedence over listener default JWT configuration.

Values

• Default: none
• Data type: map

Rules[].Filters{}.ExtAuthz

Enterprise

Overrides the gateway-wide external authorization (ext_authz) default behavior for the routes matched by this rule. This filter only takes effect when a builtin/ext-authz Envoy extension with ProxyType = "api-gateway" is applied to the gateway. It takes precedence over the gateway-wide ExtAuthz toggle.

Values

• Default: none
• Data type: map

Rules[].Filters{}.ExtAuthz.Enabled

Enterprise

Specifies whether Envoy runs the external authorization check for requests matched by this rule. Set to true to force external authorization on for these routes, or false to skip it, regardless of the gateway-wide default.

Values

• Default: none
• Data type: boolean

Rules[].Services[].Limits

Specifies upstream circuit-breaker limits for this routed destination service.

These values override any gateway-level defaults configured in the parent api-gateway configuration entry. If the same upstream service is referenced by multiple routes or listeners attached to the same gateway, Consul applies the lowest non-zero value for each limit when generating the shared Envoy cluster.

Values

• Default: none. If unspecified, Consul uses the gateway-level default for the same field when available. Otherwise the proxy default applies.
• Data type: Map that can contain the following fields:
  • MaxConnections
  • MaxPendingRequests
  • MaxConcurrentRequests
  • PassiveHealthCheck

Rules[].Services[].Limits.MaxConnections

Specifies the maximum number of upstream connections this routed service is allowed to establish.

Values

• Default: none. If unspecified, Consul uses Defaults.MaxConnections when available.
• Data type: Integer

Rules[].Services[].Limits.MaxPendingRequests

Specifies the maximum number of requests that are allowed to queue while waiting to establish an upstream connection.

The attached API gateway listener must use an L7 protocol such as http, http2, or grpc for this configuration to take effect.

Values

• Default: none. If unspecified, Consul uses Defaults.MaxPendingRequests when available.
• Data type: Integer

Rules[].Services[].Limits.MaxConcurrentRequests

Specifies the maximum number of concurrent upstream requests that are allowed at a single point in time.

The attached API gateway listener must use an L7 protocol such as http, http2, or grpc for this configuration to take effect.

Values

• Default: none. If unspecified, Consul uses Defaults.MaxConcurrentRequests when available.
• Data type: Integer

Rules[].Services[].Limits.PassiveHealthCheck

Specifies the passive health check for this routed destination service. Passive health checks configure Envoy outlier detection, which removes service instances that return consecutive errors from the gateway's load balancing pool.

This value replaces the Defaults.PassiveHealthCheck value configured in the parent api-gateway configuration entry for this service. Consul does not merge individual fields from the gateway default into this value. When multiple routes or listeners attached to the same gateway reference the same upstream service with different passive health checks, Consul applies only one of them to the shared Envoy cluster. Configure the same passive health check for a service across all routes on a gateway.

The map can contain the following fields:

• Interval
• MaxFailures
• Consecutive5xx
• ConsecutiveGatewayFailure
• EnforcingConsecutive5xx
• EnforcingConsecutiveGatewayFailure
• MaxEjectionPercent
• BaseEjectionTime

Refer to Defaults.PassiveHealthCheck in the API gateway configuration reference for more information about the gateway default.

Values

• Default: none. If unspecified, Consul uses Defaults.PassiveHealthCheck when available. Otherwise, Envoy uses its default outlier detection settings.
• Data type: Map

Rules[].Services[].Limits.PassiveHealthCheck.Interval

Specifies the time between outlier detection analysis sweeps. Each sweep can eject hosts from the load balancing pool or return them to the pool.

Values

• Default: none. Envoy uses 10s.
• Data type: String duration, such as "10s". The value cannot be negative.

Rules[].Services[].Limits.PassiveHealthCheck.MaxFailures

Specifies the number of consecutive 5xx errors that cause Envoy to eject a host from the load balancing pool.

Values

• Default: none. Envoy uses 5.
• Data type: Integer

Rules[].Services[].Limits.PassiveHealthCheck.Consecutive5xx

Specifies the number of consecutive 5xx errors that cause Envoy to eject a host. When set, this value overrides MaxFailures.

Values

• Default: none
• Data type: Integer greater than 0

Rules[].Services[].Limits.PassiveHealthCheck.ConsecutiveGatewayFailure

Specifies the number of consecutive gateway failures, such as 502, 503, or 504 errors, that cause Envoy to detect an outlier. Envoy ejects the host only when EnforcingConsecutiveGatewayFailure is greater than 0.

Values

• Default: none. Envoy uses 5.
• Data type: Integer greater than 0

Rules[].Services[].Limits.PassiveHealthCheck.EnforcingConsecutive5xx

Specifies the percent chance that Envoy ejects a host when it detects an outlier status through consecutive 5xx errors. Use this setting to turn off ejection or ramp it up gradually.

Values

• Default: none. Envoy uses 100.
• Data type: Integer from 0 to 100

Rules[].Services[].Limits.PassiveHealthCheck.EnforcingConsecutiveGatewayFailure

Specifies the percent chance that Envoy ejects a host when it detects an outlier status through consecutive gateway failures.

Values

• Default: none. Envoy uses 0, which turns off ejection for consecutive gateway failures.
• Data type: Integer from 0 to 100

Rules[].Services[].Limits.PassiveHealthCheck.MaxEjectionPercent

Specifies the maximum percentage of hosts in the upstream cluster that Envoy can eject at the same time. Envoy ejects at least one host regardless of the value.

Values

• Default: none. Envoy uses 10.
• Data type: Integer from 0 to 100

Rules[].Services[].Limits.PassiveHealthCheck.BaseEjectionTime

Specifies the base amount of time that an ejected host stays out of the load balancing pool. The actual ejection time equals the base ejection time multiplied by the number of times Envoy has ejected the host, up to a maximum of 300s.

Values

• Default: none. Envoy uses 30s.
• Data type: String duration, such as "30s". The value cannot be negative.

Examples

The following examples demonstrate common HTTP route configuration patterns for specific use cases.

Configure JWT verification settings

In the following example, the route is configured to accept incoming requests from the okta provider that requires the client to have admin permissions.

kind = "http-route"
name = "api-gateway-route"
parents = [
  {
    sectionName = "listener-one"
    name = "api-gateway"
    kind = "api-gateway"
  }
]
rules = [
  {
    matches = "/"
  },
  {
    matches = "/admin"
    filters = {
      JWT = {
        Providers = [
          {
            Name = "okta"
            VerifyClaims = {
              Path = ["perms", "role"]
              Value = "admin"
            }
          }
        ]
      }
    }
    services = [
      {
        name = "okta-verified-service"
      }
    ]
  }
]

{
  "kind": "http-route",
  "name": "api-gateway-route",
  "parents": [
    {
      "sectionName": "listener-one",
      "name": "api-gateway",
      "kind": "api-gateway"
    }
  ],
  "rules": [
    {
      "matches": "/"
    },
    {
      "matches": "/admin",
      "filters": {
        "JWT": {
          "Providers": [
            {
              "Name": "okta",
              "VerifyClaims": {
                "Path": ["perms", "role"],
                "Value": "admin"
              }
            }
          ]
        }
      },
      "services": [
        {
          "name": "okta-verified-service"
        }
      ]
    }
  ]
}

Route to a service subset

The following example creates stable and canary subsets for the api service. The service-router routes requests with the x-version: canary header to the canary subset. The http-route exposes the api service through api-gateway; Consul API Gateway applies the service-router rule when routing matching requests to the backend service.

Create the service resolver:

Kind          = "service-resolver"
Name          = "api"
DefaultSubset = "stable"
Subsets = {
  stable = {
    Filter = "Service.Meta.version == stable"
  }
  canary = {
    Filter = "Service.Meta.version == canary"
  }
}

Create the service router:

Kind = "service-router"
Name = "api"
Routes = [
  {
    Match {
      HTTP {
        Header = [
          {
            Name  = "x-version"
            Exact = "canary"
          },
        ]
      }
    }

    Destination {
      Service       = "api"
      ServiceSubset = "canary"
    }
  },
]

Create the HTTP route:

Kind = "http-route"
Name = "api-route"

Rules = [
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/api"
        }
      }
    ]
    Services = [
      {
        Name = "api"
      }
    ]
  }
]

Parents = [
  {
    Kind        = "api-gateway"
    Name        = "api-gateway"
    SectionName = "http"
  }
]

Override the passive health check for a routed service

In the following example, the s1 service inherits the passive health check from the api-gateway configuration entry's Defaults.PassiveHealthCheck field. The s2 service uses its own passive health check, which replaces the gateway default for that service.

Kind = "http-route"
Name = "api-gateway-route"

Parents = [
  {
    Kind        = "api-gateway"
    Name        = "api-gateway"
    SectionName = "listener-one"
  }
]

Rules = [
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/s1"
        }
      }
    ]
    Services = [
      {
        Name = "s1"
      }
    ]
  },
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/s2"
        }
      }
    ]
    Services = [
      {
        Name = "s2"
        Limits = {
          PassiveHealthCheck = {
            Interval                = "20s"
            MaxFailures             = 5
            EnforcingConsecutive5xx = 60
            MaxEjectionPercent      = 50
            BaseEjectionTime        = "60s"
          }
        }
      }
    ]
  }
]

{
  "Kind": "http-route",
  "Name": "api-gateway-route",
  "Parents": [
    {
      "Kind": "api-gateway",
      "Name": "api-gateway",
      "SectionName": "listener-one"
    }
  ],
  "Rules": [
    {
      "Matches": [
        {
          "Path": {
            "Match": "prefix",
            "Value": "/s1"
          }
        }
      ],
      "Services": [
        {
          "Name": "s1"
        }
      ]
    },
    {
      "Matches": [
        {
          "Path": {
            "Match": "prefix",
            "Value": "/s2"
          }
        }
      ],
      "Services": [
        {
          "Name": "s2",
          "Limits": {
            "PassiveHealthCheck": {
              "Interval": "20s",
              "MaxFailures": 5,
              "EnforcingConsecutive5xx": 60,
              "MaxEjectionPercent": 50,
              "BaseEjectionTime": "60s"
            }
          }
        }
      ]
    }
  ]
}

Route requests based on the absence of a header

In the following example, requests that do not include the x-canary header route to the s2 service. Requests that include the x-canary header, with any value, route to the s1 service.

Kind = "http-route"
Name = "canary-route"

Parents = [
  {
    Kind        = "api-gateway"
    Name        = "api-gateway"
    SectionName = "listener-one"
  }
]

Rules = [
  {
    Matches = [
      {
        Headers = [
          {
            Name   = "x-canary"
            Match  = "present"
            Invert = true
          }
        ]
      }
    ]
    Services = [
      {
        Name = "s2"
      }
    ]
  },
  {
    Matches = [
      {
        Headers = [
          {
            Name  = "x-canary"
            Match = "present"
          }
        ]
      }
    ]
    Services = [
      {
        Name = "s1"
      }
    ]
  }
]

{
  "Kind": "http-route",
  "Name": "canary-route",
  "Parents": [
    {
      "Kind": "api-gateway",
      "Name": "api-gateway",
      "SectionName": "listener-one"
    }
  ],
  "Rules": [
    {
      "Matches": [
        {
          "Headers": [
            {
              "Name": "x-canary",
              "Match": "present",
              "Invert": true
            }
          ]
        }
      ],
      "Services": [
        {
          "Name": "s2"
        }
      ]
    },
    {
      "Matches": [
        {
          "Headers": [
            {
              "Name": "x-canary",
              "Match": "present"
            }
          ]
        }
      ],
      "Services": [
        {
          "Name": "s1"
        }
      ]
    }
  ]
}