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

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.

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>"
            }
          }
        ]
      }
    }
    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>"
          }
        ]
        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>
        }
        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>"
          }
        }
      }
    ]
  }
]

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.

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[].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

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[].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

Rules[].Services[].Limits.MaxConnections

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

Values

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

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

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"
      }
    ]
  }
]

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"
  }
]
Edit this page on GitHub