HTTP route configuration 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 EnterpriseEnterprise
• Partition: string | no default EnterpriseEnterprise
• 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 EnterpriseEnterprise
  • Partition: string | no default EnterpriseEnterprise
  • SectionName: string | no default
• Rules: list | no default
  • Filters: map | no default
    • Headers: list | no default
      • Add: map | no default
      • Remove: list | no default
      • Set: map | no default
    • URLRewrite: map | no default
      • Path: string | no default
    • RetryFilter: map
      • NumRetries: number | 1
      • RetryOnConnectionFailure: boolean | false
      • RetryOn: list of strings
      • RetryOnStatusCodes: list of numbers
    • TimeoutFilter: map
      • IdleTimeout: number | 0
      • RequestTimeout: number | 0
    • JWT: map
      • Providers: list
        • Name: string
        • VerifyClaims: map
          • Path: list
          • Value: string
  • ResponseFilters
    • Headers: list | no default
      • Add: map | no default
      • Remove: list | no default
      • Set: map | no default
  • Matches: list | no default
    • Headers: list | no default
      • Match: string | no default
      • Name: string | no default
      • Value: string | no default
    • Method: string | no default
    • Path: map | no default
      • Match: string | no default
      • Value: string | no default
    • Query: list | no default
      • Match: string | no default
      • Name: string | no default
      • Value: string | no default
  • Services: list | no default
    • Name: string | no default
    • Namespace: string EnterpriseEnterprise
    • Partition: string EnterpriseEnterprise
    • Weight: number | 1
    • Filters: map | no default
      • Headers: list | no default
        • Add: map | no default
        • Remove: list | no default
        • Set: map | no default
      • URLRewrite: map | no default
        • Path: string | no default
      • RetryFilter: map
        • NumRetries: number | 1
        • RetryOnConnectionFailure: boolean | false
        • RetryOn: list of strings
        • RetryOnStatusCodes: list of numbers
      • TimeoutFilter: map
        • IdleTimeout: number | 0
        • RequestTimeout: number | 0
      • JWT: map
        • Providers: list
          • Name: string
          • VerifyClaims: map
            • Path: list
            • Value: string
    • ResponseFilters
      • Headers: list | no default
        • Add: map | no default
        • Remove: list | no default
        • Set: map | no default

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>"
      }
      JWT = {
        Providers = [
          Name = "<name of the provider>"
          VerifyClaim = {
            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 = "<number proportional to other weights>"
        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>"
          }
        }
      }
    ]
  }
]

{
  "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>"
            }
          ],
        "JWT": {
          "Providers": [{
            "Name": "okta",
            "VerifyClaims": {
              "Path": ["perms", "role"],
              "Value": "user"
            }
          }]
        }
      }
    ],
    "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 route>",
        "Partition": "<enterprise: partition of the route>",
        "Weight": "<number proportional to other weights>",
        "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>"
              }
            ]
          }
        ],
        "ResponseFilters": [
          {
            "Headers": [
              {
                "Add": [
                  {
                    "<name of header to add": "<value of header to add>"
                  }
                ],
                "Remove": ["<header to remove from response>"],
                "Set": [
                  {
                    "<name of header to set": "<value of header to set>"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }]
}

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. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster.

Values

• Default: Defaults to the name of the node after writing the entry to the Consul server.
• This field is required.
• Data type: string

Namespace EnterpriseEnterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Partition EnterpriseEnterprise

Specifies the Enterprise admin partition to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Meta

Specifies an arbitrary set of key-value pairs to associate with the route.

Values

• Default: none
• Data type: map containing one or more keys and string values.

Parents[]

Specifies the list of gateways that this route binds to.

Values

• Default: none
• Data type: List of map. Each member of the list contains the following fields:
  • Kind
  • Name
  • Namespace EnterpriseEnterprise
  • Partition EnterpriseEnterprise
  • SectionName

Parents[].Kind

Specifies the type of resource to bind to. This field is required and must be set to "api-gateway"

Values

• Default: none
• This field is required.
• Data type: string value set to "api-gateway"

Parents[].Name

Specifies the name of the api-gateway to bind to.

Values

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

Parents[].Namespace EnterpriseEnterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Parents[].Partition EnterpriseEnterprise

Specifies the Enterprise admin partition to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Parents[].SectionName

Specifies the name of the listener to bind to on the api-gateway. If left empty, this route binds to all listeners on the parent gateway.

Values

• Default: ""
• Data type: string

Rules[]

Specifies the list of HTTP-based routing rules that this route uses to construct a route table.

Values

• Default:
• Data type: List of maps. Each member of the list contains the following fields:
  • Filters
  • Matches
  • Services

Rules[].Filters[]

Specifies the list of HTTP-based filters used to modify a request prior to routing it to the upstream service.

Values

• Default: none
• Data type: Map that contains the following fields:
  • Headers
  • UrlRewrite
  • RetryFilter
  • TimeoutFilter

Rules[].Filters[].Headers[]

Defines operations to perform on matching request headers when an incoming request matches the Rules.Matches configuration.

Values

This field contains the following configuration objects:

Rules[].Filters[].URLRewrite

Specifies rule for rewriting the URL of incoming requests when an incoming request matches the Rules.Matches configuration.

Values

• Default: none
• This field is a map that contains a Path field.

Rules[].Filters[].URLRewrite.Path

Specifies a path that determines how Consul API Gateway rewrites a URL path. Refer to Reroute HTTP requests for additional information.

Values

The following table describes the parameters for path:

Rules[].Filters[].RetryFilter

Specifies a block of settings Consul uses to retry a request if it fails.

Values

• Default: None
• Data type: Map containing the following parameters:
  • NumRetries
  • RetryOnConnectFailure
  • RetryOn
  • RetryOnStatusCodes

Rules[].Filters[].RetryFilter{}.NumRetries

Specifies the number of times to retry the request when a retry condition occurs.

Values

• Default: 1
• Data type: Integer

Rules[].Filters[].RetryFilter{}.RetryOnConnectFailure

Enables Consul to retry the request if the connection fails. Define the one or more retry configurations to define the retry logic for the route.

Values

• Default: false
• Data type: Boolean

Rules[].Filters[].RetryFilter{}.RetryOn

Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. The following retry conditions are supported:

Values

• Default: None

• Data type: List of strings. Strings must match one of the following values:

  • 5xx
  • gateway-error
  • reset
  • connect-failure
  • envoy-ratelimited
  • retriable-4xx
  • refused-stream
  • cancelled
  • deadline-exceeded
  • internal
  • resource-exhausted
  • unavailable

Rules[].Filters[].RetryFilter{}.RetryOnStatusCodes

Specifies a list of integers for HTTP response status codes that trigger a retry request.

Values

• Default: None
• Data type: List of integers

Rules[].Filters[].TimeoutFilter

Specifies timeout settings for routes from an API gateway listener to the destination service in Consul service mesh.

Values

• Default: None
• Data type: Map

The following table describes the settings you can configure in the TimeoutFilter map:

Rules[].Filters{}.JWT

Specifies a block of JWT verification configurations to apply to the route. These route-specific settings have precedence over default configurations defined for listeners the route attaches to on the API gateway. Refer to Listeners[].default{}.JWT for additional information.

Values

• Default: None
• Data type: Map

Rules[].Filters[].JWT{}.Providers

Specifies a list of JWT provider configurations to apply to the route. A provider configuration contains the name of the provider and claims.

Values

• Default: None
• Data type: List of maps

The following table describes the parameters you can specify in a member of the Providers list:

Refer to Configure JWT verification settings for an example configuration.

Rules[].ResponseFilters[]

Specifies the list of HTTP-based filters used to modify a response prior to routing it to the calling client.

Values

• Default: none
• Data type: Map that contains the following fields:
  • Headers

Rules[].ResponseFilters[].Headers[]

Defines operations to perform on matching response headers when an incoming request matches the Rules.Matches configuration.

Values

This field contains the following configuration objects:

Rules[].Matches[]

Specifies the matching criteria used in the routing table. When an incoming request matches the given HTTPMatch configuration, traffic routes to services specified in the Rules.Services field.

Values

• Default: none
• Data type: List containing maps. Each member of the list contains the following fields:
  • Headers
  • Method
  • Path
  • Query

Rules[].Matches[].Headers[]

Specifies rules for matching incoming request headers. You can specify multiple rules in a list, as well as multiple lists of rules. If all rules in a single list are satisfied, then the route forwards the request to the appropriate service defined in the Rules.Services configuration. You can create multiple Header[] lists to create a range of matching criteria. When at least one list of matching rules are satisfied, the route forwards the request to the appropriate service defined in the Rules.Services configuration.

Values

• Default: none
• Data type: List containing maps with the following fields:
  • Match
  • Name
  • Value

Rules.Matches.Headers.Match

Specifies type of match for headers: "exact", "prefix", or "regex".

Values

• Default: none
• Data type: string

Rules.Matches.Headers.Name

Specifies the name of the header to match.

Values

• Default: none
• Data type: string

Rules[].Matches.Headers.Value

Specifies the value of the header to match.

Values

• Default: none
• Data type: string

Rules[].Matches[].Method

Specifies a list of strings that define matches based on HTTP request method.

Values

Specify one of the following string values:

• HEAD
• POST
• PUT
• PATCH
• GET
• DELETE
• OPTIONS
• TRACE
• CONNECT

Rules[].Matches[].Path

Specifies the HTTP method to match.

Values

• Default: none
• Data type: map containing the following fields:
  • Match
  • Value

Rules[].Matches[].Path.Match

Specifies type of match for the path: "exact", "prefix", or "regex".

If set to prefix, Consul uses simple string matching to identify incoming request prefixes. For example, if the route is configured to match incoming requests to services prefixed with /dev, then the gateway would match requests to /dev- and /deviate and route to the upstream.

This deviates from the Kubernetes Gateway API specification, which matches on full path elements. In the previous example, only requests to /dev or /dev/ would match.

Values

• Default: none
• Data type: string

Rules[].Matches[].Path.Value

Specifies the value of the path to match.

Values

• Default: none
• Data type: string

Rules[].Matches[].Query[]

Specifies how a match is completed on a request’s query parameters.

Values

• Default: none
• Data type: List of map that contains the following fields:
  • Match
  • Name
  • Value

Rules[].Matches[].Query[].Match

Specifies type of match for query parameters: "exact", "prefix", or "regex".

Values

• Default: none
• Data type: string

Rules[].Matches[].Query[].Name

Specifies the name of the query parameter to match.

Values

• Default: none
• Data type: string

Rules[].Matches[].Query[].Value

Specifies the value of the query parameter to match.

Values

• Default: none
• Data type: string

Rules[].Services[]

Specifies the service that the API gateway routes incoming requests to when the requests match the Rules.Matches configuration.

Values

• Default: none
• This field contains a list of maps. Each member of the list contains the following fields:
  • Name
  • Weight
  • Filters
  • Namespace EnterpriseEnterprise
  • Partition EnterpriseEnterprise

Rules[].Services[].Name

Specifies the name of an HTTP-based service to route to.

Values

• Default: none
• Data type: string

Rules[].Services[].Namespace EnterpriseEnterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Rules[].Services.Partition EnterpriseEnterprise

Specifies the Enterprise admin partition to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Rules[].Services[].Weight

Specifies the proportion of requests forwarded to the specified service. If no weight is specified, or if the specified weight is set to less than or equal to 0, the weight is normalized to 1. The proportion is determined by dividing the value of the weight by the sum of all weights in the service list. For non-zero values, there may be some deviation from the exact proportion depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100.

Values

• Default: none
• Data type: integer

Rules[].Services[].Filters[]

Specifies the list of HTTP-based filters used to modify a request prior to routing it to this upstream service.

Values

• Default: none
• Data type: Map that contains the following fields:
  • Headers
  • UrlRewrite

Rules[].Services[].Filters[].Headers[]

Defines operations to perform on matching request headers.

Values

This field contains the following configuration objects:

Rules[].Services[].Filters[].URLRewrite

Specifies rule for rewriting the URL of incoming requests.

Values

• Default: none
• This field is a map that contains a Path field.

Rules[].Services[].Filters[].RetryFilters

Specifies a block of settings Consul uses to retry a request if it fails.

Values

• Default: None
• Data type: Map containing the following parameters:
  • NumRetries
  • RetryOnConnectFailure
  • RetryOn
  • RetryOnStatusCodes

Rules[].Services[].Filters[].RetryFilters{}.NumRetries

Specifies the number of times to retry the request when a retry condition occurs.

Values

• Default: 1
• Data type: Integer

Rules[].Services[].Filters[].RetryFilters{}.RetryOnConnectFailure

Enables Consul to retry the request if the connection fails. Define the one or more retry configurations to define the retry logic for the route.

Values

• Default: false
• Data type: Boolean

Rules[].Services[].Filters[].RetryFilters{}.RetryOn

Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. The following retry conditions are supported:

Values

• Default: None

• Data type: List of strings. Strings must match one of the following values:

  • 5xx
  • gateway-error
  • reset
  • connect-failure
  • envoy-ratelimited
  • retriable-4xx
  • refused-stream
  • cancelled
  • deadline-exceeded
  • internal
  • resource-exhausted
  • unavailable

Rules[].Services[].Filters[].RetryFilters{}.RetryOnStatusCodes

Specifies a list of integers for HTTP response status codes that trigger a retry request.

Values

• Default: None
• Data type: List of integers

Rules[].Services[].Filters[].TimeoutFilter

Specifies timeout settings for routes from an API gateway listener to the destination service in Consul service mesh.

Values

• Default: None
• Data type: Map

The following table describes the settings you can configure in the TimeoutFilter map:

Rules[].Services[].ResponseFilters[]

Specifies the list of HTTP-based filters used to modify a response prior to routing it to the calling client.

Values

• Default: none
• Data type: Map that contains the following fields:
  • Headers

Rules[].Services[].ResponseFilters[].Headers[]

Defines operations to perform on matching response headers when an incoming request matches the Rules.Matches configuration.

Values

This field contains the following configuration objects:

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", # this is referencing an existing JWT provider config entry
            VerifyClaims = {
              Path = ["perms", "role"],
              Value = "admin",
            }
          }
        ]
      }
    }
    services = [
      {
        name = "bender"
      }
    ]
  }
]

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