HashiCorp Developer AI Private beta now available Sign up today
Consul
Consul Home

You are viewing documentation for version v1.16.x. View latest version.

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.

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

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 Enterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

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

Partition Enterprise

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

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 Enterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

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

Parents[].Partition Enterprise

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

Rules[].Filters

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

Values

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:

ParameterDescriptionType
setConfigure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations:
  • name: Required string that specifies the name of the HTTP header to set.
  • value: Required string that specifies the value of the HTTP header to set.
List of maps
addConfigure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the values to add. You can specify the following configurations:
  • name: Required string that specifies the name of the HTTP header to append.
  • value: Required string that specifies the value of the HTTP header to add.
List of maps
removeConfigure this field to specify an array of header names to remove from the request header.List of strings

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:

ParameterDescriptionType
replacePrefixMatchSpecifies a value that replaces the path prefix for incoming HTTP requests. The operation only affects the path prefix. The rest of the path is unchanged.String
typeSpecifies the type of replacement to use for the URL path. You can specify the following values:
  • ReplacePrefixMatch: Replaces the matched prefix of the URL path (default).
String

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:

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:

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:

Rules[].Matches[].Path

Specifies the HTTP method to match.

Values

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

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:

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:

Rules[].Services[].Name

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

Values

  • Default: none
  • Data type: string

Rules[].Services[].Namespace Enterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

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

Rules[].Services.Partition Enterprise

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

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

Defines operations to perform on matching request headers.

Values

This field contains the following configuration objects:

ParameterDescriptionType
setConfigure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations:
  • name: Required string that specifies the name of the HTTP header to set.
  • value: Required string that specifies the value of the HTTP header to set.
List of maps
addConfigure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the values to add. You can specify the following configurations:
  • name: Required string that specifies the name of the HTTP header to append.
  • value: Required string that specifies the value of the HTTP header to add.
List of maps
removeConfigure this field to specify an array of header names to remove from the request header.List of strings

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.