github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/connect/config-entries/http-route.mdx

1129 lines
44 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
layout: docs
page_title: HTTP Route Configuration
description: Learn how to configure an HTTP Route bound to an API Gateway on VMs.
---
# HTTP route configuration reference
This topic provides reference information for the gateway routes configuration entry. Refer to [Route Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/routes) 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`](#kind): string | must be `http-route`
- [`Name`](#name): string | no default
- [`Namespace`](#namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#partition): string | no default <EnterpriseAlert inline />
- [`Meta`](#meta): map | no default
- [`Hostnames`](#hostnames): list | no default
- [`Parents`](#parents): list | no default
- [`Kind`](#parents-kind): string | must be `api-gateway`
- [`Name`](#parents-name): string | no default
- [`Namespace`](#parents-namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#parents-partition): string | no default <EnterpriseAlert inline />
- [`SectionName`](#parents-sectionname): string | no default
- [`Rules`](#rules): list | no default
- [`Filters`](#rules-filters): map | no default
- [`Headers`](#rules-filters-headers): list | no default
- [`Add`](#rules-filters-headers-add): map | no default
- [`Remove`](#rules-filters-headers-remove): list | no default
- [`Set`](#rules-filters-headers-set): map | no default
- [`URLRewrite`](#rules-filters-urlrewrite): map | no default
- [`Path`](#rules-filters-urlrewrite-path): string | no default
- [`RetryFilter`](#rules-filters-retryfilter): map
- [`NumRetries`](#rules-filters-retryfilter-numretries): number | `1`
- [`RetryOnConnectionFailure`](#rules-filters-retryfilter-retryonconnectionfailure): boolean | `false`
- [`RetryOn`](#rules-filters-retryfilter-retryon): list of strings
- [`RetryOnStatusCodes`](#rules-filters-retryfilter-retryon): list of numbers
- [`TimeoutFilter`](#rules-filters-timeoutfilter): map
- [`IdleTimeout`](#rules-filters-timeoutfilter): number | `0`
- [`RequestTimeout`](#rules-filters-timeoutfilter): number | `0`
- [`JWT`](#rules-filters-jwt): map
- [`Providers`](#rules-filters-jwt-providers): list
- [`Name`](#rules-filters-jwt-providers): string
- [`VerifyClaims`](#rules-filters-jwt-providers): map
- [`Path`](#rules-filters-jwt-providers): list
- [`Value`](#rules-filters-jwt-providers): string
- [`ResponseFilters`](#rules-responsefilters)
- [`Headers`](#rules-responsefilters-headers): list | no default
- [`Add`](#rules-responsefilters-headers-add): map | no default
- [`Remove`](#rules-responsefilters-headers-remove): list | no default
- [`Set`](#rules-responsefilters-headers-set): map | no default
- [`Matches`](#rules-matches): list | no default
- [`Headers`](#rules-matches-headers): list | no default
- [`Match`](#rules-matches-headers-match): string | no default
- [`Name`](#rules-matches-headers-name): string | no default
- [`Value`](#rules-matches-headers-value): string | no default
- [`Method`](#rules-matches-method): string | no default
- [`Path`](#rules-matches-path): map | no default
- [`Match`](#rules-matches-path-match): string | no default
- [`Value`](#rules-matches-path-value): string | no default
- [`Query`](#rules-matches-query): list | no default
- [`Match`](#rules-matches-query-match): string | no default
- [`Name`](#rules-matches-query-name): string | no default
- [`Value`](#rules-matches-query-value): string | no default
- [`Services`](#rules-services): list | no default
- [`Name`](#rules-services-name): string | no default
- [`Namespace`](#rules-services-namespace): string <EnterpriseAlert inline />
- [`Partition`](#rules-services-partition): string <EnterpriseAlert inline />
- [`Weight`](#rules-services-weight): number | `1`
- [`Filters`](#rules-services-filters): map | no default
- [`Headers`](#rules-services-filters-headers): list | no default
- [`Add`](#rules-services-filters-headers-add): map | no default
- [`Remove`](#rules-services-filters-headers-remove): list | no default
- [`Set`](#rules-services-filters-headers-set): map | no default
- [`URLRewrite`](#rules-services-filters-urlrewrite): map | no default
- [`Path`](#rules-services-filters-urlrewrite-path): string | no default
- [`RetryFilter`](#rules-services-filters-retryfilter): map
- [`NumRetries`](#rules-services-filters-retryfilter-numretries): number | `1`
- [`RetryOnConnectionFailure`](#rules-services-filters-retryfilter-retryonconnectionfailure): boolean | `false`
- [`RetryOn`](#rules-services-filters-retryfilter-retryon): list of strings
- [`RetryOnStatusCodes`](#rules-services-filters-retryfilter-retryon): list of numbers
- [`TimeoutFilter`](#rules-services-filters-timeoutfilter): map
- [`IdleTimeout`](#rules-services-filters-timeoutfilter): number | `0`
- [`RequestTimeout`](#rules-services-filters-timeoutfilter): number | `0`
- [`ResponseFilters`](#rules-services-responsefilters)
- [`Headers`](#rules-services-responsefilters-headers): list | no default
- [`Add`](#rules-services-responsefilters-headers-add): map | no default
- [`Remove`](#rules-services-responsefilters-headers-remove): list | no default
- [`Set`](#rules-services-responsefilters-headers-set): map | no default
## Complete configuration
When every field is defined, an `http-route` configuration entry has the following form:
<CodeTabs>
```hcl
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>"
}
}
}
]
}
]
```
```json
{
"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>"
}
]
}
]
}
]
}
]
}]
}
```
</CodeTabs>
## 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` <EnterpriseAlert inline />
Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Partition` <EnterpriseAlert inline />
Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) 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` <EnterpriseAlert inline />
- `Partition` <EnterpriseAlert inline />
- `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` <EnterpriseAlert inline />
Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Parents[].Partition` <EnterpriseAlert inline />
Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) 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:
| Parameter | Description | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `set` | Configure 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of maps |
| `add` | Configure 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of maps |
| `remove` | Configure 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](/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests) for additional information.
#### Values
The following table describes the parameters for `path`:
| Parameter | Description | Type |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| `replacePrefixMatch` | Specifies 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 |
| `type` | Specifies the type of replacement to use for the URL path. You can specify the following values: <ul><li>`ReplacePrefixMatch`: Replaces the matched prefix of the URL path (default). </li></ul> | String |
### `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:
| Conditions | Description |
| :------------------- | :------------------------------------------------------------------------------------------------------- |
| `5xx` | Consul retries the request when an upstream responds with any 5xx error code or does not respond at all. |
| `gateway-error` | Consul retries the request when the upstream responds with a 502, 503, or 504 error. |
| `reset` | Consul retries the request when the upstream does not respond at all. |
| `connect-failure` | Consul retries the request when the connection to the upstream fails. |
| `envoy-ratelimited` | Consul retries the request when the header `x-envoy-ratelimited` is present. |
| `retriable-4xx` | Consul retries the request when the upstream responds with a retriable 4xx code. |
| `refused-stream` | Consul retries the request when the upstream resets the stream with a `REFUSED_STREAM` error code. |
| `cancelled` | Consul retries the request when the gRPC status code in the response headers is `cancelled`. |
| `deadline-exceeded` | Consul retries the request when the gRPC status code in the response headers is `deadline-exceeded`. |
| `internal` | Consul retries the request when the gRPC status code in the response headers is `internal`. |
| <nobr>`resource-exhausted`</nobr> | Consul retries the request when the gRPC status code in the response headers is `resource-exhausted`. |
| `unavailable` | Consul retries the request when the gRPC status code in the response headers is `unavailable`. |
#### 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) 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:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `IdleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` |
| `RequestTimeout` | Specifies the total amount of time in nanoseconds, including retry attempts, Consul permits for the entire downstream request to be processed. | Integer | `0` |
### `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`](/consul/docs/connect/config-entries/api-gateway#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:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `Name` | Specifies the name of the provider. | String | None |
| `VerifyClaims` | Specifies a list of paths and a value that define the claim. Consul verifies requests that match the claims declared in the listener JWT configuration and allow the request through the gateway. The `VerifyClaims` map specifies the following settings: <ul><li>`Path`: Specifies a list of one or more registered or custom claims.</li><li>`Value`: Specifies the expected value of the claim.</li></ul> | Map | None |
Refer to [Configure JWT verification settings](#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:
| Parameter | Description | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `set` | Configure this field to rewrite the HTTP response 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of maps |
| `add` | Configure this field to append the response 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of maps |
| `remove` | Configure this field to specify an array of header names to remove from the response header. | List of strings |
### `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`](#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`](#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`](#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](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.PathMatchType), 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` <EnterpriseAlert inline />
- `Partition` <EnterpriseAlert inline />
### `Rules[].Services[].Name`
Specifies the name of an HTTP-based service to route to.
#### Values
- Default: none
- Data type: string
### `Rules[].Services[].Namespace` <EnterpriseAlert inline />
Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Rules[].Services.Partition` <EnterpriseAlert inline />
Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) 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:
| Parameter | Description | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `set` | Configure 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of maps |
| `add` | Configure 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of maps |
| `remove` | Configure 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.
### `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:
| Conditions | Description |
| :------------------- | :------------------------------------------------------------------------------------------------------- |
| `5xx` | Consul retries the request when an upstream responds with any 5xx error code or does not respond at all. |
| `gateway-error` | Consul retries the request when the upstream responds with a 502, 503, or 504 error. |
| `reset` | Consul retries the request when the upstream does not respond at all. |
| `connect-failure` | Consul retries the request when the connection to the upstream fails. |
| `envoy-ratelimited` | Consul retries the request when the header `x-envoy-ratelimited` is present. |
| `retriable-4xx` | Consul retries the request when the upstream responds with a retriable 4xx code. |
| `refused-stream` | Consul retries the request when the upstream resets the stream with a `REFUSED_STREAM` error code. |
| `cancelled` | Consul retries the request when the gRPC status code in the response headers is `cancelled`. |
| `deadline-exceeded` | Consul retries the request when the gRPC status code in the response headers is `deadline-exceeded`. |
| `internal` | Consul retries the request when the gRPC status code in the response headers is `internal`. |
| <nobr>`resource-exhausted`</nobr> | Consul retries the request when the gRPC status code in the response headers is `resource-exhausted`. |
| `unavailable` | Consul retries the request when the gRPC status code in the response headers is `unavailable`. |
#### 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) 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:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `IdleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` |
| `RequestTimeout` | Specifies the total amount of time in nanoseconds, including retry attempts, Consul permits for the entire downstream request to be processed. | Integer | `0` |
### `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:
| Parameter | Description | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `set` | Configure this field to rewrite the HTTP response 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of maps |
| `add` | Configure this field to append the response 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: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of maps |
| `remove` | Configure this field to specify an array of header names to remove from the response header. | List of strings |
## 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.
<Tabs>
<Tab heading="HCL" group="hcl">
```hcl
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"
}
]
}
]
```
</Tab>
<Tab heading="JSON" group="json">
```json
{
"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"
}
]
}]
}
```
</Tab>
</Tabs>
Reference in New Issue View Git Blame Copy Permalink