From ab3751161c7fd3a66e1e1cf5ba5d51c7aa9d3e9f Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 25 Apr 2023 09:49:05 -0700 Subject: [PATCH 01/25] service-resolve configuration entry reference --- .../config-entries/service-resolver.mdx | 1310 +++++++++++------ 1 file changed, 857 insertions(+), 453 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 1136c15cfef9..2a303d132dcb 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -1,34 +1,863 @@ --- layout: docs -page_title: Service Resolver - Configuration Entry Reference -description: >- - The service resolver configuration entry kind defines subsets of service instances that satisfy upstream discovery requests. Use the reference guide to learn about `""service-resolver""` config entry parameters and how filtering by service subsets helps route traffic based on properties like version number. +page_title: Service Resolver Configuration Entry Reference +description: >- + Service resolver configuration entries are L7 traffic management tools for defining sets of service instances that resolve upstream requests and Consul’s behavior when resolving them. Learn how to write `service-resolver` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case. --- -# Service Resolver Configuration Entry +# Service Resolver Configuration Reference + +This page provides reference information for service resolver configuration entries. Configure and apply service resolvers to create named subsets of service instances and their behavior when satisfying upstream requests. + +Refer to [L7 traffic management overview](/consul/docs/connect/l7-traffic) for additional information. + +## Configuration model + +The following list outlines field hierarchy, language-specific data types, and requirements in the configuration entry. Click on a property name to view additional details, including default values. + + + + + +- [`Kind`](#kind): string | `service-resolver` | required +- [`Name`](#name): string | required +- [`Namespace`](#namespace): string | `default` +- [`Partition`](#partition): string | `default` +- [`Meta`](#meta): map +- [`ConnectTimeout`](#connecttimeout): string | `0s` +- [`RequestTimeout`](#requesttimeout): string | `0s` +- [`Subsets`](#subsets): map + - [`Filter`](#subsets): string + - [`OnlyPassing`](#subsets): boolean | `false` +- [`DefaultSubset`](#defaultsubset): string +- [`Redirect`](#redirect): map + - [`Service`](#redirect-service): string + - [`ServiceSubset`](#redirect-servicesubset): string + - [`Namespace`](#redirect-namespace): string + - [`Partition`](#redirect-partition): string | `default` + - [`Datacenter`](#redirect-datacenter): list + - [`Peer`](#redirect-peer): string +- [`Failover`](#failover): map + - [`Service`](#failover-service): string + - [`ServiceSubset`](#failover-servicesubset): string + - [`Namespace`](#failover-namespace): string + - [`Datacenters`](#failover-datacenters): list + - [`Targets`](#failover-targets): list + - [`Service`](#failover-targets-service): string + - [`ServiceSubset`](#failover-targets-servicesubset): string + - [`Namespace`](#failover-targets-namespace): string + - [`Partition`](#failover-targets-partition): string | `default` + - [`Datacenter`](#failover-targets-datacenter): string + - [`Peer`](#failover-targets-peer): string +- [`LoadBalancer`](#loadbalancer): map + - [`Policy`](#loadbalancer-policy): string + - [`RingHashConfig`](#loadbalancer-ringhashconfig): map + - [`MinimumRingSize`](#loadbalancer-ringhashconfig-minimum): integer | `1024` + - [`MaximumRingSize`](#loadbalancer-ringhashconfig-maximum): integer | `8192` + - [`LeastRequestConfig`](#loadbalancer-leastrequestconfig): map + - [`ChoiceCount`](#loadbalancer-leastrequestconfig-choicecount): integer `2` + - [`HashPolicies`](#loadbalancer-hashpolicies): map + - [`Field`](#loadbalancer-hashpolicies-field): string + - [`FieldValue`](#loadbalancer-hashpolicies-fieldvalue): string + - [`CookieConfig`](#loadbalancer-hashpolicies-cookieconfig): map + - [`Session`](#loadbalancer-hashpolicies-cookieconfig-session): boolean | `false` + - [`TTL`](#loadbalancer-hashpolicies-cookieconfig-ttl): string + - [`Path`](#loadbalancer-hashpolicies-cookieconfig-path): string + - [`SourceIP`](#loadbalancer-hashpolicies-sourceip): boolean | `false` + - [`Terminal`](#loadbalancer-hashpolicies-terminal): boolean | `false` + + + + + +- [`apiVersion`](#apiversion): string | required | `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | required | `serviceResolver` +- [`metadata`](#metadata): map | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): map | required + - [`connectTimeout`](#spec-connecttimeout): string | `0s` + - [`requestTimeout`](#spec-requesttimeout): string | `0s` + - [`subsets`](#spec-subsets): map + - [`filter`](#spec-subsets-filter): string + - [`onlyPassing`](#spec-subsets-onlypassing): boolean | `false` + - [`defaultSubset`](#spec-defaultsubset): string + - [`redirect`](#spec-redirect): map + - [`service`](#spec-redirect-service): string + - [`serviceSubset`](#spec-redirect-servicesubset): string + - [`namespace`](#spec-redirect-namespace): string + - [`partition`](#spec-redirect-partition): string + - [`datacenter`](#spec-redirect-datacenter): string + - [`peer`](#spec-redirect-peer): string + - [`failover`](#spec-failover): map + - [`service`](#spec-failover-service): string + - [`serviceSubset`](#spec-failover-servicesubset): string + - [`namespace`](#spec-failover-namespace): string + - [`datacenters`](#spec-failover-datacenters): string + - [`targets`](#spec-failover-targets): list + - [`service`](#spec-failover-targets-service): string + - [`serviceSubset`](#spec-failover-targets-servicesubset): string + - [`namespace`](#spec-failover-targets-namespace): string | `default` + - [`partition`](#spec-failover-targets-partition): string | `default` + - [`datacenter`](#spec-failover-targets-datacenter): string + - [`peer`](#spec-failover-targets-peer): string + - [`loadBalancer`](#spec-loadbalancer): map + - [`policy`](#spec-loadbalancer-policy): string + - [`leastRequestConfig`](#spec-loadbalancer-leastrequestconfig): map + - [`choiceCount`](#spec-loadbalancer-leastrequestconfig-choicecount): integer | `2` + - [`ringHashConfig`](#spec-loadbalancer-ringhashconfig): map + - [`minimumRingSize`](#spec-loadbalancer-ringhashconfig-minimum): integer | `1024` + - [`maximumRingSize`](#spec-loadbalancer-ringhashconfig-maximum): integer | `8192` + - [`hashPolicies`](#spec-loadbalancer-hashpolicies): list + - [`field`](#spec-loadbalancer-hashpolicies-field): string + - [`fieldValue](#spec-loadbalancer-hashpolicies-fieldvalue): string + - [`cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig): map + - [`session`](spec-#loadbalancer-hashpolicies-cookieconfig-session): boolean | `false` + - [`ttl`](#spec-loadbalancer-hashpolicies-cookieconfig-ttl): string | `0s` + - [`path`](#spec-loadbalancer-hashpolicies-cookieconfig-path): string + - [`sourceIP`](#spec-loadbalancer-hashpolicies-sourceip): boolean | `false` + - [`terminal`](#spec-loadbalancer-hashpolicies-terminal): boolean | `false` + + + + +## Complete configuration + +When every field is defined, a service resolver configuration entry has the following form: + + + + --> **v1.8.4+:** On Kubernetes, the `ServiceResolver` custom resource is supported in Consul versions 1.8.4+.
-**v1.6.0+:** On other platforms, this config entry is supported in Consul versions 1.6.0+. +```hcl +Kind = "service-resolver" ## required +Name = "" +Namespace = "" +Partition = "parition-configuration-applies-to>" +Meta = { + = "" +} + +ConnectTimeout = "10s" +RequestTimeout = "5s" +Subsets = { + = { + Filter = "" + OnlyPassing = true + } + = { + Filter = "" + OnlyPassing = true + } +} +DefaultSubset = "" + +Redirect = { + Service = "" + ServiceSubset = "" + Namespace = "" + Partition = "" + Datacenter = "" + Peer = "" +} + +Failover = { ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters + = { + Targets = [ + { Service = "" }, + { ServiceSubset = "" }, + { Namespace = "" }, + { Partition = "" }, + { Datacenter = "" }, + { Peer = "" } + ] + } + "*" = { + Service = "" + ServiceSubset = "" + Namespace = "" + Datacenters = ["", ""] + } +} + +LoadBalancer = { + Policy = "random" + RingHashConfig = { ## requires Policy = "ring_hash" + MinimumRingSize = 1024 + MaximumRingSize = 8192 + } + LeastRequestConfig = { ## requires Policy = "least_request" + ChoiceCount = 2 + } + HashPolicies = [ + { + Field = "header" ## cannot specify with SourceIP + FieldValue = "" ## cannot specify with SourceIP + CookieConfig = { + Session = false + TTL = "0s" + Path = "" + } + SourceIP = false ## cannot specify with Field or FieldValue + Terminal = false + } + ] +} + +``` + + + + + +```json +{ + "Kind":"service-resolver", // required + "Name":"", + "Namespace":"", + "Partition":"parition-configuration-applies-to>", + "Meta":{ + "":"" + }, + + "ConnectTimeout":"10s", + "RequestTimeout":"5s", + "Subsets":{ + "":{ + "Filter":"", + "OnlyPassing":true + }, + "":{ + "Filter":"", + "OnlyPassing":true + } + }, + "DefaultSubset ":"", + + "Redirect":{ + "Service":"", + "ServiceSubset":"", + "Namespace":"", + "Partition":"", + "Datacenter":"", + "Peer":"" + }, + + "Failover":{ // requires at least one of the following": Service, ServiceSubset, Namespace, Targets, Datacenters + "":{ + "Targets":[ + {"Service":""}, + {"ServiceSubset":""}, + {"Namespace":""}, + {"Partition":""}, + {"Datacenter":""}, + {"Peer":""} + ] + }, + "*":{ + "Service ":"", + "ServiceSubset":"", + "Namespace":"", + "Datacenters":["", ""] + } + }, + + "LoadBalancer":{ + "Policy":"random", + "RingHashConfig":{ // requires Policy":"ring_hash" + "MinimumRingSize":1024, + "MaximumRingSize":8192 + }, + "LeastRequestConfig":{ // requires Policy":"least_request" + "ChoiceCount":2 + }, + "HashPolicies":[ + { + "Field":"header", // cannot specify with SourceIP + "FieldValue":"", // cannot specify with SourceIP + "CookieConfig":{ + "Session":false, + "TTL":"0s", + "Path":"" + }, + "SourceIP":false, // cannot specify with Field or FieldValue + "Terminal":false + } + ] + } +} +``` + + + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 # required +kind: ServiceResolver # required +metadata: + name: + namespace: +spec: + connectTimeout: 10s + requestTimeout: 5s + subsets: + : + filter: + onlyPassing: false + : + filter: + onlyPassing: false + defaultSubset: + redirect: + service: + servicesubset: + namespace: + partition: + peer: + failover: # requires at least one of the following: service, serviceSubset, namespace, targets, datacenters + : + targets: + - service: + - serviceSubset: + - namespace: + - partition: + - datacenter: + - peer: + `*`: + service: + serviceSubset: + namespace: + datacenters: ["", ""] + loadBalancer: + policy: random + leastRequestConfig: # requires policy: leastRequestConfig + choiceCount: 2 + ringHashConfig: # requires policy: ringHashConfig + minimumRingSize: 1024 + maximumRingSize: 8192 + hashPolicies: + - field: header # cannot specify with SourceIP + - fieldValue: # cannot specify with SourceIP + - cookieConfig: + session: false + ttl: 0s + path: + - sourceIP: false # cannot specify with field or fieldValue + - terminal: false +``` + + + + + +## Specification + +This section provides details about the fields you can configure in the configuration entry. + + + + + +### `Kind` + +Specifies the type of configuration entry to implement. Must be set to `service-resolver`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `service-resolver`. + +### `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: None +- This field is required. +- Data type: String + +### `Namespace` + +Specifies the namespace that the service resolver applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information. + +#### Values + +- Default: None +- Data type: String + +### `Partition` + +Specifies the admin partition that the service resolver applies to. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. + +#### Values + +- Default: `default` +- Data type: String + +### `Meta` + +Specifies key-value pairs to add to the KV store. + +#### Values + +- Default: none +- Data type: Map of one or more key-value pairs + - ``: String + - ``: String or integer + +### `ConnectTimeout` + +Specifies the timeout duration for establishing new network connections to this service. The duration is measured in seconds. + +#### Values + +- Default: `15s` +- Data type: String + +### `RequestTimeout` + +Specifies the timeout duration for receiving an HTTP response from this service, measured in seconds. When set to `0s`, the default value of `15s` is used instead. + +#### Values + +- Default: `15s` +- Data type: String + +### `Subsets` + +Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a filtering expression. If empty, only the unnamed default subset is usable. + +#### Values + +- Default: None +- Data type: Map containing a key/value pair. + - ``: String that names the subset. The string must be valid as a DNS subdomain element. + - ``: Map that can contain the following fields: + | Parameter | Description | Data type | Default | + | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | + | `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | + | `OnlyPassing` | Determines if instances that return a warning from a health check are allowed to resolve a request. When set to `false`, instances with `passing` and `warning` states are considered healthy. When set to `true`, only instances with a `passing` health check state are considered healthy. | Boolean | `false` | + +### `DefaultSubset` + +Specifies a defined subset of service instances to use when no explicit subset is requested. If empty, Consul uses the unnamed default subset. + +#### Values + +- Default: None +- Data type: String + +### `Redirect` + +Specifies redirect instructions for local service traffic so that services deployed to a different network location resolve the upstream request instead. When this field is defined, Consul ignores all other fields in a service resolver configuration entry except for `Kind`, `Name`, `Namespace`. When there are multiple redirects defined for a single service, Consul uses only the first one it applies. + +#### Values + +- Default: None +- Data type: Map that can contain the following paramters: + | Parameter | Description | Data type | Default | + | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | + | `Service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | + | `ServiceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `Redirect` map: `Service`, `Namespace`, `Datacenter` | String | None | + | `Namespace` | Specifies the namespace at the redirect’s destination that resolves local upstream requests. | String | None | + | `Partition` | Specifies the admin partition at the redirect’s destination that resolves local upstream requests. | String | None | + | `Datacenter` | Specifies the datacenter at the redirect’s destination that resolves local upstream requests. | String | None | + | `Peer` | Specifies the cluster with an active cluster peering connection at the redirect’s destination that resolves local upstream requests. Requires separately defined service intentions that [authorize services for peers](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers). When Consul runs a health check before resolving requests from the peer, it does not apply health checks that were defined on the peer and exported to the local cluster through the exported services configuration entry. | String | None | + +### `Failover` + +Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. + +This map is keyed by the name of the local service subset whose traffic should redirect when it fails. The `"*"` wildcard can be used to apply failovers to any subset. + +`Service`, `ServiceSubset`, `Namespace`, `Targets`, and `Datacenters` cannot all be empty at the same time. + +#### Values + +- Default: None +- Data type: Map that can contain the following objects: +- Data type: Map that can contain the following paramters: + | Parameter | Description | Data type | Default | + | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | + | `Service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | + | `ServiceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`DefaultSubset](#defaultsubset). | String | None | + | `Namespace` | Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. | String | None | + | `Datacenters` | Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. | String | None | + | `Targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`Failover{}.Targets`](#failover-targets) for configuration details. | List | None | + +### `Failover{}.Targets` + +Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. + +For examples, refer to the [failover example configurations](#examples-failover). + +#### Values + +- Default: None +- Data type: List of maps that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | + | `Service` | Specifies the service name to use for the failover target. If empty, the current service name is used. | String | None | + | `ServiceSubset` | Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used. | String | None | + | `Namespace` | Specifies the namespace to use for the failover target. If empty, the default namespace is used. | String | None | + | `Partition` | Specifies the admin partition within the same datacenter to use for the failover target. If empty, the `default` partition is used. To use an admin partition in a different datacenter for the failover target, use the `Peer` field instead. | String | None | + | `Datacenter` | Specifies the WAN federated datacenter to use for the failover target. If empty, the current datacenter is used. To use a datacenter for the failover target that is connected with a cluster peering relationship rather than WAN federation, use the `Peer` field instead. | String | None | + | `Peer` | Specifies the destination cluster peer to resolve the target service name from. [Intentions](/consul/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) must be defined on the peered cluster so that the source service can access this failover target service as an upstream. When the peer name is specified, Consul uses Envoy's outlier detection to determine the health of the failover target based on whether services can communicate with the failover target. Consul ignores service health checks imported from a peer for failover targets because the checks do not account for service routers, splitters, and resolvers that may be defined in the peer for the target service. | String | None | + +### `LoadBalancer` + +Specifies the load balancing policy and configuration for services issuing requests to this upstream. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | + | `Policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`LoadBalancer{}.Policy`](#loadbalancer-policy) for additional configuration parameters. | Map | None | + | `LeastRequestConfig` | Specifies configuration for the `least_request policy` type. Refer to [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig) for additional configuration parameters. | Map | None | + | `RingHashConfig` | Specifies configuration for the `ring_hash` policy type. Refer to [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig) for additional configuration parameters. | Map | None | + | `HashPolicies` | Specifies a list of hash policies to use for hashing load balancing algorithms. Refer to [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies) for additional configuration parameters. | Map | None | + +### `LoadBalancer{}.Policy` + +Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include: + +- Random +- Round robin +- Least request +- Ring hash +- Maglev + +#### Values + +- Default: None +- Data type: String containing one of the following values: + | Policy type | Description | + | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | + | `round_robin` | The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. | + | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). | + | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). | + | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). | + +### `LoadBalancer{}.LeastRequestConfig` + +Specifies configuration for the `least_request policy` type. + +#### Values + +- Default: None +- Data type: Map containing the following object: + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | + | `ChoiceCount` | Specifies the number of random healthy hosts from which to select the one with the least requests. | Integer | `2` | + +### `LoadBalancer{}.RingHashConfig` + +Specifies configuration for the `ring_hash` policy type. + +#### Values + +- Default: None +- Data type: List that can contain the following maps: + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------- | --------- | ------- | + | `MinimumRingSize` | Determines the minimum number of entries in the hash ring. | Integer | `1024` | + | `MaximumRingSize` | Determines the maximum number of entries in the hash ring. | Integer | `8192` | + +### `LoadBalancer{}.HashPolicies` + +Specifies a list of hash policies to use for hashing load balancing algorithms. Consul evaluates hash policies individually and combines them so that identical lists result in the same hash. If no hash policies are present or successfully evaluated, then Consul selects a random backend host. + +#### Values + +- Default: None +- Data type: List of maps for the following parameters: + | Parameter | Description | Data type | Default | + | :------------- | :------------------------------------------------------------- | --------- | ------- | + | `Field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `Field` parameter if `SourceIP` is also configured. | String | None | + | `FieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `FieldValue` parameter if `SourceIP` is also configured. | String | None | + | `CookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`LoadBalancer{}.HashPolicies[].CookieConfig`](#loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | + | `SourceIP` | Determines if the hash type should besource IP address. You cannot specify `SourceIP` if `Field` or `FieldValue` are configured. | Boolean | `false` | + | `Terminal` | Determines if Consul should short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + +### `LoadBalancer{}.HashPolicies[].CookieConfig` + +Specifies additional configuration options for the `cookie` hash policy type. This field causes Envoy to generate a cookie for a client on its first request. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | + | `Session` | Directs Consul to generate a session cookie with no expiration. | Boolean | `false` | + | `TTL` | Specifies the TTL for generated cookies. Cannot be specified for session cookies. | String | `0s` | + | `Path` | Specifies the path to set for the cookie. | String | None | + + + + + +### `apiVersion` + +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`. -The `service-resolver` config entry kind (`ServiceResolver` on Kubernetes) controls which service instances -should satisfy Connect upstream discovery requests for a given service name. +#### Values -If no resolver config is defined the chain assumes 100% of traffic goes to the -healthy instances of the default service in the current datacenter+namespace -and discovery terminates. +- Default: None +- This field is required. +- String value that must be set to `consul.hashicorp.com/v1alpha1`. -## Interaction with other Config Entries +### `kind` -- Service resolver config entries are a component of [L7 Traffic - Management](/consul/docs/connect/l7-traffic). +Specifies the type of configuration entry to implement. Must be set to `ServiceResolver`. -## UI +#### Values -Once a `service-resolver` is successfully entered, you can view it in the UI. Service routers, service splitters, and service resolvers can all be viewed by clicking on your service then switching to the *routing* tab. +- Default: None +- This field is required. +- Data type: String value that must be set to `ServiceResolver`. -![screenshot of service resolver in the UI](/img/l7-routing/Resolver.png) +## `metadata` -## Sample Config Entries +Map that contains an arbitrary name for the configuration entry and the namespace it applies to. + +#### Values + +- Default: None +- Data type: Map + +### `metadata.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: None +- This field is required. +- Data type: String + +### `metadata.namespace` + +Specifies the namespace that the service resolver applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information. + +#### Values + +- Default: None +- Data type: String + +### `spec` + +Map that contains the details about the `ServiceIntentions` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +### `spec.connectTimeout` + +Specifies the timeout duration for establishing new network connections to this service. The duration is measured in seconds. + +#### Values + +- Default: `15s` +- Data type: String + +### `spec.requestTimeout` + +Specifies the timeout duration for receiving an HTTP response from this service, measured in seconds. When set to `0s`, the default value of `15s` is used instead. + +#### Values + +- Default: `15s` +- Data type: String + +### `spec.subsets` + +Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a filtering expression. If empty, only the unnamed default subset is usable. + +#### Values + +- Default: None +- Data type: Map containing a key/value pair. + - ``: String that names the subset. The string must be valid as a DNS subdomain element. + - ``: Map that can contain the following fields: + | Parameter | Description | Data type | Default | + | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | + | `filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | + | `onlyPassing` | Determines if instances that return a warning from a health check are allowed to resolve a request. When set to `false`, instances with `passing` and `warning` states are considered healthy. When set to `true`, only instances with a `passing` health check state are considered healthy. | Boolean | `false` | + +### `spec.defaultSubset` + +Specifies a defined subset of service instances to use when no explicit subset is requested. If empty, Consul uses the unnamed default subset. + +#### Values + +- Default: None +- Data type: String + +### `spec.redirect` + +Specifies redirect instructions for local service traffic so that services deployed to a different network location resolve the upstream request instead. When this field is defined, Consul ignores all other fields in a service resolver configuration entry except for `kind`, `name`, `namespace`. When there are multiple redirects defined for a single service, Consul uses only the first one it applies. + +#### Values + +- Default: None +- Data type: Map that can contain the following paramters: + | Parameter | Description | Data type | Default | + | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | + | `service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | + | `serviceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `redirect` map: `service`, `namespace`, `datacenter` | String | None | + | `namespace` | Specifies the namespace at the redirect’s destination that resolves local upstream requests. | String | None | + | `partition` | Specifies the admin partition at the redirect’s destination that resolves local upstream requests. | String | None | + | `datacenter` | Specifies the datacenter at the redirect’s destination that resolves local upstream requests. | String | None | + | `peer` | Specifies the cluster with an active cluster peering connection at the redirect’s destination that resolves local upstream requests. Requires separately defined service intentions that [authorize services for peers](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers). When Consul runs a health check before resolving requests from the peer, it does not apply health checks that were defined on the peer and exported to the local cluster through the exported services configuration entry. | String | None | + +### `spec.failover` + +Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. + +This map is keyed by the name of the local service subset whose traffic should redirect when it fails. The `"*"` wildcard can be used to apply failovers to any subset. + +`service`, `serviceSubset`, `namespace`, `targets`, and `Datacenters` cannot all be empty at the same time. + +#### Values + +- Default: None +- Data type: Map that can contain the following objects: +- Data type: Map that can contain the following paramters: + | Parameter | Description | Data type | Default | + | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | + | `service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | + | `serviceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`defaultSubset](#spec-defaultsubset). | String | None | + | `namespace` | Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. | String | None | + | `datacenters` | Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. | String | None | + | `targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`spec-failover{}.targets`](#spec-failover-targets) for configuration details. | List | None | + +### `spec.failover.targets` + +Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. + +For examples, refer to the [failover example configurations](#examples-failover). + +#### Values + +- Default: None +- Data type: List of maps that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | + | `service` | Specifies the service name to use for the failover target. If empty, the current service name is used. | String | None | + | `serviceSubset` | Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used. | String | None | + | `namespace` | Specifies the namespace to use for the failover target. If empty, the default namespace is used. | String | None | + | `partition` | Specifies the admin partition within the same datacenter to use for the failover target. If empty, the `default` partition is used. To use an admin partition in a different datacenter for the failover target, use the `peer` field instead. | String | None | + | `datacenter` | Specifies the WAN federated datacenter to use for the failover target. If empty, the current datacenter is used. To use a datacenter for the failover target that is connected with a cluster peering relationship rather than WAN federation, use the `peer` field instead. | String | None | + | `peer` | Specifies the destination cluster peer to resolve the target service name from. [Intentions](/consul/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) must be defined on the peered cluster so that the source service can access this failover target service as an upstream. When the peer name is specified, Consul uses Envoy's outlier detection to determine the health of the failover target based on whether services can communicate with the failover target. Consul ignores service health checks imported from a peer for failover targets because the checks do not account for service routers, splitters, and resolvers that may be defined in the peer for the target service. | String | None | + +### `spec.loadBalancer` + +Specifies the load balancing policy and configuration for services issuing requests to this upstream. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | + | `policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`spec.loadBalancer{}.policy`](#spec-loadbalancer-policy) for additional configuration parameters. | Map | None | + | `leastRequestConfig` | Specifies configuration for the `least_request policy` type. Refer to [`spec.loadBalancer{}.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig) for additional configuration parameters. | Map | None | + | `ringHashConfig` | Specifies configuration for the `ring_hash` policy type. Refer to [`spec.loadBalancer{}.ringHashConfig`](#spec-loadbalancer-ringhashconfig) for additional configuration parameters. | Map | None | + | `hashPolicies` | Specifies a list of hash policies to use for hashing load balancing algorithms. Refer to [`spec.loadBalancer{}.hashPolicies`](#spec-loadbalancer-hashpolicies) for additional configuration parameters. | Map | None | + +### `spec.loadBalancer.policy` + +Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include: + +- Random +- Round robin +- Least request +- Ring hash +- Maglev + +#### Values + +- Default: None +- Data type: String containing one of the following values: + | Policy type | Description | + | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | + | `round_robin` | The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. | + | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`spec.loadBalancer{}.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig). | + | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer{}.ringHashConfig`](#spec-loadbalancer-ringhashconfig). | + | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer{}.hashPolicies`](#spec-loadbalancer-hashpolicies). | + +### `spec.loadBalancer.leastRequestConfig` + +Specifies configuration for the `least_request policy` type. + +#### Values + +- Default: None +- Data type: Map containing the following parameter: + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | + | `choiceCount` | Specifies the number of random healthy hosts from which to select the one with the least requests. | Integer | `2` | + +### `spec.loadBalancer.ringHashConfig` + +Specifies configuration for the `ring_hash` policy type. + +#### Values + +- Default: None +- Data type: List that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------- | --------- | ------- | + | `minimumRingSize` | Determines the minimum number of entries in the hash ring. | Integer | `1024` | + | `maximumRingSize` | Determines the maximum number of entries in the hash ring. | Integer | `8192` | + +### `spec.loadBalancer.hashPolicies` + +Specifies a list of hash policies to use for hashing load balancing algorithms. Consul evaluates hash policies individually and combines them so that identical lists result in the same hash. If no hash policies are present or successfully evaluated, then Consul selects a random backend host. + +#### Values + +- Default: None +- Data type: List that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------- | :------------------------------------------------------------- | --------- | ------- | + | `field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `field` parameter if `sourceIP` is also configured. | String | None | + | `fieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `fieldValue` parameter if `sourceIP` is also configured. | String | None | + | `cookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`spec.loadBalancer{}.hashPolicies[].cookieConfig`](spec-loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | + | `sourceIP` | Determines if the hash type should besource IP address. You cannot specify `sourceIP` if `field` or `fieldValue` are configured. | Boolean | `false` | + | `Terminal` | Determines if Consul should short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + +### `spec.loadBalancer{}.hashPolicies[].cookieConfig` + +Specifies additional configuration options for the `cookie` hash policy type. This field causes Envoy to generate a cookie for a client on its first request. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | + | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | + | `session` | Directs Consul to generate a session cookie with no expiration. | Boolean | `false` | + | `ttl` | Specifies the TTL for generated cookies. Cannot be specified for session cookies. | String | `0s` | + | `path` | Specifies the path to set for the cookie. | String | None | + + + + +## Examples + +The following examples demonstrate common service resolver configuration patterns for specific use cases. ### Filter on service version @@ -82,9 +911,9 @@ spec: -### Other datacenters +### Resolve virtual upstreams -Expose a set of services in another datacenter as a virtual service: +Expose a set of services to another datacenter as a virtual service: @@ -173,6 +1002,8 @@ spec: +#### Failover for federation and cluster peering + Enable failover to a WAN federated datacenter and then a cluster peer for all service subsets. @@ -225,6 +1056,9 @@ spec: + +#### Failover for all service subsets + Failover to another datacenter and namespace for all service subsets. @@ -274,6 +1108,9 @@ spec: + +#### Failover to a namespace + Failover within a datacenter and a different namespace. @@ -373,436 +1210,3 @@ spec: ``` - -## Available Fields - -', - yaml: false, - }, - { - name: 'Namespace', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the namespace in which the configuration entry will apply.', - yaml: false, - }, - { - name: 'Partition', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the admin partition in which the configuration entry will apply.', - yaml: false, - }, - { - name: 'Meta', - type: 'map: nil', - description: - 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.', - yaml: false, - }, - { - name: 'metadata', - children: [ - { - name: 'name', - description: 'Set to the name of the service being configured.', - }, - { - name: 'namespace', - description: - 'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for more details.', - }, - ], - hcl: false, - }, - { - name: 'ConnectTimeout', - type: 'duration: 0s', - description: - 'The timeout for establishing new network connections to this service. The default unit of time is `ns`.', - }, - { - name: 'RequestTimeout', - type: 'duration: 0s', - description: - 'The timeout for receiving an HTTP response from this service before the connection is terminated. If unspecified or 0, the default of 15s is used. The default unit of time is `ns`.', - }, - { - name: 'DefaultSubset', - type: 'string: ""', - description: - 'The subset to use when no explicit subset is requested. If empty, the unnamed subset is used.', - }, - { - name: 'Subsets', - type: 'map[string]ServiceResolverSubset', - description: - 'A map of subset name to subset definition for all usable named subsets of this service. The map key is the name of the subset and all names must be valid DNS subdomain elements.

This may be empty, in which case only the unnamed default subset will be usable.', - children: [ - { - name: 'Filter', - type: 'string: ""', - description: `The filter expression for selecting instances of the - requested service. If empty, all healthy instances are returned. - This expression can filter on the same selectors as the - [Health API endpoint](/consul/api-docs/health#filtering-2).`, - }, - { - name: 'OnlyPassing', - type: 'bool: false', - description: `Specifies the behavior of the resolver's - health check interpretation. If this is set to false, instances with checks - in the passing as well as the warning states will be considered healthy. If - this is set to true, only instances with checks in the passing state will - be considered healthy.`, - }, - ], - }, - { - name: 'Redirect', - type: 'ServiceResolverRedirect: ', - description: { - hcl: `When configured, all attempts to resolve the service this resolver defines will be substituted for the supplied redirect EXCEPT when the redirect has already been applied. -

- When \`Redirect\` is set, all other fields besides \`Kind\`, \`Name\`, \`Namespace\` and \`Redirect\` will be ignored.`, - yaml: `When configured, all attempts to resolve the service this resolver defines will be substituted for the supplied redirect EXCEPT when the redirect has already been applied. -

- When \`redirect\` is set, all other fields besides \`redirect\` will be ignored.`, - }, - children: [ - { - name: 'Service', - type: 'string: ""', - description: 'A service to resolve instead of the current service.', - }, - { - name: 'ServiceSubset', - type: 'string: ""', - description: { - hcl: `A named subset of the given service to - resolve instead of one defined as that service's \`DefaultSubset\`. If empty, the - default subset is used. -

- If this is specified at least one of \`Service\`, \`Datacenter\`, or \`Namespace\` - should be configured.`, - yaml: `A named subset of the given service to - resolve instead of one defined as that service's \`defaultSubset\`. If empty, the - default subset is used. -

- If this is specified at least one of \`service\`, \`datacenter\`, or \`namespace\` - should be configured.`, - }, - }, - { - name: 'Namespace', - enterprise: true, - type: 'string: ""', - description: - 'Specifies the destination namespace to resolve the service from.', - }, - { - name: 'Partition', - enterprise: true, - type: 'string: ""', - description: - 'Specifies the destination admin partition to resolve the service from.', - }, - { - name: 'Datacenter', - type: 'string: ""', - description: - 'Specifies the destination datacenter to resolve the service from.', - }, - { - name: 'Peer', - type: 'string: ""', - description: - `Specifies the destination cluster peer to resolve the target service name from. - Ensure that [intentions are defined](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers) - on the peered cluster to allow the source service to access this redirect target service as an upstream. When - the peer name is specified, Consul uses Envoy's outlier detection to determine - the health of the redirect target based on whether communication attempts to the - redirect target are generally successful. Service health checks imported from a peer - are not considered in the health of a redirect target because they do not account for service - routers, splitters, and resolvers that may be defined in the peer for the target service.`, - }, - ], - }, - { - name: 'Failover', - type: 'map[string]ServiceResolverFailover', - description: { - hcl: `Controls when and how to - reroute traffic to an alternate pool of service instances. -

- The map is keyed by the service subset it applies to and the special - string \`"*"\` is a wildcard that applies to any subset not otherwise - specified here. -

- \`Service\`, \`ServiceSubset\`, \`Namespace\`, \`Targets\`, and - \`Datacenters\` cannot all be empty at once.`, - yaml: `Controls when and how to - reroute traffic to an alternate pool of service instances. -

- The map is keyed by the service subset it applies to and the special - string \`"*"\` is a wildcard that applies to any subset not otherwise - specified here. -

- \`service\`, \`serviceSubset\`, \`namespace\`, \`targets\` and - \`datacenters\` cannot all be empty at once.`, - }, - children: [ - { - name: 'Service', - type: 'string: ""', - description: - 'The service to resolve instead of the default as the failover group of instances during failover.', - }, - { - name: 'ServiceSubset', - type: 'string: ""', - description: - 'The named subset of the requested service to resolve as the failover group of instances. If empty, the default subset for the requested service is used.', - }, - { - name: 'Namespace', - enterprise: true, - type: 'string: ""', - description: - 'The namespace to resolve the requested service from to form the failover group of instances. If empty, the current namespace is used.', - }, - { - name: 'Datacenters', - type: 'array', - description: 'A fixed list of datacenters to try during failover.', - }, - { - name: 'Targets', - type: 'array', - description: `A fixed list of failover targets to try during - failover. It allows operators to express complicated failover - scenarios such as between cluster peers, WAN federated datacenters, and local admin partitions.`, - children: [ - { - name: 'Service', - type: 'string: ""', - description: - 'The service name to use for the failover target. If empty, the current service name is used.', - }, - { - name: 'ServiceSubset', - type: 'string: ""', - description: - 'The named subset to use for the failover target. If empty, the default subset for the requested service name is used.', - }, - { - name: 'Namespace', - enterprise: true, - type: 'string: ""', - description: - `The namespace to use for the failover target. If empty, the \`default\` namespace is used.`, - }, - { - name: 'Partition', - enterprise: true, - type: 'string: ""', - description: - `The admin partition within the same datacenter to use for the failover target. - If empty, the \`default\` partition is used. - To use an admin partition in a different datacenter for the failover target, - use the \`Peer\` field instead.`, - }, - { - name: 'Datacenter', - type: 'string: ""', - description: - `The WAN federated datacenter to use for the failover target. - If empty, the current datacenter is used. - To use a datacenter for the failover target that is connected - with a cluster peering relationship rather than WAN federation, - use the \`Peer\` field instead.`, - }, - { - name: 'Peer', - type: 'string: ""', - description: - `Specifies the destination cluster peer to resolve the target service name from. - Ensure that [intentions are defined](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers) - on the peered cluster to allow the source service to access this failover target service as an upstream. - When the peer name is specified, Consul uses Envoy's outlier detection - to determine the health of the failover target based on - whether communication attempts to the failover target are generally successful. - Service health checks imported from a peer are not considered in the health - of a failover target because they do not account for service routers, splitters, and resolvers - that may be defined in the peer for the target service.`, - }, - ], - }, - ], - }, - { - name: 'LoadBalancer', - type: 'LoadBalancer', - description: - 'Determines the load balancing policy and configuration for services issuing requests to this upstream. This option is available in Consul versions 1.9.0 and newer.', - children: [ - { - name: 'Policy', - type: 'string: ""', - description: - 'The load balancing policy used to select a host. One of: `random`, `round_robin`, `least_request`, `ring_hash`, `maglev`.', - }, - { - name: 'RingHashConfig', - type: 'RingHashConfig', - description: 'Configuration for the `ring_hash` policy type.', - children: [ - { - name: 'MinimumRingSize', - type: 'int: 1024', - description: - 'Determines the minimum number of entries in the hash ring.', - }, - { - name: 'MaximumRingSize', - type: 'int: 8192', - description: - 'Determines the maximum number of entries in the hash ring.', - }, - ], - }, - { - name: 'LeastRequestConfig', - type: 'LeastRequestConfig', - description: 'Configuration for the `least_request` policy type.', - children: [ - { - name: 'ChoiceCount', - type: 'int: 2', - description: - 'Determines the number of random healthy hosts from which to select the one with the least requests.', - }, - ], - }, - { - name: 'HashPolicies', - type: 'array', - description: `List of hash policies to use for - hashing load balancing algorithms. Hash policies are evaluated individually - and combined such that identical lists result in the same hash. - If no hash policies are present, or none are successfully evaluated, - then a random backend host will be selected.`, - children: [ - { - name: 'Field', - type: 'string: ""', - description: { - hcl: - 'The attribute type to hash on. Must be one of `header`, `cookie`, or `query_parameter`. Cannot be specified along with `SourceIP`.', - yaml: - 'The attribute type to hash on. Must be one of `header`, `cookie`, or `query_parameter`. Cannot be specified along with `sourceIP`.', - }, - }, - { - name: 'FieldValue', - type: 'string: ""', - description: { - hcl: - 'The value to hash. ie. header name, cookie name, URL query parameter name. Cannot be specified along with `SourceIP`.', - yaml: - 'The value to hash. ie. header name, cookie name, URL query parameter name. Cannot be specified along with `sourceIP`.', - }, - }, - { - name: 'CookieConfig', - type: 'CookieConfig', - description: - 'Additional configuration for the "cookie" hash policy type. This is specified to have Envoy generate a cookie for a client on its first request.', - children: [ - { - name: 'Session', - type: 'bool: false', - description: 'Generates a session cookie with no expiration.', - }, - { - name: 'TTL', - type: 'duration: 0s', - description: - 'TTL for generated cookies. Cannot be specified for session cookies.', - }, - { - name: 'Path', - type: 'string: ""', - description: 'The path to set for the cookie.', - }, - ], - }, - { - name: 'SourceIP', - type: 'bool: false', - description: { - hcl: - 'Determines whether the hash should be of the source IP address rather than of a field and field value. Cannot be specified along with `Field` or `FieldValue`.', - yaml: - 'Determines whether the hash should be of the source IP address rather than of a field and field value. Cannot be specified along with `field` or `fieldValue`.', - }, - }, - { - name: 'Terminal', - type: 'bool: false', - description: - 'Will short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a Terminal policy is evaluated, then that hash will be used and subsequent hash policies will be ignored.', - }, - ], - }, - ], - }, - ]} -/> - -## Service Subsets - -A service subset assigns a concrete name to a specific subset of discoverable -service instances within a datacenter, such as `"version2"` or `"canary"`. - -A service subset name is useful only when composed with an actual service name, -a specific datacenter, and namespace. - -All services have an unnamed default subset that will return all healthy -instances unfiltered. - -Subsets are defined in `service-resolver` configuration entries, but are -referenced by their names throughout the other configuration entry kinds. - -## ACLs - -Configuration entries may be protected by [ACLs](/consul/docs/security/acl). - -Reading a `service-resolver` config entry requires `service:read` on the resource. - -Creating, updating, or deleting a `service-resolver` config entry requires -`service:write` on the resource and `service:read` on any other service referenced by -name in these fields: - -- [`Redirect.Service`](#service) - -- [`Failover[].Service`](#service-1) From 934a8ad10e2637d2626e5a8a2257ed4301a5025e Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 25 Apr 2023 10:14:45 -0700 Subject: [PATCH 02/25] Updates --- .../config-entries/service-resolver.mdx | 78 +++++++++++-------- 1 file changed, 46 insertions(+), 32 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 2a303d132dcb..6c89d275a4e2 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -19,13 +19,13 @@ The following list outlines field hierarchy, language-specific data types, and r -- [`Kind`](#kind): string | `service-resolver` | required +- [`Kind`](#kind): string | required | must be set to `service-resolver` - [`Name`](#name): string | required - [`Namespace`](#namespace): string | `default` - [`Partition`](#partition): string | `default` - [`Meta`](#meta): map - [`ConnectTimeout`](#connecttimeout): string | `0s` -- [`RequestTimeout`](#requesttimeout): string | `0s` +- [`RequestTimeout`](#requesttimeout): string | `15s` - [`Subsets`](#subsets): map - [`Filter`](#subsets): string - [`OnlyPassing`](#subsets): boolean | `false` @@ -70,14 +70,14 @@ The following list outlines field hierarchy, language-specific data types, and r -- [`apiVersion`](#apiversion): string | required | `consul.hashicorp.com/v1alpha1` -- [`kind`](#kind): string | required | `serviceResolver` +- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | required | must be set to `serviceResolver` - [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional - [`spec`](#spec): map | required - [`connectTimeout`](#spec-connecttimeout): string | `0s` - - [`requestTimeout`](#spec-requesttimeout): string | `0s` + - [`requestTimeout`](#spec-requesttimeout): string | `15s` - [`subsets`](#spec-subsets): map - [`filter`](#spec-subsets-filter): string - [`onlyPassing`](#spec-subsets-onlypassing): boolean | `false` @@ -139,7 +139,7 @@ Meta = { } ConnectTimeout = "10s" -RequestTimeout = "5s" +RequestTimeout = "15s" Subsets = { = { Filter = "" @@ -162,7 +162,7 @@ Redirect = { } Failover = { ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters - = { + = { Targets = [ { Service = "" }, { ServiceSubset = "" }, @@ -221,7 +221,7 @@ LoadBalancer = { }, "ConnectTimeout":"10s", - "RequestTimeout":"5s", + "RequestTimeout":"15s", "Subsets":{ "":{ "Filter":"", @@ -300,7 +300,7 @@ metadata: namespace: spec: connectTimeout: 10s - requestTimeout: 5s + requestTimeout: 15s subsets: : filter: @@ -414,7 +414,7 @@ Specifies the timeout duration for establishing new network connections to this #### Values -- Default: `15s` +- Default: `0s` - Data type: String ### `RequestTimeout` @@ -436,6 +436,7 @@ Specifies names for service subsets and the conditions under which service insta - Data type: Map containing a key/value pair. - ``: String that names the subset. The string must be valid as a DNS subdomain element. - ``: Map that can contain the following fields: + | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | | `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | @@ -458,6 +459,7 @@ Specifies redirect instructions for local service traffic so that services deplo - Default: None - Data type: Map that can contain the following paramters: + | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `Service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | @@ -478,8 +480,8 @@ This map is keyed by the name of the local service subset whose traffic should r #### Values - Default: None -- Data type: Map that can contain the following objects: -- Data type: Map that can contain the following paramters: +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `Service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | @@ -498,6 +500,7 @@ For examples, refer to the [failover example configurations](#examples-failover) - Default: None - Data type: List of maps that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `Service` | Specifies the service name to use for the failover target. If empty, the current service name is used. | String | None | @@ -515,6 +518,7 @@ Specifies the load balancing policy and configuration for services issuing reque - Default: None - Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | | `Policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`LoadBalancer{}.Policy`](#loadbalancer-policy) for additional configuration parameters. | Map | None | @@ -536,6 +540,7 @@ Specifies the type of load balancing policy for selecting a host. Supported load - Default: None - Data type: String containing one of the following values: + | Policy type | Description | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | @@ -552,6 +557,7 @@ Specifies configuration for the `least_request policy` type. - Default: None - Data type: Map containing the following object: + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | | `ChoiceCount` | Specifies the number of random healthy hosts from which to select the one with the least requests. | Integer | `2` | @@ -564,6 +570,7 @@ Specifies configuration for the `ring_hash` policy type. - Default: None - Data type: List that can contain the following maps: + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------- | --------- | ------- | | `MinimumRingSize` | Determines the minimum number of entries in the hash ring. | Integer | `1024` | @@ -577,6 +584,7 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. - Default: None - Data type: List of maps for the following parameters: + | Parameter | Description | Data type | Default | | :------------- | :------------------------------------------------------------- | --------- | ------- | | `Field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `Field` parameter if `SourceIP` is also configured. | String | None | @@ -593,6 +601,7 @@ Specifies additional configuration options for the `cookie` hash policy type. Th - Default: None - Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | | `Session` | Directs Consul to generate a session cookie with no expiration. | Boolean | `false` | @@ -667,7 +676,7 @@ Specifies the timeout duration for establishing new network connections to this #### Values -- Default: `15s` +- Default: `0s` - Data type: String ### `spec.requestTimeout` @@ -688,7 +697,8 @@ Specifies names for service subsets and the conditions under which service insta - Default: None - Data type: Map containing a key/value pair. - ``: String that names the subset. The string must be valid as a DNS subdomain element. - - ``: Map that can contain the following fields: + - ``: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | | `filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | @@ -710,7 +720,8 @@ Specifies redirect instructions for local service traffic so that services deplo #### Values - Default: None -- Data type: Map that can contain the following paramters: +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | @@ -732,7 +743,8 @@ This map is keyed by the name of the local service subset whose traffic should r - Default: None - Data type: Map that can contain the following objects: -- Data type: Map that can contain the following paramters: +- Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | @@ -751,6 +763,7 @@ For examples, refer to the [failover example configurations](#examples-failover) - Default: None - Data type: List of maps that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `service` | Specifies the service name to use for the failover target. If empty, the current service name is used. | String | None | @@ -768,6 +781,7 @@ Specifies the load balancing policy and configuration for services issuing reque - Default: None - Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | | `policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`spec.loadBalancer{}.policy`](#spec-loadbalancer-policy) for additional configuration parameters. | Map | None | @@ -789,6 +803,7 @@ Specifies the type of load balancing policy for selecting a host. Supported load - Default: None - Data type: String containing one of the following values: + | Policy type | Description | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | @@ -805,6 +820,7 @@ Specifies configuration for the `least_request policy` type. - Default: None - Data type: Map containing the following parameter: + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | | `choiceCount` | Specifies the number of random healthy hosts from which to select the one with the least requests. | Integer | `2` | @@ -817,6 +833,7 @@ Specifies configuration for the `ring_hash` policy type. - Default: None - Data type: List that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------- | --------- | ------- | | `minimumRingSize` | Determines the minimum number of entries in the hash ring. | Integer | `1024` | @@ -830,6 +847,7 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. - Default: None - Data type: List that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------- | :------------------------------------------------------------- | --------- | ------- | | `field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `field` parameter if `sourceIP` is also configured. | String | None | @@ -846,6 +864,7 @@ Specifies additional configuration options for the `cookie` hash policy type. Th - Default: None - Data type: Map that can contain the following parameters: + | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | | `session` | Directs Consul to generate a session cookie with no expiration. | Boolean | `false` | @@ -861,7 +880,7 @@ The following examples demonstrate common service resolver configuration pattern ### Filter on service version -Create service subsets based on a version metadata and override the defaults: +The following example creates service subsets based on version metadata: @@ -913,7 +932,7 @@ spec: ### Resolve virtual upstreams -Expose a set of services to another datacenter as a virtual service: +The folowing example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service: @@ -952,7 +971,7 @@ spec: ### Failover -Enable failover for subset `v2` to `dc2`, and all other subsets to `dc3` or `dc4`: +The following example enables failover for subset `v2` to `dc2`. All other subsets attempt failover to `dc3`, and when it is not available, to `dc4`: @@ -1002,10 +1021,9 @@ spec: -#### Failover for federation and cluster peering +#### Failover targets for federation and cluster peering -Enable failover to a WAN federated datacenter and then a cluster peer for all -service subsets. +The following example enables failover to target a WAN federated datacenter for all service subsets. If the connection to `dc3` times out after 15 seconds, the service failover targets the peer with the establish cluster peering connection instead. @@ -1055,12 +1073,9 @@ spec: - - -#### Failover for all service subsets +#### Failover for all service subsets - Failover to another datacenter and namespace for all service subsets. - +The following example enables failover to the `secondary` namespace in another datacenter for all service subsets. @@ -1107,12 +1122,11 @@ spec: - -#### Failover to a namespace +#### Failover to a namespace + +The following example enables failover to a different namespace in the same datacenter. - Failover within a datacenter and a different namespace. - @@ -1161,7 +1175,7 @@ spec: ### Consistent load balancing -Apply consistent load balancing for requests based on `x-user-id` header: +The following example applies a Maglev load balancing policy for requests with an `x-user-id` header: From faaaef4b08a79e57b53cec2d30480397f462058c Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 25 Apr 2023 10:19:15 -0700 Subject: [PATCH 03/25] missing backtick --- .../content/docs/connect/config-entries/service-resolver.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 6c89d275a4e2..821493bcbf12 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -110,7 +110,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`maximumRingSize`](#spec-loadbalancer-ringhashconfig-maximum): integer | `8192` - [`hashPolicies`](#spec-loadbalancer-hashpolicies): list - [`field`](#spec-loadbalancer-hashpolicies-field): string - - [`fieldValue](#spec-loadbalancer-hashpolicies-fieldvalue): string + - [`fieldValue`](#spec-loadbalancer-hashpolicies-fieldvalue): string - [`cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig): map - [`session`](spec-#loadbalancer-hashpolicies-cookieconfig-session): boolean | `false` - [`ttl`](#spec-loadbalancer-hashpolicies-cookieconfig-ttl): string | `0s` From 3de651d1587223dcc69c8348a4f784e1f77848f3 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 25 Apr 2023 16:56:10 -0700 Subject: [PATCH 04/25] service router configuration entry reference --- .../config-entries/service-resolver.mdx | 6 +- .../connect/config-entries/service-router.mdx | 1332 +++++++++++------ 2 files changed, 875 insertions(+), 463 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 821493bcbf12..999441082ea9 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -133,7 +133,7 @@ When every field is defined, a service resolver configuration entry has the foll Kind = "service-resolver" ## required Name = "" Namespace = "" -Partition = "parition-configuration-applies-to>" +Partition = "" Meta = { = "" } @@ -439,7 +439,7 @@ Specifies names for service subsets and the conditions under which service insta | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | - | `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | + | `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). For more information about creating and using expressions to filter, refer to [filtering](/consul/api-docs/features/filtering). | String | None | | `OnlyPassing` | Determines if instances that return a warning from a health check are allowed to resolve a request. When set to `false`, instances with `passing` and `warning` states are considered healthy. When set to `true`, only instances with a `passing` health check state are considered healthy. | Boolean | `false` | ### `DefaultSubset` @@ -701,7 +701,7 @@ Specifies names for service subsets and the conditions under which service insta | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | - | `filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | + | `filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). For more information about creating and using expressions to filter, refer to [filtering](/consul/api-docs/features/filtering). | String | None | | `onlyPassing` | Determines if instances that return a warning from a health check are allowed to resolve a request. When set to `false`, instances with `passing` and `warning` states are considered healthy. When set to `true`, only instances with a `passing` health check state are considered healthy. | Boolean | `false` | ### `spec.defaultSubset` diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 1a12e3cdf9fa..ca8506a71ad0 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -1,53 +1,878 @@ --- layout: docs -page_title: Service Router - Configuration Entry Reference -description: >- - The service router configuration entry kind defines where the service mesh routes requests based on L7 network information such as header or path. Use the reference guide to learn about `""service-router""` config entry parameters and how behaviors like request timeouts, retry behavior, header modification, and path rewriting can be applied to a request based on its header or path information. +page_title: Service Router Configuration Entry Reference +description: >- + Service router configuration entries are L7 traffic management tools for redirecting requests for a service to a particular instance or set of instances. Learn how to write `service-router` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case. --- -# Service Router Configuration Entry +# Service router configuration entry reference + +This page provides reference information for service router configuration entries. Service routers use L7 network information to redirect a traffic request for a service to one or more specific service instances. + +Refer to [L7 traffic management overview](/consul/docs/connect/l7-traffic) for additional information. + +## Configuration model + +The following list outlines field hierarchy, language-specific data types, and requirements in this configuration entry. Click on a property name to view additional details, including default values. + + + + + +- [`Kind`](#kind): string | required | must be set to `service-router` +- [`Name`](#name): string | required +- [`Namespace`](#namespace): string +- [`Partition`](#partition): string | `default` +- [`Meta`](#meta): map +- [`Routes`](#routes): list + - [`Match`](#routes-match): map + - [‘HTTP`](#routes-match-http): map + - [`PathExact`](#routes-match-http-pathexact): string + - [`PathPrefix`](#routes-match-http-pathprefix): string + - [`PathRegex`](#routes-match-http-pathregex): string + - [`Methods`](#routes-match-http-methods): list + - [`Header`](#routes-match-http-header): list + - [`Name`](#routes-match-http-header-name): string + - [`Present`](#routes-match-http-header-present): boolean | `false` + - [`Exact`](#routes-match-http-header-exact): string + - [`Prefix`](#routes-match-http-header-prefix): string + - [`Suffix`](#routes-match-http-header-suffix): string + - [`Regex`](#routes-match-http-header-regex): string + - [`Invert`](#routes-match-http-header-invert): boolean | `false` + - [`QueryParam`](#routes-match-http-queryparam): list + - [`Name`](#routes-match-http-queryparam-name): string + - [`Present`](#routes-match-http-queryparam-present): boolean | `false` + - [`Exact`](#routes-match-http-queryparam-exact): string + - [`Regex`](#routes-match-http-queryparam-regex): string + - [`Destination`](#routes-destination): map + - [`Service`](#routes-destination-service): string + - [`ServiceSubset`](#routes-destination-servicesubset): string +- [`Namespace`](#routes-destination-namespace): string +- [`Partition`](#routes-destination-partition): string +- [`PrefixRewrite`](#routes-destination-prefixrewrite): string +- [`RequestTimeout`](#routes-destination-requesttimeout): integer | `0` +- [`IdleTimeout`](#routes-destination-idletimeout): integer | `0` +- [`NumRetries`](#routes-destination-numretries): integer | `1` +- [`RetryOnConnectFailure`](#routes-destination-retryonconnectfailure): boolean | `false` +- [`RetryOn`](#routes-destination-retryon): list +- [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes): list +- [`RequestHeaders`](#routes-destination-requestheaders): map + - [`Add`](#routes-destination-requestheaders): map + - [`Set`](#routes-destination-requestheaders): map + - [`Remove`](#routes-destination-requestheaders): map +- [`ResponseHeaders`](#routes-destination-responseheaders): map + - [`Add`](#routes-destination-responseheaders): map + - [`Set`](#routes-destination-responseheaders): map + - [`Remove`](#routes-destination-responseheaders): map + + + + + +- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | required | must be set to `serviceRouter` +- [`metadata`](#metadata): map | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): map | required + - [`routes`](#spec-routes): list + - [`match`](#spec-routes-match): map + - [‘http`](#spec-routes-match-http): map + - [`pathExact`](#spec-routes-match-http-pathexact): string + - [`pathPrefix`](#spec-routes-match-http-pathprefix): string + - [`pathRegex`](#spec-routes-match-http-pathregex): string + - [`methods`](#spec-routes-match-http-methods): list + - [`header`](#spec-routes-match-http-header): list + - [`name`](#spec-routes-match-http-header-name): string + - [`present`](#spec-routes-match-http-header-present): boolean | `false` + - [`exact`](#spec-routes-match-http-header-exact): string + - [`prefix`](#spec-routes-match-http-header-prefix): string + - [`suffix`](#spec-routes-match-http-header-suffix): string + - [`regex`](#spec-routes-match-http-header-regex): string + - [`invert`](#spec-routes-match-http-header-invert): boolean + - [`queryParam`](#spec-routes-match-http-queryparam): list + - [`name`](#spec-routes-match-http-queryparam-name): string + - [`present`](#spec-routes-match-http-queryparam-present): boolean | `false` + - [`regex`](#spec-routes-match-http-queryparam-regex): string + - [`destination`](#spec-routes-destination): map + - [`service`](#spec-routes-destination-service): string + - [`serviceSubset`](#spec-routes-destination-servicesubset): string + - [`namespace`](#spec-routes-destination-namespace): string + - [`partition`](#spec-routes-destination-partition): string + - [`prefixRewrite`](#spec-routes-destination-prefixrewrite): string + - [`requestTimeout`](#spec-routes-destination-requesttimeout): integer | `0` + - [`numRetries`](#spec-routes-destination-numretries): integer | `0` + - [`numRetries`](#spec-routes-destination-numretries): integer | `1` + - [`retryOnConnectFailure`](#spec-routes-destination-retryonconnectfailure): boolean | `false` + - [`retryOn`](#spec-routes-destination-retryon): list + - [`retryOnStatusCodes`](#spec-routes-destination-retryonstatuscodes): list + - [`requestHeaders`](#spec-routes-destination-requestheaders): map + - [`add`](#spec-routes-destination-requestheaders): map + - [`set`](#spec-routes-destination-requestheaders): map + - [`remove`](#spec-routes-destination-requestheaders): map + - [`responseHeaders`](#spec-routes-destination-responseheaders): map + - [`add`](#spec-routes-destination-responseheaders): map + - [`set`](#spec-routes-destination-responseheaders): map + - [`remove`](#spec-routes-destination-responseheaders): map + + + + +## Complete configuration + +When every field is defined, a service router configuration entry has the following form: + + + + -The `service-router` config entry kind (`ServiceRouter` on Kubernetes) controls Connect traffic routing and -manipulation at networking layer 7 (e.g. HTTP). +```hcl +Kind = "service-router" ## required +Name = "" ## required +Namespace = "" +Partition = "" +Meta = { + = "" +} + + +Routes = [ + { + Match { + HTTP { + PathExact = "" ## cannot specify with PathPrefix or PathRegex + }, + HTTP { + PathPrefix = "" ## cannot specify with PathExact or PathRegex + }, + HTTP { + PathRegex = "" ## cannot specify with PathPrefix or PathExact + }, + HTTP { + Methods = ["GET", "POST", "PUT"] + }, + HTTP { + Header = [ ## do not specify Present, Exact, Prefix, Suffix, and Regex in a single Header + { + Name = "" ## required when specifying Routes.Match.HTTP.Header + Present = false + Exact = "" + Prefix = "" + Suffix = "" + Regex = "" + Invert = false + } + ] + } + HTTP { + QueryParam = [ ## do not specify Present, Exact, and Regex in a single QueryParam + Name = "" ## required when specifying Routes.Match.HTTP.Header + Present = false + Exact = "" + Regex = "" + ] + } + }, + + + Destination { + Service = "" + ServiceSubset = "" + Namespace = "" + Partition = "" + PrefixRewrite = "" ## required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact + RequestTimeout = 0 + IdleTimeout = 0 + NumRetries = 1 + RetryOnConnectFailure = false + RetryOn = ["reset", "unavailable"] + RetryOnStatusCodes = [500, 502, 503] + RequestHeaders = { + Set = { + "X-Web-Version" : "" + } + } + ResponseHeaders = { + Set = { + "X-Web-Version" : "" + } + } + } + } +] +``` + + + + + +```json +{ + "Kind": "service-router", // required + "Name": "", // required + "Namespace": "", + "Partition": "", + "Meta": { + "": "" + }, + + "Routes": [ + { + "Match": { + "HTTP": { + "PathExact": "" // cannot specify with PathPrefix or PathRegex + }, + "HTTP": { + "PathPrefix": "" // cannot specify with PathExact or PathRegex + }, + "HTTP": { + "PathRegex": "" // cannot specify with PathPrefix or PathExact + }, + "HTTP": { + "Methods": ["GET", "POST", "PUT"] + }, + "HTTP": { + "Header": [ // do not specify Present, Exact, Prefix, Suffix, and Regex in a single Header + { + "Name": "", // required when specifying Routes.Match.HTTP.Header + "Present": false, + "Exact": "", + "Prefix": "", + "Suffix": "", + "Regex": "", + "Invert": false, + } + ] + }, + "HTTP": { + "QueryParam": [ // do not specify Present, Exact, and Regex in a single QueryParam + "Name": "", // required when specifying Routes.Match.HTTP.Header + "Present": false, + "Exact": "", + "Regex": "" + ] + } + }, + + "Destination": { + "Service": "", + "ServiceSubset": "", + "Namespace": "", + "Partition": "", + "PrefixRewrite": "", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact + "RequestTimeout": 0, + "IdleTimeout": 0, + "NumRetries": 1, + "RetryOnConnectFailure": false, + "RetryOn": ["reset", "unavailable"], + "RetryOnStatusCodes": [500, 502, 503], + "RequestHeaders": { + "Set": { + "X-Web-Version" : "" + } + }, + "ResponseHeaders": { + "Set": { + "X-Web-Version" : "" + } + } + } + } + ] +} +``` + + + + + +```yaml +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 # required +kind: ServiceRouter # required +metadata: + name: + namespace: +spec: + routes: + - match: + http: + pathExact: ## cannot specify with pathPrefix or pathRegex + http: + pathPrefix: ## cannot specify with pathExact or pathRegex + http: + pathRegex: ## cannot specify with pathPrefix or pathExact + http: + methods: [GET, POST, PUT] + http: + header: ## do not specify present, exact, prefix, suffix, and regex in a single header + - name: ## required when specifying routes.match.http.header + present: false + exact: + prefix: + suffix: + regex: + invert: false + http: + queryParam: ## do not specify present, exact, and regex in a single QueryParam + - name: ## required when specifying routes.match.http.header + present: false + exact: + regex: + + destination: + service: + serviceSubset: + namespace: + partition: + prefixRewrite: ## required specifying either routes.match.http.pathPrefix or routes.match.http.pathExact + requestTimeout: 0 + idleTimeout: 0 + numRetries: 1 + retryOnConnectFailure: false + retryOn: ['reset'] + retryOnStatusCodes: [500, 502, 503] + requestHeaders: + set: + x-Web-Version: + responseHeaders: + set: + x-Web-Version: +``` + + + + + +## Specification + +This section provides details about the fields you can configure in the service router configuration entry. + + + + + +### `Kind` + +Specifies the type of configuration entry to implement. + +#### Values + +- Default: none +- This field is required. +- Data type: String value that must be set to `service-router`. + +### `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 with the [`consul config` command](/consul/commands/config). + +#### 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` + +Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry to. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for additional information about Consul namespaces. + +#### Values + +- Default: None +- Data type: String + +### `Partition` + +Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to apply the configuration entry to. Refer to [Admin partitions](/consul/docs/enterprise/admin-partitions) for additional information. + +#### Values + +- Default: `default` +- Data type: String + +### `Meta` + +Specifies key-value pairs to add to the KV store. + +#### Values + +- Default: none +- Data type: Map of one or more key-value pairs + - ``: String + - ``: String or integer + +### `Routes` + +Defines the possible routes for L7 requests. Consul evaluates traffic against the list of routes in their order of appearance in the configuration entry. When multiple routes satisfy the request, Consul uses the first route that matches. Traffic that fails to match any of the provided routes is routed to the default service. + +#### Values + +- Default: None +- Data type: List that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | + | `Match` | The criteria the configuration entry uses to identify requests. Refer to [`Routes[].Match`](#routes-match) for additional configuration parameters. | Map | None | + | `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes`](#routes-destination) for additional configuration parameters. | Map | None | + +### `Routes[].Match` + +Describes a set of criteria that Consul compares incoming L7 traffic with. If empty or omitted, it acts as a catch-all. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `HTTP` | A set of HTTP-specific match criteria. Refer to [`Routes[].Match{}.HTTP`](#routes-match-http) for additional configuration parameters. | Map | None | + +### `Routes[].Match{}.HTTP` + +Specifies a set of HTTP criteria used to evaluate incoming L7 traffic for matches. + +When matching on the HTTP request path, you can only match on one path at a time. Do not configure `PathExact`, `PathPrefix`, and `PathRegex` in a single HTTP map. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `PathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same HTTP object. | String | None | +| `PathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathRegex` in the same HTTP object. | String | None | +| `PathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `Methods` | Specifies HTTP methods that the match applies to. Refer to [`Routes[].Match{}.HTTP{}.Methods`](#routes-march-http-methods) for additional configuration parameters. | List | None | +| `Header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header) for additional configuration parameters. | List | None | +| `QueryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `Present`, `Exact`, or `Regex` in the same HTTP object. Refer to [`Routes[].Match{}.HTTP{}.QueryParam](#routes-match-http-queryparam) for additional configuration parameters. | List | None | + +### `Routes[].Match{}.HTTP{}.Methods` + +Specifies HTTP methods that the match applies to. If not specified, the request matches on all HTTP methods. If provided, the name must be a valid method formatted as a string. + +#### Values + +- Default: None +- Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): + - `GET` + - `HEAD` + - `POST` + - `PUT` + - `DELETE` + - `CONNECT` + - `OPTIONS` + - `TRACE` + - `PATCH` + +### `Routes[].Match{}.HTTP{}.Header` + +Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. + +When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, and `Regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. + +#### Values + +- Default: None +- Data type: List containing one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `Name` | Specifies the name of the HTTP header to match. This field is required when using [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header). | String | None | +| `Present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. | Boolean | `false` | +| `Exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. | String | None | +| `Prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP object. | String | None | +| `Suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP object. | String | None | +| `Regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `Invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | + +### `Routes[].Match{}.HTTP{}.QueryParam` + +Specifies information to match to on HTTP query parameters. When more than one field is configured, all criteria must match for the service routing to apply. + +When using this field, do not configure `Present`, `Exact`, and `Regex` in a single map. You can use only one of these fields at a time when configuring match criteria for HTTP query parameters, as they are mutually exclusive with one another. + +#### Values + +- Default: None +- Data type: List of maps. Each map can contain one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `Name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`Routes[].Match{}.HTTP{}.QueryParam`](#routes-match-http-queryparam). | String | None | +| `Present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `Exact` or `Regex` in the same map. | Boolean | `false` | +| `Exact` | Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `Present` or `Regex` in the same map. | String | None | +| `Regex` | Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `Present` or `Exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | + +### `Routes[].Destination` + +Specifies the target service to route matching requests to, as well as behavior for the request to follow when routed. + +#### Values + +- Default: None +- Data type: Map containing one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `Service` | Specifies the name of the service to resolve instead of the default. If empty, the default service name is inherited from the configuration entry’s [`Name` field](#name). | String | None | +| `ServiceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None | +| `Namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | +| `Partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None | +| `PrefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Match.HTTP.PathPrefix`](#match-http-pathprefix) or [`Match.HTTP.PathExact`](#match-http-pathexact) be configured on this route. | String | None | +| `RequestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | +| `IdleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | +| `NumRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`. | Integer | `1` | +| `RetryOnConnectFailure` | Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). | Boolean | `false` | +| `RetryOn` | Specifies a list of conditions for Consul to retry requests. Use this field to configure advanced logic for retry attempts. Refer to [`Routes[].Destination{}.RetryOn[]`](#routes-destination-retryon) for additional configuration parameters. | List | None | +| `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. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). +| `RequestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`Routes[].Destination{}.RequestHeaders`](#routes-destination-requestheaders) for additional configuration parameters. | Map | None | +| `ResponseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`Routes[].Destination{}.ResponseHeaders`](#routes-destination-responseheaders) for additional configuration parameters. | Map | None | + +### `Routes[].Destination{}.RetryOn[]` + +Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `Destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +#### Values + +- Default: None +- Data type: List of strings. Strings must match one of the following values: + +| Conditions | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------- | +| `5xx` | Consul encountered a 5xx HTTP response code error code while routing the request. | +| `gateway-error` | Consul encountered a gateway error while routing the request. | +| `reset` | The Consul server was reset while routing the request. | +| `connect-failure` | Consul encountered a service mesh failure while routing the request. | +| `envoy-ratelimited` | An Envoy proxy did not complete the request because it was rate limited. | +| `retriable-4xx` | Consul encountered a retriable 4xx HTTP response code while routing the request. | +| `refused-stream` | An upstream service refused the connection while Consul was routing the request. | +| `cancelled` | The request was canceled while Consul was routing it. | +| `deadline-exceeded` | Consul did not receive a response that the request was routed within the configured timeout period. | +| `internal` | Consul encountered an internal error while routing the request. | +| `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | +| `unavailable` | Consul was unavailable to route the request when it was made. | + +### `Routes[].Destination{}.RequestHeaders` + +Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `Add`: Map of one or more key-value pairs. + - `Set`: Map of one or more key-value pairs. + - `Remove`: Map of one or more key-value pairs. + +The following table describes how to configure values for request headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + +### `Routes[].Destination{}.ResponseHeaders` + +Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `Add`: Map of one or more string key-value pairs. + - `Set`: Map of one or more string key-value pairs. + - `Remove`: Map of one or more string key-value pairs. + +The following table describes how to configure values for response headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + + + + + +### `apiVersion` + +Kubernetes-only parameter that specifies the version of the Consul API that the configuration entry maps to Kubernetes configurations. The value must be `consul.hashicorp.com/v1alpha1`. + +### `kind` + +Specifies the type of configuration entry to implement. + +#### Values + +- Default: none +- This field is required. +- Data type: String value that must be set to `serviceRouter`. + +### `metadata.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: Inherits name from the host node +- This field is required. +- Data type: String + + +### `metadata.namespace` + +Specifies the Consul namespace to use for resolving the service. You can map Consul namespaces to Kubernetes Namespaces in different ways. Refer to [Custom Resource Definitions (CRDs) for Consul on Kubernetes](/consul/docs/k8s/crds#consul-enterprise) for additional information. + +#### Values + +- Default: None +- Data type: String + +### `spec` + +Kubernetes-only field that contains all of the configurations for service splitter pods. + +#### Values + +- Default: None +- This field is required. +- Data type: Object containing [`spec.routes`](#spec-routes) configuration + +### `spec.meta` + +Specifies key-value pairs to add to the KV store. + +#### Values + +- Default: none +- Data type: Map of one or more key-value pairs + - keys: String + - values: String, integer, or float + +### `spec.routes` + +Defines the possible routes for L7 requests. Consul evaluates traffic against the list of routes in their order of appearance in the configuration entry. When multiple routes satisfy the request, Consul uses the first route that matches. Traffic that fails to match any of the provided routes is routed to the default service. + +#### Values + +- Default: None +- Data type: List that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | + | `match` | The criteria the configuration entry uses to identify requests. Refer to [`routes[].match`](#spec-routes-match) for additional configuration parameters. | Map | None | + | `destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`routes`](#spec-routes-destination) for additional configuration parameters. | Map | None | + +### `spec.routes[].match` + +Describes a set of criteria that Consul compares incoming L7 traffic with. If empty or omitted, it acts as a catch-all. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `http` | A set of HTTP-specific match criteria. Refer to [`routes[].match{}.http`](#spec-routes-match-http) for additional configuration parameters. | Map | None | + +### `spec.routes[].match.http` + +Specifies a set of HTTP criteria used to evaluate incoming L7 traffic for matches. + +When matching on the HTTP request path, you can only match on one path at a time. Do not configure `pathExact`, `pathPrefix`, and `pathRegex` in a single HTTP map. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP object. | String | None | +| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP object. | String | None | +| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `methods` | Specifies HTTP methods that the match applies to. Refer to [`routes[].match{}.http{}.methods`](#spec-routes-march-http-methods) for additional configuration parameters. | List | None | +| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`routes[].match{}.HTTP{}.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | +| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP object. Refer to [`routes[].match{}.HTTP{}.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | + +### `spec.routes[].match.http.methods` + +Specifies HTTP methods that the match applies to. If not specified, the request matches on all HTTP methods. If provided, the name must be a valid method formatted as a string. + +#### Values + +- Default: None +- Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): + - `GET` + - `HEAD` + - `POST` + - `PUT` + - `DELETE` + - `CONNECT` + - `OPTIONS` + - `TRACE` + - `PATCH` -If a router is not explicitly configured or is configured with no routes then -the system behaves as if a router were configured sending all traffic to a -service of the same name. +### `spec.routes[].match.http.header` -## Requirements +Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. -- Consul [service mesh connect](/consul/docs/connect/configuration) enabled services -- Service to service communication over the protocol `http` +When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, and `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. -## Interaction with other Config Entries +#### Values -- Service router config entries are a component of [L7 Traffic - Management](/consul/docs/connect/l7-traffic). +- Default: None +- Data type: List containing one or more of the following parameters: -- Service router config entries are restricted to only services that define - their protocol as HTTP-based via a corresponding - [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config - entry or globally via - [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) . +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `name` | Specifies the name of the HTTP header to match. This field is required when using [`routes[].match{}.http{}.header`](#spec-routes-match-http-header). | String | None | +| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. | Boolean | `false` | +| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP object. | String | None | +| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP object. | String | None | +| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP object. | String | None | +| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | -- Any route destination that omits the `ServiceSubset` field is eligible for - splitting via a - [`service-splitter`](/consul/docs/connect/config-entries/service-splitter) should - one be configured for that service, otherwise resolution proceeds according - to any configured - [`service-resolver`](/consul/docs/connect/config-entries/service-resolver). +### `spec.routes[].match.http.queryParam` -## UI +Specifies information to match to on HTTP query parameters. When more than one field is configured, all criteria must match for the service routing to apply. -Once a `service-router` is successfully entered, you can view it in the UI. Service routers, service splitters, and service resolvers can all be viewed by clicking on your service then switching to the _routing_ tab. +When using this field, do not configure `present`, `exact`, and `regex` in a single map. You can use only one of these fields at a time when configuring match criteria for HTTP query parameters, as they are mutually exclusive with one another. -![screenshot of service router in the UI](/img/l7-routing/Router.png) +#### Values -## Sample Config Entries +- Default: None +- Data type: List of maps. Each map can contain one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`routes[].match{}.http{}.queryParam`](#spec-routes-match-http-queryparam). | String | None | +| `present` | Specifies that a request matches when the value in the `name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `exact` or `regex` in the same map. | Boolean | `false` | +| `exact` | Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `present` or `regex` in the same map. | String | None | +| `regex` | Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `present` or `exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | + +### `spec.routes[].destination` + +Specifies the target service to route matching requests to, as well as behavior for the request to follow when routed. + +#### Values + +- Default: None +- Data type: Map containing one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `service` | Specifies the name of the service to resolve instead of the default. If empty, the default service name is inherited from the configuration entry’s [`name` field](#name). | String | None | +| `serviceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None | +| `namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | +| `partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None | +| `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`match.http.pathPrefix`](#match-http-pathprefix) or [`match.http.pathExact`](#match-http-pathexact) be configured on this route. | String | None | +| `requestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | +| `idleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | +| `numRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`. | Integer | `1` | +| `retryOnConnectFailure` | Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). | Boolean | `false` | +| `retryOn` | Specifies a list of conditions for Consul to retry requests. Use this field to configure advanced logic for retry attempts. Refer to [`routes[].destination{}.RetryOn[]`](#spec-routes-destination-retryon) for additional configuration parameters. | List | None | +| `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. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). +| `requestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`routes[].destination{}.requestHeaders`](#spec-routes-destination-requestheaders) for additional configuration parameters. | Map | None | +| `responseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`routes[].destination{}.responseHeaders`](#spec-routes-destination-responseheaders) for additional configuration parameters. | Map | None | + +### `spec.routes[].destination.retryOn[]` + +Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +#### Values + +- Default: None +- Data type: List of strings. Strings must match one of the following values: + +| Conditions | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------- | +| `5xx` | Consul encountered a 5xx HTTP response code error code while routing the request. | +| `gateway-error` | Consul encountered a gateway error while routing the request. | +| `reset` | The Consul server was reset while routing the request. | +| `connect-failure` | Consul encountered a service mesh failure while routing the request. | +| `envoy-ratelimited` | An Envoy proxy did not complete the request because it was rate limited. | +| `retriable-4xx` | Consul encountered a retriable 4xx HTTP response code while routing the request. | +| `refused-stream` | An upstream service refused the connection while Consul was routing the request. | +| `cancelled` | The request was canceled while Consul was routing it. | +| `deadline-exceeded` | Consul did not receive a response that the request was routed within the configured timeout period. | +| `internal` | Consul encountered an internal error while routing the request. | +| `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | +| `unavailable` | Consul was unavailable to route the request when it was made. | + +### `spec.routes[].destination.requestHeaders` + +Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `add`: Map of one or more key-value pairs. + - `set`: Map of one or more key-value pairs. + - `remove`: Map of one or more key-value pairs. + +The following table describes how to configure values for request headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + +### `spec.routes[].destination.responseHeaders` + +Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `add`: Map of one or more string key-value pairs. + - `set`: Map of one or more string key-value pairs. + - `remove`: Map of one or more string key-value pairs. + +The following table describes how to configure values for response headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + + + + + +## Examples + +The following examples demonstrate common service router configuration patterns for specific use cases. ### Path prefix matching -Route HTTP requests with a path starting with `/admin` to a different service: +The following example routes HTTP requests with `/admin` at the start of their path to a service named `admin`. @@ -66,7 +891,6 @@ Routes = [ Service = "admin" } }, - # NOTE: a default catch-all will send unmatched traffic to "web" ] ``` @@ -82,7 +906,6 @@ spec: pathPrefix: /admin destination: service: admin - # NOTE: a default catch-all will send unmatched traffic to "web" ``` ```json @@ -106,9 +929,9 @@ spec: -### Header/query parameter matching +### Match a header and query parameter -Route HTTP requests with a special URL parameter or header to a canary subset: +The following example routes HTTP traffic to the `web` service to a subset of `canary` instances when the requests have `x-debug` in either the header or the URL parameter. @@ -148,7 +971,6 @@ Routes = [ ServiceSubset = "canary" } }, - # NOTE: a default catch-all will send unmatched traffic to "web" ] ``` @@ -175,7 +997,6 @@ spec: destination: service: web serviceSubset: canary - # NOTE: a default catch-all will send unmatched traffic to "web" ``` ```json @@ -223,8 +1044,7 @@ spec: ### gRPC routing -Re-route a gRPC method to another service. Since gRPC method calls [are -HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic: +The following example routes gRPC requests to the `invoice-generator`service when they come from an HTTP path that is exact match for `mycompany.BillingService/GenerateInvoice`. Because gRPC method calls use HTTP/2, you can use an HTTP path match rule to re-route traffic. @@ -243,7 +1063,6 @@ Routes = [ Service = "invoice-generator" } }, - # NOTE: a default catch-all will send unmatched traffic to "billing" ] ``` @@ -259,7 +1078,6 @@ spec: pathExact: /mycompany.BillingService/GenerateInvoice destination: service: invoice-generator - # NOTE: a default catch-all will send unmatched traffic to "billing" ``` ```json @@ -285,7 +1103,10 @@ spec: ### Retry logic -Enable retry logic by delegating this responsibility to Consul and the proxy. Review the [`ServiceRouteDestination`](#serviceroutedestination) block for more details. +The following example configures Consul so that when a request for the `orders` service passes through the service mesh, Consul routes the traffic to the `products` service or the `procurement` service based on the HTTP path that originated the request: + +- If it originates from the `/coffees` path, the request routes to the `products` service, times out after 15 seconds, and attempts 5 retries. +- If it originates from the `/orders` path, the request routes to the `procurement` services, times out after 10 seconds, and attempts 3 retries. @@ -295,7 +1116,7 @@ Kind = "service-router" Name = "orders" Routes = [ { - Match{ + Match { HTTP { PathPrefix = "/coffees" } @@ -303,14 +1124,14 @@ Routes = [ Destination { Service = "products" - RequestTimeout = "10s" - NumRetries = 3 + RequestTimeout = "15s" + NumRetries = 5 RetryOnConnectFailure = true RetryOn = ["reset"] } }, { - Match{ + Match { HTTP { PathPrefix = "/orders" } @@ -339,8 +1160,8 @@ spec: pathExact: /coffees destination: service: products - requestTimeout: 10s - numRetries: 3 + requestTimeout: 15s + numRetries: 5 retryOnConnectFailure: true retryOn: ['reset'] - match: @@ -367,8 +1188,8 @@ spec: } }, "Destination": { - "NumRetries": 3, - "RequestTimeout": "10s", + "NumRetries": 5, + "RequestTimeout": "15s", "RetryOnConnectFailure": true, "RetryOn": ["reset"], "Service": "procurement" @@ -392,413 +1213,4 @@ spec: } ``` - - -## Available Fields - -', - yaml: false, - }, - { - name: 'Namespace', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the namespace to which the configuration entry will apply.', - yaml: false, - }, - { - name: 'Partition', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the admin partition to which the configuration will apply.', - yaml: false, - }, - { - name: 'Meta', - type: 'map: nil', - description: - 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.', - yaml: false, - }, - { - name: 'metadata', - children: [ - { - name: 'name', - description: 'Set to the name of the service being configured.', - }, - { - name: 'namespace', - description: - 'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for more details.', - }, - ], - hcl: false, - }, - { - name: 'Routes', - type: 'array', - description: `The list of routes to consider when - processing L7 requests. The first route to match in the list is terminal and - stops further evaluation. Traffic that fails to match any of the provided - routes will be routed to the default service.`, - children: [ - { - name: 'Match', - type: 'ServiceRouteMatch: ', - description: `A set of criteria that can - match incoming L7 requests. If empty or omitted it acts as a catch-all.`, - children: [ - { - name: 'HTTP', - type: 'ServiceRouteHTTPMatch: ', - description: `A set of [HTTP-specific match criteria](#serviceroutehttpmatch).`, - }, - ], - }, - { - name: 'Destination', - type: 'ServiceRouteDestination: ', - description: `Controls [how to proxy](#serviceroutedestination) the matching request(s) to a service.`, - }, - ], - }, - ]} -/> - -### `ServiceRouteHTTPMatch` - -
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Exact path to match on the HTTP request path.

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'PathPrefix', - type: 'string: ""', - description: { - hcl: - 'Path prefix to match on the HTTP request path.

At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Path prefix to match on the HTTP request path.

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'PathRegex', - type: 'string: ""', - description: { - hcl: - 'Regular expression to match on the HTTP request path.

The syntax is [described below](#regular-expression-syntax).

At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Regular expression to match on the HTTP request path.

The syntax is [described below](#regular-expression-syntax).

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'Methods', - type: 'array', - description: - 'A list of HTTP methods for which this match applies. If unspecified all HTTP methods are matched. If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).', - }, - { - name: 'Header', - type: 'array)', - description: - 'A set of criteria that can match on HTTP request headers. If more than one is configured all must match for the overall match to apply.', - children: [ - { - name: 'Name', - type: 'string: ', - description: 'Name of the header to match.', - }, - { - name: 'Present', - type: 'bool: false', - description: { - hcl: - 'Match if the header with the given name is present with any value.

At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the header with the given name is present with any value.

At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Exact', - type: 'string: ""', - description: { - hcl: - 'Match if the header with the given name is this value.

At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the header with the given name is this value.

At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Prefix', - type: 'string: ""', - description: { - hcl: - 'Match if the header with the given name has this prefix.

At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the header with the given name has this prefix.

At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Suffix', - type: 'string: ""', - description: { - hcl: - 'Match if the header with the given name has this suffix.

At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the header with the given name has this suffix.

At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Regex', - type: 'string: ""', - description: { - hcl: - 'Match if the header with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the header with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Invert', - type: 'bool: false', - description: 'Inverts the logic of the match', - }, - ], - }, - { - name: 'QueryParam', - type: 'array)', - description: - 'A set of criteria that can match on HTTP query parameters. If more than one is configured all must match for the overall match to apply.', - children: [ - { - name: 'Name', - type: 'string: ', - description: 'The name of the query parameter to match on.', - }, - { - name: 'Present', - type: 'bool: false', - description: { - hcl: - 'Match if the query parameter with the given name is present with any value.

At most only one of `Exact`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the query parameter with the given name is present with any value.

At most only one of `exact`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Exact', - type: 'string: ""', - description: { - hcl: - 'Match if the query parameter with the given name is this value.

At most only one of `Exact`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the query parameter with the given name is this value.

At most only one of `exact`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Regex', - type: 'string: ""', - description: { - hcl: - 'Match if the query parameter with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `Exact`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the query parameter with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `exact`, `regex`, or `present` may be configured.', - }, - }, - ], - }, - ]} -/> - -### `ServiceRouteDestination` - -
This requires that either `Match.HTTP.PathPrefix` or `Match.HTTP.PathExact` be configured on this route.', - yaml: - 'Defines how to rewrite the HTTP request path before proxying it to its final destination.

This requires that either `match.http.pathPrefix` or `match.http.pathExact` be configured on this route.', - }, - }, - { - name: 'RequestTimeout', - type: 'duration: 0', - description: - 'The total amount of time permitted for the entire downstream request (and retries) to be processed.', - }, - { - name: 'IdleTimeout', - type: 'duration: 0', - description: - 'The total amount of time permitted for the request stream to be idle', - }, - { - name: 'NumRetries', - type: 'int: 1', - description: { - hcl: 'The number of times to retry the request when a retryable result occurs. You cannot set the value to `0`. To disable retries, unset all other retry settings (`RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`)', - yaml: 'The number of times to retry the request when a retryable result occurs. You cannot set the value to `0`. To disable retries, unset all other retry settings (`retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`)', - } - }, - { - name: 'RetryOnConnectFailure', - type: 'bool: false', - description: 'Allows for connection failure errors to trigger a retry.', - }, - { - name: 'RetryOn', - type: 'array', - description: `Allows Consul to retry requests when they meet one of the following sets of conditions: - \`5xx\`, \`gateway-error\`, \`reset\`, \`connect-failure\`, \`envoy-ratelimited\`, \`retriable-4xx\`, - \`refused-stream\`, \`cancelled\`, \`deadline-exceeded\`, \`internal\`, \`resource-exhausted\`, or \`unavailable\``, - }, - { - name: 'RetryOnStatusCodes', - type: 'array', - description: - 'A list of HTTP response status codes that are eligible for retry.', - }, - { - name: 'RequestHeaders', - type: 'HTTPHeaderModifiers: ', - description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers) - that will be applied to requests routed to this service. - This cannot be used with a \`tcp\` listener.`, - }, - { - name: 'ResponseHeaders', - type: 'HTTPHeaderModifiers: ', - description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers) - that will be applied to responses from this service. - This cannot be used with a \`tcp\` listener.`, - }, - ]} -/> - -### `HTTPHeaderModifiers` - -: optional', - description: `The set of key/value pairs that specify header values to add. - Use header names as keys. Header names are _not_ case-sensitive. - If header values with the same name already exist, the value set here will - be appended and both will be present. - If Envoy is used as the proxy, the value may contain - [variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example - \`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request - metadata into the value added.`, - }, - { - name: 'Set', - type: 'map: optional', - description: `The set of key/value pairs that specify header values to add. - Use header names as keys. Header names are _not_ case-sensitive. - If header values with the same name already exist, the value set here will - _replace_ them. - If Envoy is used as the proxy, the value may contain - [variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example - \`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request - metadata into the value added.`, - }, - { - name: 'Remove', - type: 'array: optional', - description: `The set of header names to remove. Only headers - whose names are a case-insensitive exact match will be removed`, - }, - ]} -/> - -## ACLs - -Configuration entries may be protected by [ACLs](/consul/docs/security/acl). - -Reading a `service-router` config entry requires `service:read` on the resource. - -Creating, updating, or deleting a `service-router` config entry requires -`service:write` on the resource and `service:read` on any other service referenced by -name in these fields: - -- [`Routes[].Destination.Service`](#service) - -## Regular Expression Syntax - -The actual syntax of the regular expression fields described here is entirely -proxy-specific. - -When using [Envoy](/consul/docs/connect/proxies/envoy) as a proxy (the only supported proxy in Kubernetes), -the syntax for these fields is version specific: - -| Envoy Version | Syntax | -| --------------- | ------------------------------------------------------------------- | -| 1.11.2 or newer | [documentation](https://github.com/google/re2/wiki/Syntax) | -| 1.11.1 or older | [documentation](https://en.cppreference.com/w/cpp/regex/ecmascript) | + \ No newline at end of file From dae246fd323ee98fbb824503c806d27a21382293 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 08:53:46 -0700 Subject: [PATCH 05/25] link fixes + tab fixes --- .../connect/config-entries/service-router.mdx | 85 ++++++++++++++----- 1 file changed, 62 insertions(+), 23 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index ca8506a71ad0..e434627d1867 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -128,7 +128,7 @@ When every field is defined, a service router configuration entry has the follow ```hcl Kind = "service-router" ## required -Name = "" ## required +Name = "" ## required Namespace = "" Partition = "" Meta = { @@ -259,7 +259,7 @@ Routes = [ "ServiceSubset": "", "Namespace": "", "Partition": "", - "PrefixRewrite": "", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact + "PrefixRewrite": "", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact "RequestTimeout": 0, "IdleTimeout": 0, "NumRetries": 1, @@ -413,7 +413,7 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | | `Match` | The criteria the configuration entry uses to identify requests. Refer to [`Routes[].Match`](#routes-match) for additional configuration parameters. | Map | None | - | `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes`](#routes-destination) for additional configuration parameters. | Map | None | + | `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes.Destination`](#routes-destination) for additional configuration parameters. | Map | None | ### `Routes[].Match` @@ -672,8 +672,8 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | - | `match` | The criteria the configuration entry uses to identify requests. Refer to [`routes[].match`](#spec-routes-match) for additional configuration parameters. | Map | None | - | `destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`routes`](#spec-routes-destination) for additional configuration parameters. | Map | None | + | `match` | The criteria the configuration entry uses to identify requests. Refer to [`spec.routes[].match`](#spec-routes-match) for additional configuration parameters. | Map | None | + | `destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`spec.routes[].destination`](#spec-routes-destination) for additional configuration parameters. | Map | None | ### `spec.routes[].match` @@ -686,7 +686,7 @@ Describes a set of criteria that Consul compares incoming L7 traffic with. If em | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `http` | A set of HTTP-specific match criteria. Refer to [`routes[].match{}.http`](#spec-routes-match-http) for additional configuration parameters. | Map | None | +| `http` | A set of HTTP-specific match criteria. Refer to [`spec.routes[].match.http`](#spec-routes-match-http) for additional configuration parameters. | Map | None | ### `spec.routes[].match.http` @@ -704,9 +704,9 @@ When matching on the HTTP request path, you can only match on one path at a time | `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP object. | String | None | | `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP object. | String | None | | `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | -| `methods` | Specifies HTTP methods that the match applies to. Refer to [`routes[].match{}.http{}.methods`](#spec-routes-march-http-methods) for additional configuration parameters. | List | None | -| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`routes[].match{}.HTTP{}.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | -| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP object. Refer to [`routes[].match{}.HTTP{}.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | +| `methods` | Specifies HTTP methods that the match applies to. Refer to [`spec.routes[].match.http.methods`](#spec-routes-match-http-methods) for additional configuration parameters. | List | None | +| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | +| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP object. Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | ### `spec.routes[].match.http.methods` @@ -739,7 +739,7 @@ When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `name` | Specifies the name of the HTTP header to match. This field is required when using [`routes[].match{}.http{}.header`](#spec-routes-match-http-header). | String | None | +| `name` | Specifies the name of the HTTP header to match. This field is required when using [`spec.routes[].match.http.header`](#spec-routes-match-http-header). | String | None | | `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. | Boolean | `false` | | `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP object. | String | None | | `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP object. | String | None | @@ -760,7 +760,7 @@ When using this field, do not configure `present`, `exact`, and `regex` in a sin | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`routes[].match{}.http{}.queryParam`](#spec-routes-match-http-queryparam). | String | None | +| `name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`spec.routes[].match.http.queryParam`](#spec-routes-match-http-queryparam). | String | None | | `present` | Specifies that a request matches when the value in the `name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `exact` or `regex` in the same map. | Boolean | `false` | | `exact` | Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `present` or `regex` in the same map. | String | None | | `regex` | Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `present` or `exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | @@ -780,15 +780,15 @@ Specifies the target service to route matching requests to, as well as behavior | `serviceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None | | `namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | | `partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None | -| `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`match.http.pathPrefix`](#match-http-pathprefix) or [`match.http.pathExact`](#match-http-pathexact) be configured on this route. | String | None | +| `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`spec.routes[].match.http.pathPrefix`](#spec-routes-match-http-pathprefix) or [`spec.routes[].match.http.pathExact`](#spec-routes-match-http-pathexact) be configured on this route. | String | None | | `requestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | | `idleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | | `numRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`. | Integer | `1` | | `retryOnConnectFailure` | Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). | Boolean | `false` | | `retryOn` | Specifies a list of conditions for Consul to retry requests. Use this field to configure advanced logic for retry attempts. Refer to [`routes[].destination{}.RetryOn[]`](#spec-routes-destination-retryon) for additional configuration parameters. | List | None | | `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. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). -| `requestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`routes[].destination{}.requestHeaders`](#spec-routes-destination-requestheaders) for additional configuration parameters. | Map | None | -| `responseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`routes[].destination{}.responseHeaders`](#spec-routes-destination-responseheaders) for additional configuration parameters. | Map | None | +| `requestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`spec.routes[].destination.requestHeaders`](#spec-routes-destination-requestheaders) for additional configuration parameters. | Map | None | +| `responseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`spec.routes[].destination.responseHeaders`](#spec-routes-destination-responseheaders) for additional configuration parameters. | Map | None | ### `spec.routes[].destination.retryOn[]` @@ -874,7 +874,8 @@ The following examples demonstrate common service router configuration patterns The following example routes HTTP requests with `/admin` at the start of their path to a service named `admin`. - + + ```hcl Kind = "service-router" @@ -894,6 +895,10 @@ Routes = [ ] ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -908,6 +913,10 @@ spec: service: admin ``` + + + + ```json { "Kind": "service-router", @@ -927,13 +936,15 @@ spec: } ``` - + + ### Match a header and query parameter The following example routes HTTP traffic to the `web` service to a subset of `canary` instances when the requests have `x-debug` in either the header or the URL parameter. - + + ```hcl Kind = "service-router" @@ -974,6 +985,10 @@ Routes = [ ] ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -999,6 +1014,10 @@ spec: serviceSubset: canary ``` + + + + ```json { "Kind": "service-router", @@ -1040,13 +1059,15 @@ spec: } ``` - + + ### gRPC routing The following example routes gRPC requests to the `invoice-generator`service when they come from an HTTP path that is exact match for `mycompany.BillingService/GenerateInvoice`. Because gRPC method calls use HTTP/2, you can use an HTTP path match rule to re-route traffic. - + + ```hcl Kind = "service-router" @@ -1066,6 +1087,10 @@ Routes = [ ] ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -1080,6 +1105,10 @@ spec: service: invoice-generator ``` + + + + ```json { "Kind": "service-router", @@ -1099,7 +1128,8 @@ spec: } ``` - + + ### Retry logic @@ -1108,8 +1138,8 @@ The following example configures Consul so that when a request for the `orders` - If it originates from the `/coffees` path, the request routes to the `products` service, times out after 15 seconds, and attempts 5 retries. - If it originates from the `/orders` path, the request routes to the `procurement` services, times out after 10 seconds, and attempts 3 retries. - - + + ```hcl Kind = "service-router" @@ -1148,6 +1178,10 @@ Routes = [ ] ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter @@ -1175,6 +1209,9 @@ spec: retryOn: ['reset'] ``` + + + ```json { @@ -1213,4 +1250,6 @@ spec: } ``` - \ No newline at end of file + + + \ No newline at end of file From 3f5c1461b82e1a76022e68e9734fedb5fd82f2c8 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 08:57:43 -0700 Subject: [PATCH 06/25] link and tab fixes --- .../config-entries/service-resolver.mdx | 100 +++++++++++++++--- .../connect/config-entries/service-router.mdx | 2 +- 2 files changed, 85 insertions(+), 17 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 999441082ea9..9bf69351f76a 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -882,7 +882,8 @@ The following examples demonstrate common service resolver configuration pattern The following example creates service subsets based on version metadata: - + + ```hcl Kind = "service-resolver" @@ -898,6 +899,10 @@ Subsets = { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -912,6 +917,10 @@ spec: filter: 'Service.Meta.version == v2' ``` + + + + ```json { "Kind": "service-resolver", @@ -928,13 +937,15 @@ spec: } ``` - + + ### Resolve virtual upstreams The folowing example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service: - + + ```hcl Kind = "service-resolver" @@ -945,6 +956,10 @@ Redirect { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -956,6 +971,10 @@ spec: datacenter: dc2 ``` + + + + ```json { "Kind": "service-resolver", @@ -967,13 +986,15 @@ spec: } ``` - + + ### Failover The following example enables failover for subset `v2` to `dc2`. All other subsets attempt failover to `dc3`, and when it is not available, to `dc4`: - + + ```hcl Kind = "service-resolver" @@ -989,6 +1010,10 @@ Failover = { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -1003,6 +1028,10 @@ spec: datacenters: ['dc3', 'dc4'] ``` + + + + ```json { "Kind": "service-resolver", @@ -1019,13 +1048,15 @@ spec: } ``` - + + #### Failover targets for federation and cluster peering The following example enables failover to target a WAN federated datacenter for all service subsets. If the connection to `dc3` times out after 15 seconds, the service failover targets the peer with the establish cluster peering connection instead. - + + ```hcl Kind = "service-resolver" @@ -1041,6 +1072,10 @@ Failover = { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -1055,6 +1090,10 @@ spec: - peer: "peer-01" ``` + + + + ```json { "Kind": "service-resolver", @@ -1071,13 +1110,15 @@ spec: } ``` - + + #### Failover for all service subsets The following example enables failover to the `secondary` namespace in another datacenter for all service subsets. - + + ```hcl Kind = "service-resolver" @@ -1092,6 +1133,10 @@ Failover = { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -1105,6 +1150,10 @@ spec: datacenters: ['dc2'] ``` + + + + ```json { "Kind": "service-resolver", @@ -1120,15 +1169,15 @@ spec: } ``` - - + + #### Failover to a namespace The following example enables failover to a different namespace in the same datacenter. - - + + ```hcl Kind = "service-resolver" @@ -1143,6 +1192,10 @@ Failover = { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -1156,6 +1209,10 @@ spec: namespace: 'secondary' ``` + + + + ```json { "Kind": "service-resolver", @@ -1171,13 +1228,15 @@ spec: } ``` - + + ### Consistent load balancing The following example applies a Maglev load balancing policy for requests with an `x-user-id` header: - + + ```hcl Kind = "service-resolver" @@ -1194,6 +1253,10 @@ LoadBalancer = { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceResolver @@ -1207,6 +1270,10 @@ spec: fieldValue: x-user-id ``` + + + + ```json { "Kind": "service-resolver", @@ -1223,4 +1290,5 @@ spec: } ``` - + + diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index e434627d1867..903f6ce5010e 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -444,7 +444,7 @@ When matching on the HTTP request path, you can only match on one path at a time | `PathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same HTTP object. | String | None | | `PathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathRegex` in the same HTTP object. | String | None | | `PathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | -| `Methods` | Specifies HTTP methods that the match applies to. Refer to [`Routes[].Match{}.HTTP{}.Methods`](#routes-march-http-methods) for additional configuration parameters. | List | None | +| `Methods` | Specifies HTTP methods that the match applies to. Refer to [`Routes[].Match{}.HTTP{}.Methods`](#routes-match-http-methods) for additional configuration parameters. | List | None | | `Header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header) for additional configuration parameters. | List | None | | `QueryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `Present`, `Exact`, or `Regex` in the same HTTP object. Refer to [`Routes[].Match{}.HTTP{}.QueryParam](#routes-match-http-queryparam) for additional configuration parameters. | List | None | From 687caaef8c8ecdeac4802f0444eda7f03abd3d89 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 09:22:04 -0700 Subject: [PATCH 07/25] link fixes --- .../config-entries/service-resolver.mdx | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 9bf69351f76a..0d849ae9ece0 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -112,7 +112,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`field`](#spec-loadbalancer-hashpolicies-field): string - [`fieldValue`](#spec-loadbalancer-hashpolicies-fieldvalue): string - [`cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig): map - - [`session`](spec-#loadbalancer-hashpolicies-cookieconfig-session): boolean | `false` + - [`session`](#spec-loadbalancer-hashpolicies-cookieconfig-session): boolean | `false` - [`ttl`](#spec-loadbalancer-hashpolicies-cookieconfig-ttl): string | `0s` - [`path`](#spec-loadbalancer-hashpolicies-cookieconfig-path): string - [`sourceIP`](#spec-loadbalancer-hashpolicies-sourceip): boolean | `false` @@ -784,10 +784,10 @@ Specifies the load balancing policy and configuration for services issuing reque | Parameter | Description | Data type | Default | | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | - | `policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`spec.loadBalancer{}.policy`](#spec-loadbalancer-policy) for additional configuration parameters. | Map | None | - | `leastRequestConfig` | Specifies configuration for the `least_request policy` type. Refer to [`spec.loadBalancer{}.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig) for additional configuration parameters. | Map | None | - | `ringHashConfig` | Specifies configuration for the `ring_hash` policy type. Refer to [`spec.loadBalancer{}.ringHashConfig`](#spec-loadbalancer-ringhashconfig) for additional configuration parameters. | Map | None | - | `hashPolicies` | Specifies a list of hash policies to use for hashing load balancing algorithms. Refer to [`spec.loadBalancer{}.hashPolicies`](#spec-loadbalancer-hashpolicies) for additional configuration parameters. | Map | None | + | `policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`spec.loadBalancer.policy`](#spec-loadbalancer-policy) for additional configuration parameters. | Map | None | + | `leastRequestConfig` | Specifies configuration for the `least_request policy` type. Refer to [`spec.loadBalancer.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig) for additional configuration parameters. | Map | None | + | `ringHashConfig` | Specifies configuration for the `ring_hash` policy type. Refer to [`spec.loadBalancer.ringHashConfig`](#spec-loadbalancer-ringhashconfig) for additional configuration parameters. | Map | None | + | `hashPolicies` | Specifies a list of hash policies to use for hashing load balancing algorithms. Refer to [`spec.loadBalancer.hashPolicies`](#spec-loadbalancer-hashpolicies) for additional configuration parameters. | Map | None | ### `spec.loadBalancer.policy` @@ -808,9 +808,9 @@ Specifies the type of load balancing policy for selecting a host. Supported load | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | | `round_robin` | The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. | - | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`spec.loadBalancer{}.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig). | - | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer{}.ringHashConfig`](#spec-loadbalancer-ringhashconfig). | - | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer{}.hashPolicies`](#spec-loadbalancer-hashpolicies). | + | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`spec.loadBalancer.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig). | + | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.ringHashConfig`](#spec-loadbalancer-ringhashconfig). | + | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.hashPolicies`](#spec-loadbalancer-hashpolicies). | ### `spec.loadBalancer.leastRequestConfig` @@ -852,9 +852,9 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. | :------------- | :------------------------------------------------------------- | --------- | ------- | | `field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `field` parameter if `sourceIP` is also configured. | String | None | | `fieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `fieldValue` parameter if `sourceIP` is also configured. | String | None | - | `cookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`spec.loadBalancer{}.hashPolicies[].cookieConfig`](spec-loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | + | `cookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`spec.loadBalancer.hashPolicies[].cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | | `sourceIP` | Determines if the hash type should besource IP address. You cannot specify `sourceIP` if `field` or `fieldValue` are configured. | Boolean | `false` | - | `Terminal` | Determines if Consul should short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + | `terminal` | Determines if Consul should short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | ### `spec.loadBalancer{}.hashPolicies[].cookieConfig` From c5f70ea00cfffc7e6520e727ceca3158f44e02f0 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 12:13:24 -0700 Subject: [PATCH 08/25] service resolver improvements --- .../config-entries/service-resolver.mdx | 47 +++++++++---------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 0d849ae9ece0..94b4a534a8aa 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -7,7 +7,7 @@ description: >- # Service Resolver Configuration Reference -This page provides reference information for service resolver configuration entries. Configure and apply service resolvers to create named subsets of service instances and their behavior when satisfying upstream requests. +This page provides reference information for service resolver configuration entries. Configure and apply service resolvers to create named subsets of service instances and define their behavior when satisfying upstream requests. Refer to [L7 traffic management overview](/consul/docs/connect/l7-traffic) for additional information. @@ -142,11 +142,11 @@ ConnectTimeout = "10s" RequestTimeout = "15s" Subsets = { = { - Filter = "" + Filter = "" OnlyPassing = true } = { - Filter = "" + Filter = "" OnlyPassing = true } } @@ -224,11 +224,11 @@ LoadBalancer = { "RequestTimeout":"15s", "Subsets":{ "":{ - "Filter":"", + "Filter":"":{ - "Filter":"", + "Filter":"", "OnlyPassing":true } }, @@ -303,10 +303,10 @@ spec: requestTimeout: 15s subsets: : - filter: + filter: onlyPassing: false : - filter: + filter: onlyPassing: false defaultSubset: redirect: @@ -428,14 +428,14 @@ Specifies the timeout duration for receiving an HTTP response from this service, ### `Subsets` -Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a filtering expression. If empty, only the unnamed default subset is usable. +Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If empty, only the unnamed default subset is usable. #### Values - Default: None - Data type: Map containing a key/value pair. - ``: String that names the subset. The string must be valid as a DNS subdomain element. - - ``: Map that can contain the following fields: + - ``: Map that can contain the following parameters: | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | @@ -458,12 +458,12 @@ Specifies redirect instructions for local service traffic so that services deplo #### Values - Default: None -- Data type: Map that can contain the following paramters: +- Data type: Map that can contain the following parameters: | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `Service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | - | `ServiceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `Redirect` map: `Service`, `Namespace`, `Datacenter` | String | None | + | `ServiceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `Redirect` map: `Service`, `Namespace`, and`Datacenter`. | String | None | | `Namespace` | Specifies the namespace at the redirect’s destination that resolves local upstream requests. | String | None | | `Partition` | Specifies the admin partition at the redirect’s destination that resolves local upstream requests. | String | None | | `Datacenter` | Specifies the datacenter at the redirect’s destination that resolves local upstream requests. | String | None | @@ -473,7 +473,7 @@ Specifies redirect instructions for local service traffic so that services deplo Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. -This map is keyed by the name of the local service subset whose traffic should redirect when it fails. The `"*"` wildcard can be used to apply failovers to any subset. +This map is keyed by the name of the local service subset whose traffic should resolve elsewhere when it fails. The `"*"` wildcard can be used to apply failovers to any subset. `Service`, `ServiceSubset`, `Namespace`, `Targets`, and `Datacenters` cannot all be empty at the same time. @@ -485,7 +485,7 @@ This map is keyed by the name of the local service subset whose traffic should r | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `Service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | - | `ServiceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`DefaultSubset](#defaultsubset). | String | None | + | `ServiceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`DefaultSubset`](#defaultsubset). | String | None | | `Namespace` | Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. | String | None | | `Datacenters` | Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. | String | None | | `Targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`Failover{}.Targets`](#failover-targets) for configuration details. | List | None | @@ -556,7 +556,7 @@ Specifies configuration for the `least_request policy` type. #### Values - Default: None -- Data type: Map containing the following object: +- Data type: Map containing the following parameter: | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | @@ -569,7 +569,7 @@ Specifies configuration for the `ring_hash` policy type. #### Values - Default: None -- Data type: List that can contain the following maps: +- Data type: List that can contain the following parameters: | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------- | --------- | ------- | @@ -690,7 +690,7 @@ Specifies the timeout duration for receiving an HTTP response from this service, ### `spec.subsets` -Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a filtering expression. If empty, only the unnamed default subset is usable. +Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If empty, only the unnamed default subset is usable. #### Values @@ -725,7 +725,7 @@ Specifies redirect instructions for local service traffic so that services deplo | Parameter | Description | Data type | Default | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | | `service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | - | `serviceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `redirect` map: `service`, `namespace`, `datacenter` | String | None | + | `serviceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `redirect` map: `service`, `namespace`, and `datacenter`. | String | None | | `namespace` | Specifies the namespace at the redirect’s destination that resolves local upstream requests. | String | None | | `partition` | Specifies the admin partition at the redirect’s destination that resolves local upstream requests. | String | None | | `datacenter` | Specifies the datacenter at the redirect’s destination that resolves local upstream requests. | String | None | @@ -737,12 +737,11 @@ Specifies controls for rerouting traffic to an alternate pool of service instanc This map is keyed by the name of the local service subset whose traffic should redirect when it fails. The `"*"` wildcard can be used to apply failovers to any subset. -`service`, `serviceSubset`, `namespace`, `targets`, and `Datacenters` cannot all be empty at the same time. +`service`, `serviceSubset`, `namespace`, `targets`, and `datacenters` cannot all be empty at the same time. #### Values - Default: None -- Data type: Map that can contain the following objects: - Data type: Map that can contain the following parameters: | Parameter | Description | Data type | Default | @@ -751,7 +750,7 @@ This map is keyed by the name of the local service subset whose traffic should r | `serviceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`defaultSubset](#spec-defaultsubset). | String | None | | `namespace` | Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. | String | None | | `datacenters` | Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. | String | None | - | `targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`spec-failover{}.targets`](#spec-failover-targets) for configuration details. | List | None | + | `targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`spec-failover.targets`](#spec-failover-targets) for configuration details. | List | None | ### `spec.failover.targets` @@ -814,7 +813,7 @@ Specifies the type of load balancing policy for selecting a host. Supported load ### `spec.loadBalancer.leastRequestConfig` -Specifies configuration for the `least_request policy` type. +Specifies configuration for the `least_request` policy type. #### Values @@ -876,11 +875,11 @@ Specifies additional configuration options for the `cookie` hash policy type. Th ## Examples -The following examples demonstrate common service resolver configuration patterns for specific use cases. +The following examples demonstrate common service resolver configuration patterns for specific use cases. ### Filter on service version -The following example creates service subsets based on version metadata: +The following example creates two subsets of the `web` service, and assigns service instances to subsets based on each instance's version metadata. It also defined `v1` as the default subset. @@ -942,7 +941,7 @@ spec: ### Resolve virtual upstreams -The folowing example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service: +The folowing example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service. From c97dd4654f2e5914a5d4917d29f2f5340db0a39f Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 13:08:27 -0700 Subject: [PATCH 09/25] hierarchy fixes --- .../connect/config-entries/service-router.mdx | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 903f6ce5010e..e14539a34ba0 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -47,23 +47,23 @@ The following list outlines field hierarchy, language-specific data types, and r - [`Destination`](#routes-destination): map - [`Service`](#routes-destination-service): string - [`ServiceSubset`](#routes-destination-servicesubset): string -- [`Namespace`](#routes-destination-namespace): string -- [`Partition`](#routes-destination-partition): string -- [`PrefixRewrite`](#routes-destination-prefixrewrite): string -- [`RequestTimeout`](#routes-destination-requesttimeout): integer | `0` -- [`IdleTimeout`](#routes-destination-idletimeout): integer | `0` -- [`NumRetries`](#routes-destination-numretries): integer | `1` -- [`RetryOnConnectFailure`](#routes-destination-retryonconnectfailure): boolean | `false` -- [`RetryOn`](#routes-destination-retryon): list -- [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes): list -- [`RequestHeaders`](#routes-destination-requestheaders): map - - [`Add`](#routes-destination-requestheaders): map - - [`Set`](#routes-destination-requestheaders): map - - [`Remove`](#routes-destination-requestheaders): map -- [`ResponseHeaders`](#routes-destination-responseheaders): map - - [`Add`](#routes-destination-responseheaders): map - - [`Set`](#routes-destination-responseheaders): map - - [`Remove`](#routes-destination-responseheaders): map + - [`Namespace`](#routes-destination-namespace): string + - [`Partition`](#routes-destination-partition): string + - [`PrefixRewrite`](#routes-destination-prefixrewrite): string + - [`RequestTimeout`](#routes-destination-requesttimeout): integer | `0` + - [`IdleTimeout`](#routes-destination-idletimeout): integer | `0` + - [`NumRetries`](#routes-destination-numretries): integer | `1` + - [`RetryOnConnectFailure`](#routes-destination-retryonconnectfailure): boolean | `false` + - [`RetryOn`](#routes-destination-retryon): list + - [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes): list + - [`RequestHeaders`](#routes-destination-requestheaders): map + - [`Add`](#routes-destination-requestheaders): map + - [`Set`](#routes-destination-requestheaders): map + - [`Remove`](#routes-destination-requestheaders): map + - [`ResponseHeaders`](#routes-destination-responseheaders): map + - [`Add`](#routes-destination-responseheaders): map + - [`Set`](#routes-destination-responseheaders): map + - [`Remove`](#routes-destination-responseheaders): map From ce0d195436bfca674312188f114224852377c1c9 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 13:10:47 -0700 Subject: [PATCH 10/25] spacing --- .../connect/config-entries/service-router.mdx | 174 +++++++++--------- 1 file changed, 87 insertions(+), 87 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index e14539a34ba0..f264878d77a1 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -25,28 +25,28 @@ The following list outlines field hierarchy, language-specific data types, and r - [`Partition`](#partition): string | `default` - [`Meta`](#meta): map - [`Routes`](#routes): list - - [`Match`](#routes-match): map - - [‘HTTP`](#routes-match-http): map - - [`PathExact`](#routes-match-http-pathexact): string - - [`PathPrefix`](#routes-match-http-pathprefix): string - - [`PathRegex`](#routes-match-http-pathregex): string - - [`Methods`](#routes-match-http-methods): list - - [`Header`](#routes-match-http-header): list - - [`Name`](#routes-match-http-header-name): string - - [`Present`](#routes-match-http-header-present): boolean | `false` - - [`Exact`](#routes-match-http-header-exact): string - - [`Prefix`](#routes-match-http-header-prefix): string - - [`Suffix`](#routes-match-http-header-suffix): string - - [`Regex`](#routes-match-http-header-regex): string - - [`Invert`](#routes-match-http-header-invert): boolean | `false` - - [`QueryParam`](#routes-match-http-queryparam): list - - [`Name`](#routes-match-http-queryparam-name): string - - [`Present`](#routes-match-http-queryparam-present): boolean | `false` - - [`Exact`](#routes-match-http-queryparam-exact): string - - [`Regex`](#routes-match-http-queryparam-regex): string - - [`Destination`](#routes-destination): map - - [`Service`](#routes-destination-service): string - - [`ServiceSubset`](#routes-destination-servicesubset): string + - [`Match`](#routes-match): map + - [‘HTTP`](#routes-match-http): map + - [`PathExact`](#routes-match-http-pathexact): string + - [`PathPrefix`](#routes-match-http-pathprefix): string + - [`PathRegex`](#routes-match-http-pathregex): string + - [`Methods`](#routes-match-http-methods): list + - [`Header`](#routes-match-http-header): list + - [`Name`](#routes-match-http-header-name): string + - [`Present`](#routes-match-http-header-present): boolean | `false` + - [`Exact`](#routes-match-http-header-exact): string + - [`Prefix`](#routes-match-http-header-prefix): string + - [`Suffix`](#routes-match-http-header-suffix): string + - [`Regex`](#routes-match-http-header-regex): string + - [`Invert`](#routes-match-http-header-invert): boolean | `false` + - [`QueryParam`](#routes-match-http-queryparam): list + - [`Name`](#routes-match-http-queryparam-name): string + - [`Present`](#routes-match-http-queryparam-present): boolean | `false` + - [`Exact`](#routes-match-http-queryparam-exact): string + - [`Regex`](#routes-match-http-queryparam-regex): string + - [`Destination`](#routes-destination): map + - [`Service`](#routes-destination-service): string + - [`ServiceSubset`](#routes-destination-servicesubset): string - [`Namespace`](#routes-destination-namespace): string - [`Partition`](#routes-destination-partition): string - [`PrefixRewrite`](#routes-destination-prefixrewrite): string @@ -57,13 +57,13 @@ The following list outlines field hierarchy, language-specific data types, and r - [`RetryOn`](#routes-destination-retryon): list - [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes): list - [`RequestHeaders`](#routes-destination-requestheaders): map - - [`Add`](#routes-destination-requestheaders): map - - [`Set`](#routes-destination-requestheaders): map - - [`Remove`](#routes-destination-requestheaders): map + - [`Add`](#routes-destination-requestheaders): map + - [`Set`](#routes-destination-requestheaders): map + - [`Remove`](#routes-destination-requestheaders): map - [`ResponseHeaders`](#routes-destination-responseheaders): map - - [`Add`](#routes-destination-responseheaders): map - - [`Set`](#routes-destination-responseheaders): map - - [`Remove`](#routes-destination-responseheaders): map + - [`Add`](#routes-destination-responseheaders): map + - [`Set`](#routes-destination-responseheaders): map + - [`Remove`](#routes-destination-responseheaders): map @@ -75,45 +75,45 @@ The following list outlines field hierarchy, language-specific data types, and r - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional - [`spec`](#spec): map | required - - [`routes`](#spec-routes): list - - [`match`](#spec-routes-match): map - - [‘http`](#spec-routes-match-http): map - - [`pathExact`](#spec-routes-match-http-pathexact): string - - [`pathPrefix`](#spec-routes-match-http-pathprefix): string - - [`pathRegex`](#spec-routes-match-http-pathregex): string - - [`methods`](#spec-routes-match-http-methods): list - - [`header`](#spec-routes-match-http-header): list - - [`name`](#spec-routes-match-http-header-name): string - - [`present`](#spec-routes-match-http-header-present): boolean | `false` - - [`exact`](#spec-routes-match-http-header-exact): string - - [`prefix`](#spec-routes-match-http-header-prefix): string - - [`suffix`](#spec-routes-match-http-header-suffix): string - - [`regex`](#spec-routes-match-http-header-regex): string - - [`invert`](#spec-routes-match-http-header-invert): boolean - - [`queryParam`](#spec-routes-match-http-queryparam): list - - [`name`](#spec-routes-match-http-queryparam-name): string - - [`present`](#spec-routes-match-http-queryparam-present): boolean | `false` - - [`regex`](#spec-routes-match-http-queryparam-regex): string - - [`destination`](#spec-routes-destination): map - - [`service`](#spec-routes-destination-service): string - - [`serviceSubset`](#spec-routes-destination-servicesubset): string - - [`namespace`](#spec-routes-destination-namespace): string - - [`partition`](#spec-routes-destination-partition): string - - [`prefixRewrite`](#spec-routes-destination-prefixrewrite): string - - [`requestTimeout`](#spec-routes-destination-requesttimeout): integer | `0` - - [`numRetries`](#spec-routes-destination-numretries): integer | `0` - - [`numRetries`](#spec-routes-destination-numretries): integer | `1` - - [`retryOnConnectFailure`](#spec-routes-destination-retryonconnectfailure): boolean | `false` - - [`retryOn`](#spec-routes-destination-retryon): list - - [`retryOnStatusCodes`](#spec-routes-destination-retryonstatuscodes): list - - [`requestHeaders`](#spec-routes-destination-requestheaders): map - - [`add`](#spec-routes-destination-requestheaders): map - - [`set`](#spec-routes-destination-requestheaders): map - - [`remove`](#spec-routes-destination-requestheaders): map - - [`responseHeaders`](#spec-routes-destination-responseheaders): map - - [`add`](#spec-routes-destination-responseheaders): map - - [`set`](#spec-routes-destination-responseheaders): map - - [`remove`](#spec-routes-destination-responseheaders): map + - [`routes`](#spec-routes): list + - [`match`](#spec-routes-match): map + - [‘http`](#spec-routes-match-http): map + - [`pathExact`](#spec-routes-match-http-pathexact): string + - [`pathPrefix`](#spec-routes-match-http-pathprefix): string + - [`pathRegex`](#spec-routes-match-http-pathregex): string + - [`methods`](#spec-routes-match-http-methods): list + - [`header`](#spec-routes-match-http-header): list + - [`name`](#spec-routes-match-http-header-name): string + - [`present`](#spec-routes-match-http-header-present): boolean | `false` + - [`exact`](#spec-routes-match-http-header-exact): string + - [`prefix`](#spec-routes-match-http-header-prefix): string + - [`suffix`](#spec-routes-match-http-header-suffix): string + - [`regex`](#spec-routes-match-http-header-regex): string + - [`invert`](#spec-routes-match-http-header-invert): boolean + - [`queryParam`](#spec-routes-match-http-queryparam): list + - [`name`](#spec-routes-match-http-queryparam-name): string + - [`present`](#spec-routes-match-http-queryparam-present): boolean | `false` + - [`regex`](#spec-routes-match-http-queryparam-regex): string + - [`destination`](#spec-routes-destination): map + - [`service`](#spec-routes-destination-service): string + - [`serviceSubset`](#spec-routes-destination-servicesubset): string + - [`namespace`](#spec-routes-destination-namespace): string + - [`partition`](#spec-routes-destination-partition): string + - [`prefixRewrite`](#spec-routes-destination-prefixrewrite): string + - [`requestTimeout`](#spec-routes-destination-requesttimeout): integer | `0` + - [`numRetries`](#spec-routes-destination-numretries): integer | `0` + - [`numRetries`](#spec-routes-destination-numretries): integer | `1` + - [`retryOnConnectFailure`](#spec-routes-destination-retryonconnectfailure): boolean | `false` + - [`retryOn`](#spec-routes-destination-retryon): list + - [`retryOnStatusCodes`](#spec-routes-destination-retryonstatuscodes): list + - [`requestHeaders`](#spec-routes-destination-requestheaders): map + - [`add`](#spec-routes-destination-requestheaders): map + - [`set`](#spec-routes-destination-requestheaders): map + - [`remove`](#spec-routes-destination-requestheaders): map + - [`responseHeaders`](#spec-routes-destination-responseheaders): map + - [`add`](#spec-routes-destination-responseheaders): map + - [`set`](#spec-routes-destination-responseheaders): map + - [`remove`](#spec-routes-destination-responseheaders): map @@ -456,15 +456,15 @@ Specifies HTTP methods that the match applies to. If not specified, the request - Default: None - Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): - - `GET` - - `HEAD` - - `POST` - - `PUT` - - `DELETE` - - `CONNECT` - - `OPTIONS` - - `TRACE` - - `PATCH` + - `GET` + - `HEAD` + - `POST` + - `PUT` + - `DELETE` + - `CONNECT` + - `OPTIONS` + - `TRACE` + - `PATCH` ### `Routes[].Match{}.HTTP{}.Header` @@ -569,7 +569,7 @@ Specifies a set of HTTP-specific header modification rules applied to requests r The following table describes how to configure values for request headers: | Rule | Description | Type | -| --- | --- | --- | +| --- | --- | --- | | `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | @@ -593,7 +593,7 @@ Specifies a set of HTTP-specific header modification rules applied to responses The following table describes how to configure values for response headers: | Rule | Description | Type | -| --- | --- | --- | +| --- | --- | --- | | `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | @@ -716,15 +716,15 @@ Specifies HTTP methods that the match applies to. If not specified, the request - Default: None - Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): - - `GET` - - `HEAD` - - `POST` - - `PUT` - - `DELETE` - - `CONNECT` - - `OPTIONS` - - `TRACE` - - `PATCH` + - `GET` + - `HEAD` + - `POST` + - `PUT` + - `DELETE` + - `CONNECT` + - `OPTIONS` + - `TRACE` + - `PATCH` ### `spec.routes[].match.http.header` From 0ce7bb019e820effa7ce294a4dc229a83ca0ae09 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 13:20:37 -0700 Subject: [PATCH 11/25] links + formatting --- .../connect/config-entries/service-router.mdx | 63 +++++++++---------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index f264878d77a1..f476516bdee8 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -286,7 +286,6 @@ Routes = [ -```yaml ```yaml apiVersion: consul.hashicorp.com/v1alpha1 # required kind: ServiceRouter # required @@ -306,7 +305,7 @@ spec: methods: [GET, POST, PUT] http: header: ## do not specify present, exact, prefix, suffix, and regex in a single header - - name: ## required when specifying routes.match.http.header + - name: ## required when specifying spec.routes.match.http.header present: false exact: prefix: @@ -314,8 +313,8 @@ spec: regex: invert: false http: - queryParam: ## do not specify present, exact, and regex in a single QueryParam - - name: ## required when specifying routes.match.http.header + queryParam: ## do not specify present, exact, and regex in a single queryParam + - name: ## required when specifying spec.routes.match.http.header present: false exact: regex: @@ -325,7 +324,7 @@ spec: serviceSubset: namespace: partition: - prefixRewrite: ## required specifying either routes.match.http.pathPrefix or routes.match.http.pathExact + prefixRewrite: ## required specifying either spec.routes.match.http.pathPrefix or spec.routes.match.http.pathExact requestTimeout: 0 idleTimeout: 0 numRetries: 1 @@ -396,8 +395,8 @@ Specifies key-value pairs to add to the KV store. #### Values -- Default: none -- Data type: Map of one or more key-value pairs +- Default: None +- Data type: Map of one or more key-value pairs - ``: String - ``: String or integer @@ -413,7 +412,7 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | | `Match` | The criteria the configuration entry uses to identify requests. Refer to [`Routes[].Match`](#routes-match) for additional configuration parameters. | Map | None | - | `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes.Destination`](#routes-destination) for additional configuration parameters. | Map | None | + | `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes[].Destination`](#routes-destination) for additional configuration parameters. | Map | None | ### `Routes[].Match` @@ -441,12 +440,12 @@ When matching on the HTTP request path, you can only match on one path at a time | Parameter | Description | Data type | Default | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `PathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same HTTP object. | String | None | -| `PathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathRegex` in the same HTTP object. | String | None | -| `PathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `PathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same HTTP map. | String | None | +| `PathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathRegex` in the same HTTP map. | String | None | +| `PathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | | `Methods` | Specifies HTTP methods that the match applies to. Refer to [`Routes[].Match{}.HTTP{}.Methods`](#routes-match-http-methods) for additional configuration parameters. | List | None | -| `Header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header) for additional configuration parameters. | List | None | -| `QueryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `Present`, `Exact`, or `Regex` in the same HTTP object. Refer to [`Routes[].Match{}.HTTP{}.QueryParam](#routes-match-http-queryparam) for additional configuration parameters. | List | None | +| `Header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header) for additional configuration parameters. | List | None | +| `QueryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `Present`, `Exact`, or `Regex` in the same HTTP map. Refer to [`Routes[].Match{}.HTTP{}.QueryParam](#routes-match-http-queryparam) for additional configuration parameters. | List | None | ### `Routes[].Match{}.HTTP{}.Methods` @@ -468,9 +467,9 @@ Specifies HTTP methods that the match applies to. If not specified, the request ### `Routes[].Match{}.HTTP{}.Header` -Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. +Specifies information in the HTTP request header to match with. When more than one field is configured, all criteria must match for the service routing to apply. -When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, and `Regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. +When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, and `Regex` in the same HTTP map. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. #### Values @@ -480,11 +479,11 @@ When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | | `Name` | Specifies the name of the HTTP header to match. This field is required when using [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header). | String | None | -| `Present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. | Boolean | `false` | -| `Exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP object. | String | None | -| `Prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP object. | String | None | -| `Suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP object. | String | None | -| `Regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `Present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map . | Boolean | `false` | +| `Exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map . | String | None | +| `Prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP map . | String | None | +| `Suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP map . | String | None | +| `Regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | | `Invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | ### `Routes[].Match{}.HTTP{}.QueryParam` @@ -520,7 +519,7 @@ Specifies the target service to route matching requests to, as well as behavior | `ServiceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None | | `Namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | | `Partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None | -| `PrefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Match.HTTP.PathPrefix`](#match-http-pathprefix) or [`Match.HTTP.PathExact`](#match-http-pathexact) be configured on this route. | String | None | +| `PrefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Routes[].Match{}.HTTP{}.PathPrefix`](#routes-match-http-pathprefix) or [`Routes[].Match{}.HTTP{}.PathExact`](#routes-match-http-pathexact) be configured on this route. | String | None | | `RequestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | | `IdleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | | `NumRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`. | Integer | `1` | @@ -701,12 +700,12 @@ When matching on the HTTP request path, you can only match on one path at a time | Parameter | Description | Data type | Default | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP object. | String | None | -| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP object. | String | None | -| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP map . | String | None | +| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP map . | String | None | +| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | | `methods` | Specifies HTTP methods that the match applies to. Refer to [`spec.routes[].match.http.methods`](#spec-routes-match-http-methods) for additional configuration parameters. | List | None | -| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | -| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP object. Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | +| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map . You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | +| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP map . Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | ### `spec.routes[].match.http.methods` @@ -730,7 +729,7 @@ Specifies HTTP methods that the match applies to. If not specified, the request Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. -When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, and `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. +When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, and `regex` in the same HTTP map . You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. #### Values @@ -740,11 +739,11 @@ When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | | `name` | Specifies the name of the HTTP header to match. This field is required when using [`spec.routes[].match.http.header`](#spec-routes-match-http-header). | String | None | -| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. | Boolean | `false` | -| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP object. | String | None | -| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP object. | String | None | -| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP object. | String | None | -| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map . | Boolean | `false` | +| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP map . | String | None | +| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP map . | String | None | +| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP map . | String | None | +| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | | `invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | ### `spec.routes[].match.http.queryParam` From 21ff59a5660be207db4f6792276da9ea05d72c3a Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 13:34:09 -0700 Subject: [PATCH 12/25] proofing fixes --- .../config-entries/service-resolver.mdx | 8 +- .../connect/config-entries/service-router.mdx | 78 +++++++++---------- 2 files changed, 43 insertions(+), 43 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 94b4a534a8aa..1b802420b695 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -71,7 +71,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` -- [`kind`](#kind): string | required | must be set to `serviceResolver` +- [`kind`](#kind): string | required | must be set to `ServiceResolver` - [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional @@ -399,12 +399,12 @@ Specifies the admin partition that the service resolver applies to. Refer to [ad ### `Meta` -Specifies key-value pairs to add to the KV store. +Specifies key/value pairs to add to the KV store. #### Values - Default: none -- Data type: Map of one or more key-value pairs +- Data type: Map of one or more key/value pairs - ``: String - ``: String or integer @@ -662,7 +662,7 @@ Specifies the namespace that the service resolver applies to. Refer to [namespac ### `spec` -Map that contains the details about the `ServiceIntentions` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. +Map that contains the details about the `ServiceResolver` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. #### Values diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index f476516bdee8..748ec2d06a24 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -70,7 +70,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` -- [`kind`](#kind): string | required | must be set to `serviceRouter` +- [`kind`](#kind): string | required | must be set to `ServiceRouter` - [`metadata`](#metadata): map | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional @@ -391,12 +391,12 @@ Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to app ### `Meta` -Specifies key-value pairs to add to the KV store. +Specifies key/value pairs to add to the KV store. #### Values - Default: None -- Data type: Map of one or more key-value pairs +- Data type: Map of one or more key/value pairs - ``: String - ``: String or integer @@ -561,16 +561,16 @@ Specifies a set of HTTP-specific header modification rules applied to requests r - Default: None - Values: Object containing one or more fields that define header modification rules: - - `Add`: Map of one or more key-value pairs. - - `Set`: Map of one or more key-value pairs. - - `Remove`: Map of one or more key-value pairs. + - `Add`: Map of one or more key/value pairs. + - `Set`: Map of one or more key/value pairs. + - `Remove`: Map of one or more key/value pairs. The following table describes how to configure values for request headers: | Rule | Description | Type | | --- | --- | --- | -| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -585,16 +585,16 @@ Specifies a set of HTTP-specific header modification rules applied to responses - Default: None - Values: Object containing one or more fields that define header modification rules: - - `Add`: Map of one or more string key-value pairs. - - `Set`: Map of one or more string key-value pairs. - - `Remove`: Map of one or more string key-value pairs. + - `Add`: Map of one or more string key/value pairs. + - `Set`: Map of one or more string key/value pairs. + - `Remove`: Map of one or more string key/value pairs. The following table describes how to configure values for response headers: | Rule | Description | Type | | --- | --- | --- | -| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -617,7 +617,7 @@ Specifies the type of configuration entry to implement. - Default: none - This field is required. -- Data type: String value that must be set to `serviceRouter`. +- Data type: String value that must be set to `ServiceRouter`. ### `metadata.name` @@ -641,7 +641,7 @@ Specifies the Consul namespace to use for resolving the service. You can map Con ### `spec` -Kubernetes-only field that contains all of the configurations for service splitter pods. +Map that contains the details about the `ServiceRouter` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. #### Values @@ -651,12 +651,12 @@ Kubernetes-only field that contains all of the configurations for service splitt ### `spec.meta` -Specifies key-value pairs to add to the KV store. +Specifies key/value pairs to add to the KV store. #### Values - Default: none -- Data type: Map of one or more key-value pairs +- Data type: Map of one or more key/value pairs - keys: String - values: String, integer, or float @@ -700,12 +700,12 @@ When matching on the HTTP request path, you can only match on one path at a time | Parameter | Description | Data type | Default | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP map . | String | None | -| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP map . | String | None | -| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP map. | String | None | +| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP map. | String | None | +| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | | `methods` | Specifies HTTP methods that the match applies to. Refer to [`spec.routes[].match.http.methods`](#spec-routes-match-http-methods) for additional configuration parameters. | List | None | -| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map . You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | -| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP map . Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | +| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | +| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP map. Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | ### `spec.routes[].match.http.methods` @@ -729,7 +729,7 @@ Specifies HTTP methods that the match applies to. If not specified, the request Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. -When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, and `regex` in the same HTTP map . You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. +When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, and `regex` in the same HTTP map. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. #### Values @@ -739,11 +739,11 @@ When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | | `name` | Specifies the name of the HTTP header to match. This field is required when using [`spec.routes[].match.http.header`](#spec-routes-match-http-header). | String | None | -| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map . | Boolean | `false` | -| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP map . | String | None | -| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP map . | String | None | -| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP map . | String | None | -| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map. | Boolean | `false` | +| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP map. | String | None | +| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP map. | String | None | +| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP map. | String | None | +| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | | `invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | ### `spec.routes[].match.http.queryParam` @@ -821,16 +821,16 @@ Specifies a set of HTTP-specific header modification rules applied to requests r - Default: None - Values: Object containing one or more fields that define header modification rules: - - `add`: Map of one or more key-value pairs. - - `set`: Map of one or more key-value pairs. - - `remove`: Map of one or more key-value pairs. + - `add`: Map of one or more key/value pairs. + - `set`: Map of one or more key/value pairs. + - `remove`: Map of one or more key/value pairs. The following table describes how to configure values for request headers: | Rule | Description | Type | | --- | --- | --- | -| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -845,16 +845,16 @@ Specifies a set of HTTP-specific header modification rules applied to responses - Default: None - Values: Object containing one or more fields that define header modification rules: - - `add`: Map of one or more string key-value pairs. - - `set`: Map of one or more string key-value pairs. - - `remove`: Map of one or more string key-value pairs. + - `add`: Map of one or more string key/value pairs. + - `set`: Map of one or more string key/value pairs. + - `remove`: Map of one or more string key/value pairs. The following table describes how to configure values for response headers: | Rule | Description | Type | | --- | --- | --- | -| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -871,7 +871,7 @@ The following examples demonstrate common service router configuration patterns ### Path prefix matching -The following example routes HTTP requests with `/admin` at the start of their path to a service named `admin`. +The following example routes HTTP requests for the `web` service to a service named `admin` when they have `/admin` at the start of their path. From cd6e60b448d6582385baea6c1a3cefd3f73a288f Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 26 Apr 2023 13:44:44 -0700 Subject: [PATCH 13/25] mmore fixes --- .../content/docs/connect/config-entries/service-router.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 748ec2d06a24..2b6a28f19ad9 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -367,8 +367,7 @@ Specifies a name for the configuration entry. The name is metadata that you can #### Values -- Default: Defaults to the name of the node after writing the entry to the Consul server. -- This field is required. +- Default: None - Data type: String ### `Namespace` @@ -625,11 +624,9 @@ Specifies a name for the configuration entry. The name is metadata that you can #### Values -- Default: Inherits name from the host node -- This field is required. +- Default: None - Data type: String - ### `metadata.namespace` Specifies the Consul namespace to use for resolving the service. You can map Consul namespaces to Kubernetes Namespaces in different ways. Refer to [Custom Resource Definitions (CRDs) for Consul on Kubernetes](/consul/docs/k8s/crds#consul-enterprise) for additional information. From 63beefcb6e5bd9fdb50a5e5c4259e799c2ec631a Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Mon, 15 May 2023 13:53:57 -0700 Subject: [PATCH 14/25] Apply suggestions from code review suggestions from code review for service resolver Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../config-entries/service-resolver.mdx | 42 +++++++++++-------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 1b802420b695..fb6fc7c15ce6 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -5,7 +5,7 @@ description: >- Service resolver configuration entries are L7 traffic management tools for defining sets of service instances that resolve upstream requests and Consul’s behavior when resolving them. Learn how to write `service-resolver` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case. --- -# Service Resolver Configuration Reference +# Service resolver configuration entry reference This page provides reference information for service resolver configuration entries. Configure and apply service resolvers to create named subsets of service instances and define their behavior when satisfying upstream requests. @@ -399,12 +399,12 @@ Specifies the admin partition that the service resolver applies to. Refer to [ad ### `Meta` -Specifies key/value pairs to add to the KV store. +Specifies key-value pairs to add to the KV store. #### Values - Default: none -- Data type: Map of one or more key/value pairs +- Data type: Map of one or more key-value pairs - ``: String - ``: String or integer @@ -414,7 +414,7 @@ Specifies the timeout duration for establishing new network connections to this #### Values -- Default: `0s` +- Default: None - Data type: String ### `RequestTimeout` @@ -428,12 +428,12 @@ Specifies the timeout duration for receiving an HTTP response from this service, ### `Subsets` -Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If empty, only the unnamed default subset is usable. +Specifies names for custom service subsets and the conditions under which service instances belong to each subset. Define a subset by specifying a key and a value where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If this parameter is not specified, only the unnamed default subset is usable. #### Values - Default: None -- Data type: Map containing a key/value pair. +- Data type: Map containing a key-value pair. - ``: String that names the subset. The string must be valid as a DNS subdomain element. - ``: Map that can contain the following parameters: @@ -444,7 +444,7 @@ Specifies names for service subsets and the conditions under which service insta ### `DefaultSubset` -Specifies a defined subset of service instances to use when no explicit subset is requested. If empty, Consul uses the unnamed default subset. +Specifies a defined subset of service instances to use when no explicit subset is requested. If this parameter is not specified, Consul uses the unnamed default subset. #### Values @@ -473,7 +473,7 @@ Specifies redirect instructions for local service traffic so that services deplo Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. -This map is keyed by the name of the local service subset whose traffic should resolve elsewhere when it fails. The `"*"` wildcard can be used to apply failovers to any subset. +This parameter is a map, and its key is the name of the local service subset that resolves to another location when it fails. You can specify a `"*"` wildcard to apply failovers to any subset. `Service`, `ServiceSubset`, `Namespace`, `Targets`, and `Datacenters` cannot all be empty at the same time. @@ -551,7 +551,7 @@ Specifies the type of load balancing policy for selecting a host. Supported load ### `LoadBalancer{}.LeastRequestConfig` -Specifies configuration for the `least_request policy` type. +Specifies configuration for the `least_request` policy type. #### Values @@ -591,7 +591,7 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. | `FieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `FieldValue` parameter if `SourceIP` is also configured. | String | None | | `CookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`LoadBalancer{}.HashPolicies[].CookieConfig`](#loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | | `SourceIP` | Determines if the hash type should besource IP address. You cannot specify `SourceIP` if `Field` or `FieldValue` are configured. | Boolean | `false` | - | `Terminal` | Determines if Consul should short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + | `Terminal` | Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | ### `LoadBalancer{}.HashPolicies[].CookieConfig` @@ -676,7 +676,7 @@ Specifies the timeout duration for establishing new network connections to this #### Values -- Default: `0s` +- Default: None - Data type: String ### `spec.requestTimeout` @@ -690,12 +690,12 @@ Specifies the timeout duration for receiving an HTTP response from this service, ### `spec.subsets` -Specifies names for service subsets and the conditions under which service instances belong to each subset. Subsets are defined in the form of a key/value pair, where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If empty, only the unnamed default subset is usable. +Specifies names for custom service subsets and the conditions under which service instances belong to each subset. Define a subset by specifying a key and a value where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If this parameter is not specified, only the unnamed default subset is usable. #### Values - Default: None -- Data type: Map containing a key/value pair. +- Data type: Map containing a key-value pair. - ``: String that names the subset. The string must be valid as a DNS subdomain element. - ``: Map that can contain the following parameters: @@ -706,7 +706,7 @@ Specifies names for service subsets and the conditions under which service insta ### `spec.defaultSubset` -Specifies a defined subset of service instances to use when no explicit subset is requested. If empty, Consul uses the unnamed default subset. +Specifies a defined subset of service instances to use when no explicit subset is requested. If this parameter is not specified, Consul uses the unnamed default subset. #### Values @@ -735,7 +735,7 @@ Specifies redirect instructions for local service traffic so that services deplo Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. -This map is keyed by the name of the local service subset whose traffic should redirect when it fails. The `"*"` wildcard can be used to apply failovers to any subset. +This parameter is a map, and its key is the name of the local service subset that resolves to another location when it fails. You can specify a `"*"` wildcard to apply failovers to any subset. `service`, `serviceSubset`, `namespace`, `targets`, and `datacenters` cannot all be empty at the same time. @@ -797,6 +797,9 @@ Specifies the type of load balancing policy for selecting a host. Supported load - Least request - Ring hash - Maglev +- Cookie +- Header +- Query parameter #### Values @@ -810,6 +813,11 @@ Specifies the type of load balancing policy for selecting a host. Supported load | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`spec.loadBalancer.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig). | | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.ringHashConfig`](#spec-loadbalancer-ringhashconfig). | | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.hashPolicies`](#spec-loadbalancer-hashpolicies). | + | `cookie` | description | + | `header` | description | + | `query_param` | description | + + ### `spec.loadBalancer.leastRequestConfig` @@ -853,7 +861,7 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. | `fieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `fieldValue` parameter if `sourceIP` is also configured. | String | None | | `cookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`spec.loadBalancer.hashPolicies[].cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | | `sourceIP` | Determines if the hash type should besource IP address. You cannot specify `sourceIP` if `field` or `fieldValue` are configured. | Boolean | `false` | - | `terminal` | Determines if Consul should short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + | `terminal` | Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | ### `spec.loadBalancer{}.hashPolicies[].cookieConfig` @@ -879,7 +887,7 @@ The following examples demonstrate common service resolver configuration pattern ### Filter on service version -The following example creates two subsets of the `web` service, and assigns service instances to subsets based on each instance's version metadata. It also defined `v1` as the default subset. +The following example creates two subsets of the `web` service and assigns service instances to subsets based on each instance's version metadata. It also defined `v1` as the default subset. From d9605f0920dac4730f585e8501fccca6302be1c2 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 15 May 2023 13:58:31 -0700 Subject: [PATCH 15/25] policy sections edits --- .../docs/connect/config-entries/service-resolver.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index fb6fc7c15ce6..a26082df6604 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -535,6 +535,9 @@ Specifies the type of load balancing policy for selecting a host. Supported load - Least request - Ring hash - Maglev +- Cookie +- Header +- Query Parameter #### Values @@ -548,6 +551,9 @@ Specifies the type of load balancing policy for selecting a host. Supported load | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). | | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). | | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). | + | `cookie` | x | + | `header` | x | + | `query_parameter` | x | ### `LoadBalancer{}.LeastRequestConfig` From 649149d7c307384af23fb728dafd710715b3c386 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 15 May 2023 14:05:10 -0700 Subject: [PATCH 16/25] service router code review --- .../connect/config-entries/service-router.mdx | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 2b6a28f19ad9..5728c9903ce1 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -26,7 +26,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`Meta`](#meta): map - [`Routes`](#routes): list - [`Match`](#routes-match): map - - [‘HTTP`](#routes-match-http): map + - [`HTTP`](#routes-match-http): map - [`PathExact`](#routes-match-http-pathexact): string - [`PathPrefix`](#routes-match-http-pathprefix): string - [`PathRegex`](#routes-match-http-pathregex): string @@ -390,12 +390,12 @@ Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to app ### `Meta` -Specifies key/value pairs to add to the KV store. +Specifies key-value pairs to add to the KV store. #### Values - Default: None -- Data type: Map of one or more key/value pairs +- Data type: Map of one or more key-value pairs - ``: String - ``: String or integer @@ -514,10 +514,10 @@ Specifies the target service to route matching requests to, as well as behavior | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `Service` | Specifies the name of the service to resolve instead of the default. If empty, the default service name is inherited from the configuration entry’s [`Name` field](#name). | String | None | -| `ServiceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None | -| `Namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | -| `Partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None | +| `Service` | Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`Name` field](#name). | String | None | +| `ServiceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used. | String | None | +| `Namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. | String | None | +| `Partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. | String | None | | `PrefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Routes[].Match{}.HTTP{}.PathPrefix`](#routes-match-http-pathprefix) or [`Routes[].Match{}.HTTP{}.PathExact`](#routes-match-http-pathexact) be configured on this route. | String | None | | `RequestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | | `IdleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | @@ -560,16 +560,16 @@ Specifies a set of HTTP-specific header modification rules applied to requests r - Default: None - Values: Object containing one or more fields that define header modification rules: - - `Add`: Map of one or more key/value pairs. - - `Set`: Map of one or more key/value pairs. - - `Remove`: Map of one or more key/value pairs. + - `Add`: Map of one or more key-value pairs. + - `Set`: Map of one or more key-value pairs. + - `Remove`: Map of one or more key-value pairs. The following table describes how to configure values for request headers: | Rule | Description | Type | | --- | --- | --- | -| `Add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `Set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -584,16 +584,16 @@ Specifies a set of HTTP-specific header modification rules applied to responses - Default: None - Values: Object containing one or more fields that define header modification rules: - - `Add`: Map of one or more string key/value pairs. - - `Set`: Map of one or more string key/value pairs. - - `Remove`: Map of one or more string key/value pairs. + - `Add`: Map of one or more string key-value pairs. + - `Set`: Map of one or more string key-value pairs. + - `Remove`: Map of one or more string key-value pairs. The following table describes how to configure values for response headers: | Rule | Description | Type | | --- | --- | --- | -| `Add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `Set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -614,7 +614,7 @@ Specifies the type of configuration entry to implement. #### Values -- Default: none +- Default: None - This field is required. - Data type: String value that must be set to `ServiceRouter`. @@ -648,12 +648,12 @@ Map that contains the details about the `ServiceRouter` configuration entry. The ### `spec.meta` -Specifies key/value pairs to add to the KV store. +Specifies key-value pairs to add to the KV store. #### Values - Default: none -- Data type: Map of one or more key/value pairs +- Data type: Map of one or more key-value pairs - keys: String - values: String, integer, or float @@ -772,10 +772,10 @@ Specifies the target service to route matching requests to, as well as behavior | Parameter | Description | Data type | Default | | :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `service` | Specifies the name of the service to resolve instead of the default. If empty, the default service name is inherited from the configuration entry’s [`name` field](#name). | String | None | -| `serviceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None | -| `namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | -| `partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None | +| `service` | Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`name` field](#name). | String | None | +| `serviceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used. | String | None | +| `namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. | String | None | +| `partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. | String | None | | `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`spec.routes[].match.http.pathPrefix`](#spec-routes-match-http-pathprefix) or [`spec.routes[].match.http.pathExact`](#spec-routes-match-http-pathexact) be configured on this route. | String | None | | `requestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | | `idleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | @@ -818,16 +818,16 @@ Specifies a set of HTTP-specific header modification rules applied to requests r - Default: None - Values: Object containing one or more fields that define header modification rules: - - `add`: Map of one or more key/value pairs. - - `set`: Map of one or more key/value pairs. - - `remove`: Map of one or more key/value pairs. + - `add`: Map of one or more key-value pairs. + - `set`: Map of one or more key-value pairs. + - `remove`: Map of one or more key-value pairs. The following table describes how to configure values for request headers: | Rule | Description | Type | | --- | --- | --- | -| `add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders @@ -842,16 +842,16 @@ Specifies a set of HTTP-specific header modification rules applied to responses - Default: None - Values: Object containing one or more fields that define header modification rules: - - `add`: Map of one or more string key/value pairs. - - `set`: Map of one or more string key/value pairs. - - `remove`: Map of one or more string key/value pairs. + - `add`: Map of one or more string key-value pairs. + - `set`: Map of one or more string key-value pairs. + - `remove`: Map of one or more string key-value pairs. The following table describes how to configure values for response headers: | Rule | Description | Type | | --- | --- | --- | -| `add` | Defines a set of key/value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | -| `set` | Defines a set of key/value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | | `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | #### Use variable placeholders From c05053aa25699d7c2b796c68fe1bf0956db2ac54 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 15 May 2023 14:47:48 -0700 Subject: [PATCH 17/25] Tables to sections - service router HCL --- .../connect/config-entries/service-router.mdx | 296 +++++++++++++++--- 1 file changed, 249 insertions(+), 47 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 5728c9903ce1..376b6c0fa95f 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -408,10 +408,8 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th - Default: None - Data type: List that can contain the following parameters: - | Parameter | Description | Data type | Default | - | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | - | `Match` | The criteria the configuration entry uses to identify requests. Refer to [`Routes[].Match`](#routes-match) for additional configuration parameters. | Map | None | - | `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes[].Destination`](#routes-destination) for additional configuration parameters. | Map | None | +- [`Match`](#routes-match) +- [`Destination`](#routes-destination) ### `Routes[].Match` @@ -420,11 +418,7 @@ Describes a set of criteria that Consul compares incoming L7 traffic with. If em #### Values - Default: None -- Data type: Map that contains the following parameter: - -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `HTTP` | A set of HTTP-specific match criteria. Refer to [`Routes[].Match{}.HTTP`](#routes-match-http) for additional configuration parameters. | Map | None | +- Data type: Map that contains the [`Routes[].Match{}.HTTP`](#routes-match-http) parameter. ### `Routes[].Match{}.HTTP` @@ -437,14 +431,39 @@ When matching on the HTTP request path, you can only match on one path at a time - Default: None - Data type: Map that can contain the following parameters: -| Parameter | Description | Data type | Default | -| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `PathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same HTTP map. | String | None | -| `PathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathRegex` in the same HTTP map. | String | None | -| `PathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | -| `Methods` | Specifies HTTP methods that the match applies to. Refer to [`Routes[].Match{}.HTTP{}.Methods`](#routes-match-http-methods) for additional configuration parameters. | List | None | -| `Header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header) for additional configuration parameters. | List | None | -| `QueryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `Present`, `Exact`, or `Regex` in the same HTTP map. Refer to [`Routes[].Match{}.HTTP{}.QueryParam](#routes-match-http-queryparam) for additional configuration parameters. | List | None | + - [`PathExact`](#routes-match-http-pathexact) + - [`PathPrefix`](#routes-match-http-pathprefix) + - [`PathRegex`](#routes-match-http-pathregex) + - [`Methods`](#routes-match-http-methods) + - [`Header`](#routes-match-http-header) + - [`QueryParam`](#routes-match-http-queryparam) + +### `Routes[].Match{}.HTTP{}.PathExact` + +Specifies the exact path to match on the HTTP request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.PathPrefix` + +Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathRegex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.PathRegex` + +Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. + +#### Values + +- Default: None +- Data type: String ### `Routes[].Match{}.HTTP{}.Methods` @@ -475,15 +494,76 @@ When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, - Default: None - Data type: List containing one or more of the following parameters: -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `Name` | Specifies the name of the HTTP header to match. This field is required when using [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header). | String | None | -| `Present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map . | Boolean | `false` | -| `Exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map . | String | None | -| `Prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP map . | String | None | -| `Suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP map . | String | None | -| `Regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | -| `Invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | + - [`Name`](#routes-match-http-header-name) + - [`Present`](#routes-match-http-header-present) + - [`Exact`](#routes-match-http-header-exact) + - [`Prefix`](#routes-match-http-header-prefix) + - [`Suffix`](#routes-match-http-header-suffix) + - [`Regex`](#routes-match-http-header-regex) + - [`Invert`](#routes-match-http-header-invert) + +### `Routes[].Match{}.HTTP{}.Header[].Name` + +Specifies the name of the HTTP header to match. This field is required when using [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header). + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.Header[].Present` + +Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `Routes[].Match{}.HTTP{}.Header[].Exact` + +Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.Header[].Prefix` + +Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.Header[].Suffix` + +Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.Header[].Regex` + +Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.Header[].Invert` + +Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. + +#### Values + +- Default: `false` +- Data type: Boolean ### `Routes[].Match{}.HTTP{}.QueryParam` @@ -496,12 +576,46 @@ When using this field, do not configure `Present`, `Exact`, and `Regex` in a sin - Default: None - Data type: List of maps. Each map can contain one or more of the following parameters: -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `Name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`Routes[].Match{}.HTTP{}.QueryParam`](#routes-match-http-queryparam). | String | None | -| `Present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `Exact` or `Regex` in the same map. | Boolean | `false` | -| `Exact` | Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `Present` or `Regex` in the same map. | String | None | -| `Regex` | Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `Present` or `Exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | + - [`Name`](#routes-match-http-queryparam-name) + - [`Present`](#routes-match-http-queryparam-present) + - [`Exact`](#routes-match-http-queryparam-exact) + - [`Regex`](#routes-match-http-queryparam-regex) + +### `Routes[].Match{}.HTTP{}.QueryParam[].Name` + +Specifies the name of the HTTP query parameter to match. This value is required when using [`Routes[].Match{}.HTTP{}.QueryParam`](#routes-match-http-queryparam). + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.QueryParam[].Present` + +Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `Exact` or `Regex` in the same map. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `Routes[].Match{}.HTTP{}.QueryParam[].Exact` + +Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `Present` or `Regex` in the same map. + +#### Values + +- Default: None +- Data type: String + +### `Routes[].Match{}.HTTP{}.QueryParam[].Regex` + +Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `Present` or `Exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. + +#### Values + +- Default: None +- Data type: String ### `Routes[].Destination` @@ -512,21 +626,100 @@ Specifies the target service to route matching requests to, as well as behavior - Default: None - Data type: Map containing one or more of the following parameters: -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `Service` | Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`Name` field](#name). | String | None | -| `ServiceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used. | String | None | -| `Namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. | String | None | -| `Partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. | String | None | -| `PrefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Routes[].Match{}.HTTP{}.PathPrefix`](#routes-match-http-pathprefix) or [`Routes[].Match{}.HTTP{}.PathExact`](#routes-match-http-pathexact) be configured on this route. | String | None | -| `RequestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | -| `IdleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | -| `NumRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`. | Integer | `1` | -| `RetryOnConnectFailure` | Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). | Boolean | `false` | -| `RetryOn` | Specifies a list of conditions for Consul to retry requests. Use this field to configure advanced logic for retry attempts. Refer to [`Routes[].Destination{}.RetryOn[]`](#routes-destination-retryon) for additional configuration parameters. | List | None | -| `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. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). -| `RequestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`Routes[].Destination{}.RequestHeaders`](#routes-destination-requestheaders) for additional configuration parameters. | Map | None | -| `ResponseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`Routes[].Destination{}.ResponseHeaders`](#routes-destination-responseheaders) for additional configuration parameters. | Map | None | + - [`Service`](#routes-destination-service) + - [`ServiceSubset`](#routes-destination-servicesubset) + - [`Namespace`](#routes-destination-namespace) + - [`Partition`](#routes-destination-partition) + - [`PrefixRewrite`](#routes-destination-prefixrewrite) + - [`RequestTimeout`](#routes-destination-requesttimeout) + - [`IdleTimeout`](#routes-destination-idletimeout) + - [`NumRetries`](#routes-destination-numretries) + - [`RetryOnConnectFailure`](#routes-destination-retryonconnectfailure) + - [`RetryOn`](#routes-destination-retryon) + - [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes) + - [`RequestHeaders`](#routes-destination-requestheaders) + - [`ResponseHeaders`](#routes-destination-responseheaders) + +### `Routes[].Destination{}.Service` + +Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`Name` field](#name). + +#### Values + +Default: None +Data type: String + +### `Routes[].Destination{}.ServiceSubset` + +Specifies a named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used. + +#### Values + +Default: None +Data type: String + +### `Routes[].Destination{}.Namespace` + +Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. + +#### Values + +Default: None +Data type: String + +### `Routes[].Destination{}.Partition` + +Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. + +#### Values + +Default: None +Data type: String + +### `Routes[].Destination{}.PrefixRewrite` + +Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Routes[].Match{}.HTTP{}.PathPrefix`](#routes-match-http-pathprefix) or [`Routes[].Match{}.HTTP{}.PathExact`](#routes-match-http-pathexact) be configured on this route. + +#### Values + +Default: None +Data type: String + +### `Routes[].Destination{}.RequestTimeout` + +Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. + +#### Values + +Default: `0` +Data type: Integer + +### `Routes[].Destination{}.IdleTimeout` + +Specifies the total amount of time permitted for the request stream to be idle. + +#### Values + +Default: `0` +Data type: Integer + +### `Routes[].Destination{}.NumRetries` + +Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`. + +#### Values + +Default: `1` +Data type: Integer + +### `Routes[].Destination{}.RetryOnConnectFailure` + +Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +#### Values + +Default: `false` +Data type: Boolean ### `Routes[].Destination{}.RetryOn[]` @@ -552,6 +745,15 @@ Specifies a list of conditions for Consul to retry requests. Configure this fiel | `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | | `unavailable` | Consul was unavailable to route the request when it was made. | +### `Routes[].Destination{}.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. Configure this field and other retry fields in `Destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic) + +#### Values + +Default: None +Data type: List of integers + ### `Routes[].Destination{}.RequestHeaders` Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. From 67516312c157aa041b7174a1b8eb458eac38363f Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 15 May 2023 15:22:06 -0700 Subject: [PATCH 18/25] YAML tables to sections --- .../connect/config-entries/service-router.mdx | 313 ++++++++++++++---- 1 file changed, 257 insertions(+), 56 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 376b6c0fa95f..ee1dc8d3d104 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -513,7 +513,7 @@ Specifies the name of the HTTP header to match. This field is required when usin ### `Routes[].Match{}.HTTP{}.Header[].Present` -Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. +Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `Exact`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. #### Values @@ -522,7 +522,7 @@ Specifies that a request matches when the value in the `Name` field is present a ### `Routes[].Match{}.HTTP{}.Header[].Exact` -Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. +Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `Present`, `Prefix`, `Suffix`, or `Regex` in the same HTTP map. #### Values @@ -531,7 +531,7 @@ Specifies that a request matches when the header with the given name is this exa ### `Routes[].Match{}.HTTP{}.Header[].Prefix` -Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP map. +Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `Present`, `Exact`, `Suffix`, or `Regex` in the same HTTP map. #### Values @@ -540,7 +540,7 @@ Specifies that a request matches when the header with the given name has this pr ### `Routes[].Match{}.HTTP{}.Header[].Suffix` -Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP map. +Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP map. #### Values @@ -549,7 +549,7 @@ Specifies that a request matches when the header with the given name has this su ### `Routes[].Match{}.HTTP{}.Header[].Regex` -Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. +Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. #### Values @@ -868,10 +868,8 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th - Default: None - Data type: List that can contain the following parameters: - | Parameter | Description | Data type | Default | - | :------------ | :-------------------------------------------------------------------------------- | --------- | ------- | - | `match` | The criteria the configuration entry uses to identify requests. Refer to [`spec.routes[].match`](#spec-routes-match) for additional configuration parameters. | Map | None | - | `destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`spec.routes[].destination`](#spec-routes-destination) for additional configuration parameters. | Map | None | +- [`match`](#spec-routes-match) +- [`destination`](#spec-routes-destination) ### `spec.routes[].match` @@ -880,11 +878,7 @@ Describes a set of criteria that Consul compares incoming L7 traffic with. If em #### Values - Default: None -- Data type: Map that contains the following parameter: - -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `http` | A set of HTTP-specific match criteria. Refer to [`spec.routes[].match.http`](#spec-routes-match-http) for additional configuration parameters. | Map | None | +- Data type: Map that contains the [`spec.routes[].match.http`](#spec-routes-match-http) parameter. ### `spec.routes[].match.http` @@ -897,14 +891,39 @@ When matching on the HTTP request path, you can only match on one path at a time - Default: None - Data type: Map that can contain the following parameters: -| Parameter | Description | Data type | Default | -| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP map. | String | None | -| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP map. | String | None | -| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | -| `methods` | Specifies HTTP methods that the match applies to. Refer to [`spec.routes[].match.http.methods`](#spec-routes-match-http-methods) for additional configuration parameters. | List | None | -| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None | -| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP map. Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None | + - [`pathExact`](#spec-routes-match-http-pathexact) + - [`pathPrefix`](#spec-routes-match-http-pathprefix) + - [`pathRegex`](#spec-routes-match-http-pathregex) + - [`methods`](#spec-routes-match-http-methods) + - [`header`](#spec-routes-match-http-header) + - [`queryParam`](#spec-routes-match-http-queryparam) + +### `spec.routes[].match.http.pathExact` + +Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.pathPrefix` + +Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.pathRegex` + +Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. + +#### Values + +- Default: None +- Data type: String ### `spec.routes[].match.http.methods` @@ -935,15 +954,76 @@ When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, - Default: None - Data type: List containing one or more of the following parameters: -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `name` | Specifies the name of the HTTP header to match. This field is required when using [`spec.routes[].match.http.header`](#spec-routes-match-http-header). | String | None | -| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map. | Boolean | `false` | -| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP map. | String | None | -| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP map. | String | None | -| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP map. | String | None | -| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | -| `invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | + - [`name`](#spec-routes-match-http-header-name) + - [`present`](#spec-routes-match-http-header-present) + - [`exact`](#spec-routes-match-http-header-exact) + - [`prefix`](#spec-routes-match-http-header-prefix) + - [`suffix`](#spec-routes-match-http-header-suffix) + - [`regex`](#spec-routes-match-http-header-regex) + - [`invert`](#spec-routes-match-http-header-invert) + +### `spec.routes[].match.http.header.name` + +Specifies the name of the HTTP header to match. This field is required when using [`spec.routes[].match.http.header`](#spec-routes-match-http-header). + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.header.present` + +Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP map. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.routes[].match.http.header.exact` + +Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.header.prefix` + +Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.header.suffix` + +Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP map. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.header.regex` + +Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` in the same HTTP map . The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.header.invert` + +Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. + +#### Values + +- Default: `false` +- Data type: Boolean ### `spec.routes[].match.http.queryParam` @@ -956,12 +1036,45 @@ When using this field, do not configure `present`, `exact`, and `regex` in a sin - Default: None - Data type: List of maps. Each map can contain one or more of the following parameters: -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`spec.routes[].match.http.queryParam`](#spec-routes-match-http-queryparam). | String | None | -| `present` | Specifies that a request matches when the value in the `name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `exact` or `regex` in the same map. | Boolean | `false` | -| `exact` | Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `present` or `regex` in the same map. | String | None | -| `regex` | Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `present` or `exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | + - [`name`](#spec-routes-match-http-queryparam-name) + - [`present`](#spec-routes-match-http-queryparam-present) + - [`regex`](#spec-routes-match-http-queryparam-regex) + +### `spec.routes[].match.http.queryParam[].name` + +Specifies the name of the HTTP query parameter to match. This value is required when using [`spec.routes[].match.http.queryParam`](#spec-routes-match-http-queryparam). + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.queryParam[].present` + +Specifies that a request matches when the value in the `name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `exact` or `regex` in the same map. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.routes[].match.http.queryParam[].exact` + +Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `present` or `regex` in the same map. + +#### Values + +- Default: None +- Data type: String + +### `spec.routes[].match.http.queryParam[].regex` + +Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `present` or `exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. + +#### Values + +- Default: None +- Data type: String ### `spec.routes[].destination` @@ -972,25 +1085,104 @@ Specifies the target service to route matching requests to, as well as behavior - Default: None - Data type: Map containing one or more of the following parameters: -| Parameter | Description | Data type | Default | -| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | -| `service` | Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`name` field](#name). | String | None | -| `serviceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used. | String | None | -| `namespace` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. | String | None | -| `partition` | Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. | String | None | -| `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`spec.routes[].match.http.pathPrefix`](#spec-routes-match-http-pathprefix) or [`spec.routes[].match.http.pathExact`](#spec-routes-match-http-pathexact) be configured on this route. | String | None | -| `requestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` | -| `idleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` | -| `numRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`. | Integer | `1` | -| `retryOnConnectFailure` | Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). | Boolean | `false` | -| `retryOn` | Specifies a list of conditions for Consul to retry requests. Use this field to configure advanced logic for retry attempts. Refer to [`routes[].destination{}.RetryOn[]`](#spec-routes-destination-retryon) for additional configuration parameters. | List | None | -| `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. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). -| `requestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`spec.routes[].destination.requestHeaders`](#spec-routes-destination-requestheaders) for additional configuration parameters. | Map | None | -| `responseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`spec.routes[].destination.responseHeaders`](#spec-routes-destination-responseheaders) for additional configuration parameters. | Map | None | - -### `spec.routes[].destination.retryOn[]` - -Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + - [`service`](#spec-routes-destination-service) + - [`serviceSubset`](#spec-routes-destination-servicesubset) + - [`namespace`](#spec-routes-destination-namespace) + - [`partition`](#spec-routes-destination-partition) + - [`prefixRewrite`](#spec-routes-destination-prefixrewrite) + - [`requestTimeout`](#spec-routes-destination-requesttimeout) + - [`numRetries`](#spec-routes-destination-numretries) + - [`numRetries`](#spec-routes-destination-numretries) + - [`retryOnConnectFailure`](#spec-routes-destination-retryonconnectfailure) + - [`retryOn`](#spec-routes-destination-retryon) + - [`retryOnStatusCodes`](#spec-routes-destination-retryonstatuscodes) + - [`requestHeaders`](#spec-routes-destination-requestheaders) + - [`responseHeaders`](#spec-routes-destination-responseheaders) + +### `spec.routes[].destination.service` + +Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`metadata.name` field](#metadata-name). + +#### Values + +Default: None +Data type: String + +### `spec.routes[].destination.serviceSubset` + +Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If this parameter is not specified, the default subset is used. + +#### Values + +Default: None +Data type: String + +### `spec.routes[].destination.namespace` + +Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. + +#### Values + +Default: None +Data type: String + +### `spec.routes[].destination.partition` + +Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. + +#### Values + +Default: None +Data type: String + +### `spec.routes[].destination.prefixRewrite` + +Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`spec.routes[].match.http.pathPrefix`](#spec-routes-match-http-pathprefix) or [`spec.routes[].match.http.pathExact`](#spec-routes-match-http-pathexact) be configured on this route. + +#### Values + +Default: None +Data type: String + +### `spec.routes[].destination.requestTimeout` + +Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. + +#### Values + +Default: `0` +Data type: Integer + +### `spec.routes[].destination.idleTimeout` + +Specifies the total amount of time permitted for the request stream to be idle. + +#### Values + +Default: `0` +Data type: Integer + +### `spec.routes[].destination.numRetries` + +Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `spec.routes.destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`. + +#### Values + +Default: `1` +Data type: Integer + +### `spec.routes[].destination.retryOnConnectFailure` + +Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `spec.routes[].destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +#### Values + +Default: `false` +Data type: Boolean + +### `spec.routes[].destination.retryOn` + +Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `spec.routes[].destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). #### Values @@ -1012,6 +1204,15 @@ Specifies a list of conditions for Consul to retry requests. Configure this fiel | `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | | `unavailable` | Consul was unavailable to route the request when it was made. | +### `spec.routes[].destination.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. Configure this field and other retry fields in `spec.routes[].destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic) + +#### Values + +Default: None +Data type: List of integers + ### `spec.routes[].destination.requestHeaders` Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. From b587e04b54a383799e035924db4fae57dbcf6e38 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 15 May 2023 15:25:11 -0700 Subject: [PATCH 19/25] formatting fixes --- .../connect/config-entries/service-router.mdx | 80 +++++++++---------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index ee1dc8d3d104..8bba32d67da9 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -646,8 +646,8 @@ Specifies the name of the service to resolve. If this parameter is not specified #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `Routes[].Destination{}.ServiceSubset` @@ -655,8 +655,8 @@ Specifies a named subset of the given service to resolve instead of the one defi #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `Routes[].Destination{}.Namespace` @@ -664,8 +664,8 @@ Specifies the Consul namespace to resolve the service from instead of the curren #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `Routes[].Destination{}.Partition` @@ -673,8 +673,8 @@ Specifies the Consul admin partition to resolve the service from instead of the #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `Routes[].Destination{}.PrefixRewrite` @@ -682,8 +682,8 @@ Specifies rewrites to the HTTP request path before proxying it to its final dest #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `Routes[].Destination{}.RequestTimeout` @@ -691,8 +691,8 @@ Specifies the total amount of time permitted for the entire downstream request t #### Values -Default: `0` -Data type: Integer +- Default: `0` +- Data type: Integer ### `Routes[].Destination{}.IdleTimeout` @@ -700,8 +700,8 @@ Specifies the total amount of time permitted for the request stream to be idle. #### Values -Default: `0` -Data type: Integer +- Default: `0` +- Data type: Integer ### `Routes[].Destination{}.NumRetries` @@ -709,8 +709,8 @@ Specifies the number of times to retry the request when a retry condition occurs #### Values -Default: `1` -Data type: Integer +- Default: `1` +- Data type: Integer ### `Routes[].Destination{}.RetryOnConnectFailure` @@ -718,8 +718,8 @@ Specifies that connection failure errors that trigger a retry request. Configure #### Values -Default: `false` -Data type: Boolean +- Default: `false` +- Data type: Boolean ### `Routes[].Destination{}.RetryOn[]` @@ -751,8 +751,8 @@ Specifies a list of integers for [HTTP response status codes](https://developer. #### Values -Default: None -Data type: List of integers +- Default: None +- Data type: List of integers ### `Routes[].Destination{}.RequestHeaders` @@ -1105,8 +1105,8 @@ Specifies the name of the service to resolve. If this parameter is not specified #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `spec.routes[].destination.serviceSubset` @@ -1114,8 +1114,8 @@ Specifies a named subset of the given service to resolve instead of the one defi #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `spec.routes[].destination.namespace` @@ -1123,8 +1123,8 @@ Specifies the Consul namespace to resolve the service from instead of the curren #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `spec.routes[].destination.partition` @@ -1132,8 +1132,8 @@ Specifies the Consul admin partition to resolve the service from instead of the #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `spec.routes[].destination.prefixRewrite` @@ -1141,8 +1141,8 @@ Specifies rewrites to the HTTP request path before proxying it to its final dest #### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `spec.routes[].destination.requestTimeout` @@ -1150,8 +1150,8 @@ Specifies the total amount of time permitted for the entire downstream request t #### Values -Default: `0` -Data type: Integer +- Default: `0` +- Data type: Integer ### `spec.routes[].destination.idleTimeout` @@ -1159,8 +1159,8 @@ Specifies the total amount of time permitted for the request stream to be idle. #### Values -Default: `0` -Data type: Integer +- Default: `0` +- Data type: Integer ### `spec.routes[].destination.numRetries` @@ -1168,8 +1168,8 @@ Specifies the number of times to retry the request when a retry condition occurs #### Values -Default: `1` -Data type: Integer +- Default: `1` +- Data type: Integer ### `spec.routes[].destination.retryOnConnectFailure` @@ -1177,8 +1177,8 @@ Specifies that connection failure errors that trigger a retry request. Configure #### Values -Default: `false` -Data type: Boolean +- Default: `false` +- Data type: Boolean ### `spec.routes[].destination.retryOn` @@ -1210,8 +1210,8 @@ Specifies a list of integers for [HTTP response status codes](https://developer. #### Values -Default: None -Data type: List of integers +- Default: None +- Data type: List of integers ### `spec.routes[].destination.requestHeaders` From 1756853be9d66bc2fbaed7b4bee67639e36694ea Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 15 May 2023 16:57:13 -0700 Subject: [PATCH 20/25] converting tables to sections - service resolver --- .../config-entries/service-resolver.mdx | 486 ++++++++++++++---- 1 file changed, 393 insertions(+), 93 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index a26082df6604..d597e1016e0a 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -51,11 +51,11 @@ The following list outlines field hierarchy, language-specific data types, and r - [`Peer`](#failover-targets-peer): string - [`LoadBalancer`](#loadbalancer): map - [`Policy`](#loadbalancer-policy): string - - [`RingHashConfig`](#loadbalancer-ringhashconfig): map - - [`MinimumRingSize`](#loadbalancer-ringhashconfig-minimum): integer | `1024` - - [`MaximumRingSize`](#loadbalancer-ringhashconfig-maximum): integer | `8192` - [`LeastRequestConfig`](#loadbalancer-leastrequestconfig): map - - [`ChoiceCount`](#loadbalancer-leastrequestconfig-choicecount): integer `2` + - [`ChoiceCount`](#loadbalancer-leastrequestconfig-choicecount): integer `2` + - [`RingHashConfig`](#loadbalancer-ringhashconfig): map + - [`MinimumRingSize`](#loadbalancer-ringhashconfig): integer | `1024` + - [`MaximumRingSize`](#loadbalancer-ringhashconfig): integer | `8192` - [`HashPolicies`](#loadbalancer-hashpolicies): map - [`Field`](#loadbalancer-hashpolicies-field): string - [`FieldValue`](#loadbalancer-hashpolicies-fieldvalue): string @@ -104,10 +104,10 @@ The following list outlines field hierarchy, language-specific data types, and r - [`loadBalancer`](#spec-loadbalancer): map - [`policy`](#spec-loadbalancer-policy): string - [`leastRequestConfig`](#spec-loadbalancer-leastrequestconfig): map - - [`choiceCount`](#spec-loadbalancer-leastrequestconfig-choicecount): integer | `2` + - [`choiceCount`](#spec-loadbalancer-leastrequestconfig): integer | `2` - [`ringHashConfig`](#spec-loadbalancer-ringhashconfig): map - - [`minimumRingSize`](#spec-loadbalancer-ringhashconfig-minimum): integer | `1024` - - [`maximumRingSize`](#spec-loadbalancer-ringhashconfig-maximum): integer | `8192` + - [`minimumRingSize`](#spec-loadbalancer-ringhashconfig): integer | `1024` + - [`maximumRingSize`](#spec-loadbalancer-ringhashconfig): integer | `8192` - [`hashPolicies`](#spec-loadbalancer-hashpolicies): list - [`field`](#spec-loadbalancer-hashpolicies-field): string - [`fieldValue`](#spec-loadbalancer-hashpolicies-fieldvalue): string @@ -182,12 +182,12 @@ Failover = { ## requires at least one of the following: Servic LoadBalancer = { Policy = "random" - RingHashConfig = { ## requires Policy = "ring_hash" + LeastRequestConfig = { ## requires Policy = "least_request" + ChoiceCount = 2 + RingHashConfig = { ## requires Policy = "ring_hash" MinimumRingSize = 1024 MaximumRingSize = 8192 } - LeastRequestConfig = { ## requires Policy = "least_request" - ChoiceCount = 2 } HashPolicies = [ { @@ -264,13 +264,13 @@ LoadBalancer = { "LoadBalancer":{ "Policy":"random", + "LeastRequestConfig":{ // requires Policy":"least_request" + "ChoiceCount":2 + }, "RingHashConfig":{ // requires Policy":"ring_hash" "MinimumRingSize":1024, "MaximumRingSize":8192 }, - "LeastRequestConfig":{ // requires Policy":"least_request" - "ChoiceCount":2 - }, "HashPolicies":[ { "Field":"header", // cannot specify with SourceIP @@ -459,15 +459,67 @@ Specifies redirect instructions for local service traffic so that services deplo - Default: None - Data type: Map that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | - | `Service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | - | `ServiceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `Redirect` map: `Service`, `Namespace`, and`Datacenter`. | String | None | - | `Namespace` | Specifies the namespace at the redirect’s destination that resolves local upstream requests. | String | None | - | `Partition` | Specifies the admin partition at the redirect’s destination that resolves local upstream requests. | String | None | - | `Datacenter` | Specifies the datacenter at the redirect’s destination that resolves local upstream requests. | String | None | - | `Peer` | Specifies the cluster with an active cluster peering connection at the redirect’s destination that resolves local upstream requests. Requires separately defined service intentions that [authorize services for peers](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers). When Consul runs a health check before resolving requests from the peer, it does not apply health checks that were defined on the peer and exported to the local cluster through the exported services configuration entry. | String | None | + - [`Service`](#redirect-service) + - [`ServiceSubset`](#redirect-servicesubset) + - [`Namespace`](#redirect-namespace) + - [`Partition`](#redirect-partition) + - [`Datacenter`](#redirect-datacenter) + - [`Peer`](#redirect-peer) + +### `Redirect{}.Service` + +Specifies the name of a service at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + +### `Redirect{}.ServiceSubset` + +Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `Redirect` map: `Service`, `Namespace`, and`Datacenter`. + +#### Values + +- Default: None +- Data type: String + +### `Redirect{}.Namespace` + +Specifies the namespace at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + +### `Redirect{}.Partition` + +Specifies the admin partition at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + + +### `Redirect{}.Datacenter` + +Specifies the datacenter at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + +### `Redirect{}.Peer` + +Specifies the cluster with an active cluster peering connection at the redirect’s destination that resolves local upstream requests. Requires separately defined service intentions that [authorize services for peers](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers). When Consul runs a health check before resolving requests from the peer, it does not apply health checks that were defined on the peer and exported to the local cluster through the exported services configuration entry. + +#### Values + +- Default: None +- Data type: String ### `Failover` @@ -481,14 +533,47 @@ This parameter is a map, and its key is the name of the local service subset tha - Default: None - Data type: Map that can contain the following parameters: + - [`Service`](#failover-service) + - [`ServiceSubset`](#failover-servicesubset) + - [`Namespace`](#failover-namespace) + - [`Datacenters`](#failover-datacenters) + - [`Targets`](#failover-targets) - | Parameter | Description | Data type | Default | - | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | - | `Service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | - | `ServiceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`DefaultSubset`](#defaultsubset). | String | None | - | `Namespace` | Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. | String | None | - | `Datacenters` | Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. | String | None | - | `Targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`Failover{}.Targets`](#failover-targets) for configuration details. | List | None | +### `Failover{}.Service` + +Specifies the name of the service to resolve at the failover location during a failover scenario. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.ServiceSubset` + +Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`DefaultSubset`](#defaultsubset). + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Namespace` + +Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Datacenters` + +Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. + +#### Values + +- Default: None +- Data type: String ### `Failover{}.Targets` @@ -500,15 +585,66 @@ For examples, refer to the [failover example configurations](#examples-failover) - Default: None - Data type: List of maps that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | - | `Service` | Specifies the service name to use for the failover target. If empty, the current service name is used. | String | None | - | `ServiceSubset` | Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used. | String | None | - | `Namespace` | Specifies the namespace to use for the failover target. If empty, the default namespace is used. | String | None | - | `Partition` | Specifies the admin partition within the same datacenter to use for the failover target. If empty, the `default` partition is used. To use an admin partition in a different datacenter for the failover target, use the `Peer` field instead. | String | None | - | `Datacenter` | Specifies the WAN federated datacenter to use for the failover target. If empty, the current datacenter is used. To use a datacenter for the failover target that is connected with a cluster peering relationship rather than WAN federation, use the `Peer` field instead. | String | None | - | `Peer` | Specifies the destination cluster peer to resolve the target service name from. [Intentions](/consul/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) must be defined on the peered cluster so that the source service can access this failover target service as an upstream. When the peer name is specified, Consul uses Envoy's outlier detection to determine the health of the failover target based on whether services can communicate with the failover target. Consul ignores service health checks imported from a peer for failover targets because the checks do not account for service routers, splitters, and resolvers that may be defined in the peer for the target service. | String | None | + - [`Service`](#failover-targets-service) + - [`ServiceSubset`](#failover-targets-servicesubset) + - [`Namespace`](#failover-targets-namespace) + - [`Partition`](#failover-targets-partition) + - [`Datacenter`](#failover-targets-datacenter) + - [`Peer`](#failover-targets-peer) + +### `Failover{}.Targets[].Service` + +Specifies the service name to use for the failover target. If empty, the current service name is used. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Targets[].ServiceSubset` + +Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Targets[].Namespace` + +Specifies the namespace to use for the failover target. If empty, the default namespace is used. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Targets[].Partition` + +Specifies the admin partition within the same datacenter to use for the failover target. If empty, the `default` partition is used. To use an admin partition in a different datacenter for the failover target, use the `Peer` field instead. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Targets[].Datacenter` + +Specifies the WAN federated datacenter to use for the failover target. If empty, the current datacenter is used. To use a datacenter for the failover target that is connected with a cluster peering relationship rather than WAN federation, use the `Peer` field instead. + +#### Values + +- Default: None +- Data type: String + +### `Failover{}.Targets[].Peer` + +Specifies the destination cluster peer to resolve the target service name from. [Intentions](/consul/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) must be defined on the peered cluster so that the source service can access this failover target service as an upstream. When the peer name is specified, Consul uses Envoy's outlier detection to determine the health of the failover target based on whether services can communicate with the failover target. Consul ignores service health checks imported from a peer for failover targets because the checks do not account for service routers, splitters, and resolvers that may be defined in the peer for the target service. + +#### Values + +- Default: None +- Data type: String ### `LoadBalancer` @@ -518,23 +654,20 @@ Specifies the load balancing policy and configuration for services issuing reque - Default: None - Data type: Map that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | - | `Policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`LoadBalancer{}.Policy`](#loadbalancer-policy) for additional configuration parameters. | Map | None | - | `LeastRequestConfig` | Specifies configuration for the `least_request policy` type. Refer to [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig) for additional configuration parameters. | Map | None | - | `RingHashConfig` | Specifies configuration for the `ring_hash` policy type. Refer to [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig) for additional configuration parameters. | Map | None | - | `HashPolicies` | Specifies a list of hash policies to use for hashing load balancing algorithms. Refer to [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies) for additional configuration parameters. | Map | None | + - [`Policy`](#loadbalancer-policy) + - [`RingHashConfig`](#loadbalancer-ringhashconfig) + - [`LeastRequestConfig`](#loadbalancer-leastrequestconfig) + - [`HashPolicies`](#loadbalancer-hashpolicies) ### `LoadBalancer{}.Policy` Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include: -- Random -- Round robin -- Least request -- Ring hash -- Maglev +- Random: The load balancer forwards a client request to a server chosen at random from a fixed list. +- Round robin: The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. +- Least request: The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). +- Ring hash: The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). +- Maglev: The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). - Cookie - Header - Query Parameter @@ -543,17 +676,15 @@ Specifies the type of load balancing policy for selecting a host. Supported load - Default: None - Data type: String containing one of the following values: - - | Policy type | Description | - | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | - | `round_robin` | The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. | - | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). | - | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). | - | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). | - | `cookie` | x | - | `header` | x | - | `query_parameter` | x | + + - `random` + - `round_robin` + - `least_request` + - `ring_hash` + - `maglev` + - `cookie` + - `header` + - `query_parameter` ### `LoadBalancer{}.LeastRequestConfig` @@ -590,14 +721,29 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. - Default: None - Data type: List of maps for the following parameters: - - | Parameter | Description | Data type | Default | - | :------------- | :------------------------------------------------------------- | --------- | ------- | - | `Field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `Field` parameter if `SourceIP` is also configured. | String | None | - | `FieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `FieldValue` parameter if `SourceIP` is also configured. | String | None | - | `CookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`LoadBalancer{}.HashPolicies[].CookieConfig`](#loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | - | `SourceIP` | Determines if the hash type should besource IP address. You cannot specify `SourceIP` if `Field` or `FieldValue` are configured. | Boolean | `false` | - | `Terminal` | Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + - [`Field`](#loadbalancer-hashpolicies-field) + - [`FieldValue`](#loadbalancer-hashpolicies-fieldvalue) + - [`CookieConfig`](#loadbalancer-hashpolicies-cookieconfig) + - [`SourceIP`](#loadbalancer-hashpolicies-sourceip) + - [`Terminal`](#loadbalancer-hashpolicies-terminal) + +### `LoadBalancer{}.HashPolicies[].Field` + + Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `Field` parameter if `SourceIP` is also configured. + +#### Values + +- Default: None +- Data type: String + +### `LoadBalancer{}.HashPolicies[].FieldValue` + +Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `FieldValue` parameter if `SourceIP` is also configured. + +#### Values + +- Default: None +- Data type: String ### `LoadBalancer{}.HashPolicies[].CookieConfig` @@ -614,6 +760,24 @@ Specifies additional configuration options for the `cookie` hash policy type. Th | `TTL` | Specifies the TTL for generated cookies. Cannot be specified for session cookies. | String | `0s` | | `Path` | Specifies the path to set for the cookie. | String | None | +### `LoadBalancer{}.HashPolicies[].SourceIP` + +Determines if the hash type should besource IP address. You cannot specify `SourceIP` if `Field` or `FieldValue` are configured. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `LoadBalancer{}.HashPolicies[].Terminal` + + Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. + +#### Values + +- Default: `false` +- Data type: Boolean + @@ -727,15 +891,67 @@ Specifies redirect instructions for local service traffic so that services deplo - Default: None - Data type: Map that can contain the following parameters: + - [`service`](#spec-redirect-service) + - [`serviceSubset`](#spec-redirect-servicesubset) + - [`namespace`](#spec-redirect-namespace) + - [`partition`](#spec-redirect-partition) + - [`datacenter`](#spec-redirect-datacenter) + - [`peer`](#spec-redirect-peer) + +### `spec.redirect.service` + +Specifies the name of a service at the redirect’s destination that resolves local upstream requests. - | Parameter | Description | Data type | Default | - | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | - | `service` | Specifies the name of a service at the redirect’s destination that resolves local upstream requests. | String | None | - | `serviceSubset` | Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `redirect` map: `service`, `namespace`, and `datacenter`. | String | None | - | `namespace` | Specifies the namespace at the redirect’s destination that resolves local upstream requests. | String | None | - | `partition` | Specifies the admin partition at the redirect’s destination that resolves local upstream requests. | String | None | - | `datacenter` | Specifies the datacenter at the redirect’s destination that resolves local upstream requests. | String | None | - | `peer` | Specifies the cluster with an active cluster peering connection at the redirect’s destination that resolves local upstream requests. Requires separately defined service intentions that [authorize services for peers](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers). When Consul runs a health check before resolving requests from the peer, it does not apply health checks that were defined on the peer and exported to the local cluster through the exported services configuration entry. | String | None | +#### Values + +- Default: None +- Data type: String + +### `spec.redirect.serviceSubset` + +Specifies the name of a subset of services at the redirect’s destination that resolves local upstream requests. If empty, the default subset is used. If specified, you must also specify at least one of the following in the same `redirect` map: `service`, `namespace`, and`datacenter`. + +#### Values + +- Default: None +- Data type: String + +### `spec.redirect.namespace` + +Specifies the namespace at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + +### `spec.redirect.partition` + +Specifies the admin partition at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + + +### `spec.redirect.datacenter` + +Specifies the datacenter at the redirect’s destination that resolves local upstream requests. + +#### Values + +- Default: None +- Data type: String + +### `spec.redirect.peer` + +Specifies the cluster with an active cluster peering connection at the redirect’s destination that resolves local upstream requests. Requires separately defined service intentions that [authorize services for peers](/consul/docs/connect/cluster-peering/usage/establish-cluster-peering#authorize-services-for-peers). When Consul runs a health check before resolving requests from the peer, it does not apply health checks that were defined on the peer and exported to the local cluster through the exported services configuration entry. + +#### Values + +- Default: None +- Data type: String ### `spec.failover` @@ -749,14 +965,47 @@ This parameter is a map, and its key is the name of the local service subset tha - Default: None - Data type: Map that can contain the following parameters: + - [`service`](#spec-failover-service) + - [`serviceSubset`](#spec-failover-servicesubset) + - [`namespace`](#spec-failover-namespace) + - [`datacenters`](#spec-failover-datacenters) + - [`targets`](#spec-failover-targets) - | Parameter | Description | Data type | Default | - | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | - | `service` | Specifies the name of the service to resolve at the failover location during a failover scenario. | String | None | - | `serviceSubset` | Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`defaultSubset](#spec-defaultsubset). | String | None | - | `namespace` | Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. | String | None | - | `datacenters` | Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. | String | None | - | `targets` | Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. Refer to [`spec-failover.targets`](#spec-failover-targets) for configuration details. | List | None | +### `spec.failover.service` + +Specifies the name of the service to resolve at the failover location during a failover scenario. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.serviceSubset` + +Specifies the name of a subset of service instances to resolve at the failover location during a failover scenario. If empty, Consul uses the service’s [`defaultSubset`](#defaultsubset). + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.namespace` + +Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.datacenters` + +Specifies an ordered list of datacenters at the failover location to attempt connections to during a failover scenario. When Consul cannot establish a connection with the first datacenter in the list, it proceeds sequentially until establishing a connection with another datacenter. + +#### Values + +- Default: None +- Data type: String ### `spec.failover.targets` @@ -768,15 +1017,66 @@ For examples, refer to the [failover example configurations](#examples-failover) - Default: None - Data type: List of maps that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | - | `service` | Specifies the service name to use for the failover target. If empty, the current service name is used. | String | None | - | `serviceSubset` | Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used. | String | None | - | `namespace` | Specifies the namespace to use for the failover target. If empty, the default namespace is used. | String | None | - | `partition` | Specifies the admin partition within the same datacenter to use for the failover target. If empty, the `default` partition is used. To use an admin partition in a different datacenter for the failover target, use the `peer` field instead. | String | None | - | `datacenter` | Specifies the WAN federated datacenter to use for the failover target. If empty, the current datacenter is used. To use a datacenter for the failover target that is connected with a cluster peering relationship rather than WAN federation, use the `peer` field instead. | String | None | - | `peer` | Specifies the destination cluster peer to resolve the target service name from. [Intentions](/consul/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) must be defined on the peered cluster so that the source service can access this failover target service as an upstream. When the peer name is specified, Consul uses Envoy's outlier detection to determine the health of the failover target based on whether services can communicate with the failover target. Consul ignores service health checks imported from a peer for failover targets because the checks do not account for service routers, splitters, and resolvers that may be defined in the peer for the target service. | String | None | + - [`service`](#spec-failover-targets-service) + - [`serviceSubset`](#spec-failover-targets-servicesubset) + - [`namespace`](#spec-failover-targets-namespace) + - [`partition`](#spec-failover-targets-partition) + - [`datacenter`](#spec-failover-targets-datacenter) + - [`peer](#spec-failover-targets-peer) + +### `spec.failover.targets.service` + +Specifies the service name to use for the failover target. If empty, the current service name is used. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.targets.serviceSubset` + +Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.targets.namespace` + +Specifies the namespace to use for the failover target. If empty, the default namespace is used. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.targets.partition` + +Specifies the admin partition within the same datacenter to use for the failover target. If empty, the `default` partition is used. To use an admin partition in a different datacenter for the failover target, use the `peer` field instead. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.targets.datacenter` + +Specifies the WAN federated datacenter to use for the failover target. If empty, the current datacenter is used. To use a datacenter for the failover target that is connected with a cluster peering relationship rather than WAN federation, use the `peer` field instead. + +#### Values + +- Default: None +- Data type: String + +### `spec.failover.targets.peer` + +Specifies the destination cluster peer to resolve the target service name from. [Intentions](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering#authorize-services-for-peers) must be defined on the peered cluster so that the source service can access this failover target service as an upstream. When the peer name is specified, Consul uses Envoy's outlier detection to determine the health of the failover target based on whether services can communicate with the failover target. Consul ignores service health checks imported from a peer for failover targets because the checks do not account for service routers, splitters, and resolvers that may be defined in the peer for the target service. + +#### Values + +- Default: None +- Data type: String ### `spec.loadBalancer` From 4352d3f5f64a463ff1a543dcd2b12c1a2a0b8319 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 16 May 2023 09:15:30 -0700 Subject: [PATCH 21/25] final tables to sections --- .../config-entries/service-resolver.mdx | 94 ++++++++++++------- 1 file changed, 60 insertions(+), 34 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index d597e1016e0a..c8f20f620dfc 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -1086,44 +1086,37 @@ Specifies the load balancing policy and configuration for services issuing reque - Default: None - Data type: Map that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :------------- | :-------------------------------------------------------------------------------- | --------- | ------- | - | `policy` | Specifies the type of load balancing policy for selecting a host. Refer to [`spec.loadBalancer.policy`](#spec-loadbalancer-policy) for additional configuration parameters. | Map | None | - | `leastRequestConfig` | Specifies configuration for the `least_request policy` type. Refer to [`spec.loadBalancer.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig) for additional configuration parameters. | Map | None | - | `ringHashConfig` | Specifies configuration for the `ring_hash` policy type. Refer to [`spec.loadBalancer.ringHashConfig`](#spec-loadbalancer-ringhashconfig) for additional configuration parameters. | Map | None | - | `hashPolicies` | Specifies a list of hash policies to use for hashing load balancing algorithms. Refer to [`spec.loadBalancer.hashPolicies`](#spec-loadbalancer-hashpolicies) for additional configuration parameters. | Map | None | + - [`policy`](#spec-loadbalancer-policy) + - [`leastRequestConfig`](#spec-loadbalancer-leastrequestconfig) + - [`ringHashConfig`](#spec-loadbalancer-ringhashconfig) + - [`hashPolicies`](#spec-loadbalancer-hashpolicies) ### `spec.loadBalancer.policy` Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include: -- Random -- Round robin -- Least request -- Ring hash -- Maglev +- Random: The load balancer forwards a client request to a server chosen at random from a fixed list. +- Round robin: The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. +- Least request: The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). +- Ring hash: The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). +- Maglev: The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). - Cookie - Header -- Query parameter +- Query Parameter #### Values - Default: None - Data type: String containing one of the following values: - - | Policy type | Description | - | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `random` | The load balancer forwards a client request to a server chosen at random from a fixed list. | - | `round_robin` | The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. | - | `least_request` | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`spec.loadBalancer.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig). | - | `ring_hash` | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.ringHashConfig`](#spec-loadbalancer-ringhashconfig). | - | `maglev` | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.hashPolicies`](#spec-loadbalancer-hashpolicies). | - | `cookie` | description | - | `header` | description | - | `query_param` | description | - + - `random` + - `round_robin` + - `least_request` + - `ring_hash` + - `maglev` + - `cookie` + - `header` + - `query_parameter` ### `spec.loadBalancer.leastRequestConfig` @@ -1160,16 +1153,31 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. - Default: None - Data type: List that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :------------- | :------------------------------------------------------------- | --------- | ------- | - | `field` | Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `field` parameter if `sourceIP` is also configured. | String | None | - | `fieldValue` | Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `fieldValue` parameter if `sourceIP` is also configured. | String | None | - | `cookieConfig` | Specifies additional configuration options for the `cookie` hash policy type. Refer to [`spec.loadBalancer.hashPolicies[].cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig) for additional configuration parameters. | Map | None | - | `sourceIP` | Determines if the hash type should besource IP address. You cannot specify `sourceIP` if `field` or `fieldValue` are configured. | Boolean | `false` | - | `terminal` | Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. | Boolean | `false` | + - [`field`](#spec-loadbalancer-hashpolicies-field) + - [`fieldValue`](#spec-loadbalancer-hashpolicies-fieldvalue) + - [`cookieConfig`](#spec-loadbalancer-hashpolicies-cookieconfig) + - [`sourceIP`](#spec-loadbalancer-hashpolicies-sourceip) + - [`terminal`](#spec-loadbalancer-hashpolicies-terminal) + +### `spec.loadBalancer.hashPolicies[].field` + + Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `field` parameter if `sourceIP` is also configured. + +#### Values -### `spec.loadBalancer{}.hashPolicies[].cookieConfig` +- Default: None +- Data type: String + +### `spec.loadBalancer.hashPolicies[].fieldValue` + +Specifies the value to hash, such as a header name, cookie name, or a URL query parameter name. You cannot specify the `fieldValue` parameter if `sourceIP` is also configured. + +#### Values + +- Default: None +- Data type: String + +### `spec.loadBalancer.hashPolicies[].cookieConfig` Specifies additional configuration options for the `cookie` hash policy type. This field causes Envoy to generate a cookie for a client on its first request. @@ -1184,6 +1192,24 @@ Specifies additional configuration options for the `cookie` hash policy type. Th | `ttl` | Specifies the TTL for generated cookies. Cannot be specified for session cookies. | String | `0s` | | `path` | Specifies the path to set for the cookie. | String | None | +### `spec.loadBalancer.hashPolicies[].sourceIP` + +Determines if the hash type should besource IP address. You cannot specify `sourceIP` if `field` or `fieldValue` are configured. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.loadBalancer.hashPolicies[].terminal` + +Determines if Consul should stop computing the hash when multiple hash policies are present. If a hash is computed when a terminal policy is evaluated, then that hash is used and subsequent hash policies are ignored. + +#### Values + +- Default: `false` +- Data type: Boolean + From 2aac088a664fbb00d430572f1a23337f5fc6784d Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 16 May 2023 10:21:34 -0700 Subject: [PATCH 22/25] Adjustments/alignments --- .../config-entries/service-resolver.mdx | 77 +++++++------ .../connect/config-entries/service-router.mdx | 102 ++++++++++++------ 2 files changed, 114 insertions(+), 65 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index c8f20f620dfc..736c976c56b0 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -52,7 +52,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`LoadBalancer`](#loadbalancer): map - [`Policy`](#loadbalancer-policy): string - [`LeastRequestConfig`](#loadbalancer-leastrequestconfig): map - - [`ChoiceCount`](#loadbalancer-leastrequestconfig-choicecount): integer `2` + - [`ChoiceCount`](#loadbalancer-leastrequestconfig-choicecount): integer | `2` - [`RingHashConfig`](#loadbalancer-ringhashconfig): map - [`MinimumRingSize`](#loadbalancer-ringhashconfig): integer | `1024` - [`MaximumRingSize`](#loadbalancer-ringhashconfig): integer | `8192` @@ -579,7 +579,7 @@ Specifies an ordered list of datacenters at the failover location to attempt con Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. -For examples, refer to the [failover example configurations](#examples-failover). +For examples, refer to the [failover example configurations](#service-failover). #### Values @@ -663,14 +663,14 @@ Specifies the load balancing policy and configuration for services issuing reque Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include: -- Random: The load balancer forwards a client request to a server chosen at random from a fixed list. -- Round robin: The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. -- Least request: The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). -- Ring hash: The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). -- Maglev: The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). -- Cookie -- Header -- Query Parameter +| Policy | Description | +| :----- | :-------------------------------------------------------------- | +| Random | The load balancer forwards a client request to an available server chosen at random from a fixed list. | +| Round robin | The load balancer proceeds through a fixed list of servers and forwards a client request to each available server in order. | +| Least request | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). | +| Ring hash | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). | +| Maglev | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). | + #### Values @@ -682,9 +682,6 @@ Specifies the type of load balancing policy for selecting a host. Supported load - `least_request` - `ring_hash` - `maglev` - - `cookie` - - `header` - - `query_parameter` ### `LoadBalancer{}.LeastRequestConfig` @@ -729,12 +726,23 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. ### `LoadBalancer{}.HashPolicies[].Field` - Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `Field` parameter if `SourceIP` is also configured. + Specifies the attribute type to hash on. You cannot specify the `Field` parameter if `SourceIP` is also configured. + + Supported attribute types include the following: + +| Attribute | Description | +| :--------- | :-------------------------------------------------------------- | +| Cookie | The load balancer uses a cookie to obtain a hash key. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-cookie) for more information. | +| Header | The load balancer uses a request header to obtain a hash key. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-header) for more information. | +| Query Parameter | The load balancer uses a URL query parameter to obtain the hash key. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-queryparameter) for more information. | #### Values - Default: None -- Data type: String +- Data type: String containing one of the following values: + - `cookie` + - `header` + - `query_parameter` ### `LoadBalancer{}.HashPolicies[].FieldValue` @@ -1011,7 +1019,7 @@ Specifies an ordered list of datacenters at the failover location to attempt con Specifies a fixed list of failover targets to try during failover. This list can express complicated failover scenarios. -For examples, refer to the [failover example configurations](#examples-failover). +For examples, refer to the [failover example configurations](#service-failover). #### Values @@ -1095,14 +1103,13 @@ Specifies the load balancing policy and configuration for services issuing reque Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include: -- Random: The load balancer forwards a client request to a server chosen at random from a fixed list. -- Round robin: The load balancer proceeds through a fixed list of servers and forwards a client request to each one in order. -- Least request: The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`LoadBalancer{}.LeastRequestConfig`](#loadbalancer-leastrequestconfig). -- Ring hash: The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.RingHashConfig`](#loadbalancer-ringhashconfig). -- Maglev: The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`LoadBalancer{}.HashPolicies`](#loadbalancer-hashpolicies). -- Cookie -- Header -- Query Parameter +| Policy | Description | +| :----- | :-------------------------------------------------------------- | +| Random | The load balancer forwards a client request to an available server chosen at random from a fixed list. | +| Round robin | The load balancer proceeds through a fixed list of servers and forwards a client request to each available server in order. | +| Least request | The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in [`spec.loadBalancer.leastRequestConfig`](#spec-loadbalancer-leastrequestconfig). | +| Ring hash | The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.ringHashConfig`](#spec-loadbalancer-ringhashconfig). | +| Maglev | The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in [`spec.loadBalancer.hashPolicies`](#spec-loadbalancer-hashpolicies). | #### Values @@ -1113,10 +1120,7 @@ Specifies the type of load balancing policy for selecting a host. Supported load - `round_robin` - `least_request` - `ring_hash` - - `maglev` - - `cookie` - - `header` - - `query_parameter` + - `maglev` ### `spec.loadBalancer.leastRequestConfig` @@ -1161,12 +1165,23 @@ Specifies a list of hash policies to use for hashing load balancing algorithms. ### `spec.loadBalancer.hashPolicies[].field` - Specifies the attribute type to hash on. Must be one of the following values: `header`, `cookie`, or `query_parameter`. You cannot specify the `field` parameter if `sourceIP` is also configured. + Specifies the attribute type to hash on. You cannot specify the `field` parameter if `sourceIP` is also configured. + +Supported attribute types include the following: + +| Attribute | Description | +| :--------- | :-------------------------------------------------------------- | +| Cookie | The load balancer uses a cookie to obtain a hash key. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-cookie) for more information. | +| Header | The load balancer uses a request header to obtain a hash key. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-header) for more information. | +| Query Parameter | The load balancer uses a URL query parameter to obtain the hash key. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-queryparameter) for more information. | #### Values - Default: None -- Data type: String +- Data type: String containing one of the following values: + - `cookie` + - `header` + - `query_parameter` ### `spec.loadBalancer.hashPolicies[].fieldValue` @@ -1328,7 +1343,7 @@ spec: -### Failover +### Service failover The following example enables failover for subset `v2` to `dc2`. All other subsets attempt failover to `dc3`, and when it is not available, to `dc4`: diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 8bba32d67da9..ca205ed867ef 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -372,7 +372,7 @@ Specifies a name for the configuration entry. The name is metadata that you can ### `Namespace` -Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry to. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for additional information about Consul namespaces. +Specifies the namespace to apply the configuration entry to. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for additional information about Consul namespaces. #### Values @@ -381,7 +381,7 @@ Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the confi ### `Partition` -Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to apply the configuration entry to. Refer to [Admin partitions](/consul/docs/enterprise/admin-partitions) for additional information. +Specifies the admin partition to apply the configuration entry to. Refer to [Admin partitions](/consul/docs/enterprise/admin-partitions) for additional information. #### Values @@ -469,10 +469,12 @@ Specifies a regular expression to match on the HTTP request path. When using thi Specifies HTTP methods that the match applies to. If not specified, the request matches on all HTTP methods. If provided, the name must be a valid method formatted as a string. +String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). + #### Values - Default: None -- Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): +- Data type: List of strings. Each string must match one of the following values: - `GET` - `HEAD` - `POST` @@ -723,27 +725,42 @@ Specifies that connection failure errors that trigger a retry request. Configure ### `Routes[].Destination{}.RetryOn[]` -Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `Destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). +Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. Configure this field and other retry fields in the `Destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +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`. | +| `resource-exhausted` | 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: -| Conditions | Description | -| :------------------- | :--------------------------------------------------------------------------------------------------- | -| `5xx` | Consul encountered a 5xx HTTP response code error code while routing the request. | -| `gateway-error` | Consul encountered a gateway error while routing the request. | -| `reset` | The Consul server was reset while routing the request. | -| `connect-failure` | Consul encountered a service mesh failure while routing the request. | -| `envoy-ratelimited` | An Envoy proxy did not complete the request because it was rate limited. | -| `retriable-4xx` | Consul encountered a retriable 4xx HTTP response code while routing the request. | -| `refused-stream` | An upstream service refused the connection while Consul was routing the request. | -| `cancelled` | The request was canceled while Consul was routing it. | -| `deadline-exceeded` | Consul did not receive a response that the request was routed within the configured timeout period. | -| `internal` | Consul encountered an internal error while routing the request. | -| `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | -| `unavailable` | Consul was unavailable to route the request when it was made. | + - `5xx` + - `gateway-error` + - `reset` + - `connect-failure` + - `envoy-ratelimited` + - `retriable-4xx` + - `refused-stream` + - `cancelled` + - `deadline-exceeded` + - `internal` + - `resource-exhausted` + - `unavailable` ### `Routes[].Destination{}.RetryOnStatusCodes` @@ -929,10 +946,12 @@ Specifies a regular expression to match on the HTTP request path. When using thi Specifies HTTP methods that the match applies to. If not specified, the request matches on all HTTP methods. If provided, the name must be a valid method formatted as a string. +String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). + #### Values - Default: None -- Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): +- Data type: List of strings. Each string must match one of the following values: - `GET` - `HEAD` - `POST` @@ -1182,27 +1201,42 @@ Specifies that connection failure errors that trigger a retry request. Configure ### `spec.routes[].destination.retryOn` -Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `spec.routes[].destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). +Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. Configure this field and other retry fields in the `spec.routes[].destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +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`. | +| `resource-exhausted` | 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: -| Conditions | Description | -| :------------------- | :--------------------------------------------------------------------------------------------------- | -| `5xx` | Consul encountered a 5xx HTTP response code error code while routing the request. | -| `gateway-error` | Consul encountered a gateway error while routing the request. | -| `reset` | The Consul server was reset while routing the request. | -| `connect-failure` | Consul encountered a service mesh failure while routing the request. | -| `envoy-ratelimited` | An Envoy proxy did not complete the request because it was rate limited. | -| `retriable-4xx` | Consul encountered a retriable 4xx HTTP response code while routing the request. | -| `refused-stream` | An upstream service refused the connection while Consul was routing the request. | -| `cancelled` | The request was canceled while Consul was routing it. | -| `deadline-exceeded` | Consul did not receive a response that the request was routed within the configured timeout period. | -| `internal` | Consul encountered an internal error while routing the request. | -| `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | -| `unavailable` | Consul was unavailable to route the request when it was made. | + - `5xx` + - `gateway-error` + - `reset` + - `connect-failure` + - `envoy-ratelimited` + - `retriable-4xx` + - `refused-stream` + - `cancelled` + - `deadline-exceeded` + - `internal` + - `resource-exhausted` + - `unavailable` ### `spec.routes[].destination.retryOnStatusCodes` From 3ab7a3a677d8f45a5514b9bd75ef92e23bd93961 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 16 May 2023 10:29:20 -0700 Subject: [PATCH 23/25] nanosecond fix --- .../docs/connect/config-entries/service-resolver.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 736c976c56b0..d7ff0e36d9c3 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -410,7 +410,7 @@ Specifies key-value pairs to add to the KV store. ### `ConnectTimeout` -Specifies the timeout duration for establishing new network connections to this service. The duration is measured in seconds. +Specifies the timeout duration for establishing new network connections to this service. By default, the duration is measured in nanoseconds (ns). #### Values @@ -419,7 +419,7 @@ Specifies the timeout duration for establishing new network connections to this ### `RequestTimeout` -Specifies the timeout duration for receiving an HTTP response from this service, measured in seconds. When set to `0s`, the default value of `15s` is used instead. +Specifies the timeout duration for receiving an HTTP response from this service. When set to `0s`, the default value of `15s` is used instead. By default, the duration is measured in nanoseconds (ns). #### Values @@ -850,7 +850,7 @@ Map that contains the details about the `ServiceResolver` configuration entry. T ### `spec.connectTimeout` -Specifies the timeout duration for establishing new network connections to this service. The duration is measured in seconds. +Specifies the timeout duration for establishing new network connections to this service. By default, the duration is measured in nanoseconds (ns). #### Values @@ -859,7 +859,7 @@ Specifies the timeout duration for establishing new network connections to this ### `spec.requestTimeout` -Specifies the timeout duration for receiving an HTTP response from this service, measured in seconds. When set to `0s`, the default value of `15s` is used instead. +Specifies the timeout duration for receiving an HTTP response from this service. When set to `0s`, the default value of `15s` is used instead. By default, the duration is measured in nanoseconds (ns). #### Values From 807295144bd3fc40962f5813ef90bfe88e952bdf Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Wed, 17 May 2023 13:22:25 -0700 Subject: [PATCH 24/25] Update website/content/docs/connect/config-entries/service-router.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/connect/config-entries/service-router.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index ca205ed867ef..4362925f59fb 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -77,7 +77,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`spec`](#spec): map | required - [`routes`](#spec-routes): list - [`match`](#spec-routes-match): map - - [‘http`](#spec-routes-match-http): map + - [`http`](#spec-routes-match-http): map - [`pathExact`](#spec-routes-match-http-pathexact): string - [`pathPrefix`](#spec-routes-match-http-pathprefix): string - [`pathRegex`](#spec-routes-match-http-pathregex): string From ab1eb06a846154a4a62a098c3d82989c01f48ee7 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 17 May 2023 13:30:35 -0700 Subject: [PATCH 25/25] link to filter example config --- .../docs/connect/config-entries/service-resolver.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index d7ff0e36d9c3..dcea59805499 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -430,6 +430,8 @@ Specifies the timeout duration for receiving an HTTP response from this service. Specifies names for custom service subsets and the conditions under which service instances belong to each subset. Define a subset by specifying a key and a value where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If this parameter is not specified, only the unnamed default subset is usable. +For additional guidance, refer to the [filter on service version configuration example](#filter-on-service-version). + #### Values - Default: None @@ -870,6 +872,8 @@ Specifies the timeout duration for receiving an HTTP response from this service. Specifies names for custom service subsets and the conditions under which service instances belong to each subset. Define a subset by specifying a key and a value where the key is the subset’s name and the value is a map that contains a [filtering expression](/consul/api-docs/features/filtering). If this parameter is not specified, only the unnamed default subset is usable. +For additional guidance, refer to the [filter on service version configuration example](#filter-on-service-version). + #### Values - Default: None @@ -1234,7 +1238,7 @@ The following examples demonstrate common service resolver configuration pattern ### Filter on service version -The following example creates two subsets of the `web` service and assigns service instances to subsets based on each instance's version metadata. It also defined `v1` as the default subset. +The following example creates two subsets of the `web` service and assigns service instances to subsets based on each instance's version metadata. It also defines `v1` as the default subset.