mirror of https://github.com/hashicorp/consul
1732 lines
59 KiB
Markdown
1732 lines
59 KiB
Markdown
---
|
||
layout: docs
|
||
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 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.
|
||
|
||
Refer to [L7 traffic management overview](/consul/docs/connect/manage-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.
|
||
|
||
<Tabs>
|
||
|
||
<Tab heading="HCL and JSON" group="hcl">
|
||
|
||
- [`Kind`](#kind): string | required | must be set to `service-resolver`
|
||
- [`Name`](#name): string | required
|
||
- [`Namespace`](#namespace): string | `default` <EnterpriseAlert inline />
|
||
- [`Partition`](#partition): string | `default` <EnterpriseAlert inline />
|
||
- [`Meta`](#meta): map
|
||
- [`ConnectTimeout`](#connecttimeout): string | `0s`
|
||
- [`RequestTimeout`](#requesttimeout): string | `15s`
|
||
- [`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 <EnterpriseAlert inline />
|
||
- [`Partition`](#redirect-partition): string | `default` <EnterpriseAlert inline />
|
||
- [`SamenessGroup`](#redirect-samenessgroup): string <EnterpriseAlert inline />
|
||
- [`Datacenter`](#redirect-datacenter): string
|
||
- [`Peer`](#redirect-peer): string
|
||
- [`PrioritizeByLocality`](#prioritizebylocality): map <EnterpriseAlert inline/>
|
||
- [`Mode`](#prioritizebylocality): string | `failover`
|
||
- [`Failover`](#failover): map
|
||
- [`Service`](#failover-service): string
|
||
- [`ServiceSubset`](#failover-servicesubset): string
|
||
- [`Namespace`](#failover-namespace): string <EnterpriseAlert inline />
|
||
- [`SamenessGroup`](#failover-samenessgroup): string <EnterpriseAlert inline />
|
||
- [`Datacenters`](#failover-datacenters): list
|
||
- [`Targets`](#failover-targets): list
|
||
- [`Service`](#failover-targets-service): string
|
||
- [`ServiceSubset`](#failover-targets-servicesubset): string
|
||
- [`Namespace`](#failover-targets-namespace): string <EnterpriseAlert inline />
|
||
- [`Partition`](#failover-targets-partition): string | `default` <EnterpriseAlert inline />
|
||
- [`Datacenter`](#failover-targets-datacenter): string
|
||
- [`Peer`](#failover-targets-peer): string
|
||
- [`LoadBalancer`](#loadbalancer): map
|
||
- [`Policy`](#loadbalancer-policy): string
|
||
- [`LeastRequestConfig`](#loadbalancer-leastrequestconfig): map
|
||
- [`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
|
||
- [`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`
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
- [`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 <EnterpriseAlert inline />
|
||
- [`spec`](#spec): map | required
|
||
- [`connectTimeout`](#spec-connecttimeout): string | `0s`
|
||
- [`requestTimeout`](#spec-requesttimeout): string | `15s`
|
||
- [`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 <EnterpriseAlert inline />
|
||
- [`partition`](#spec-redirect-partition): string <EnterpriseAlert inline />
|
||
- [`samenessGroup`](#spec-redirect-samenessgroup): string <EnterpriseAlert inline />
|
||
- [`datacenter`](#spec-redirect-datacenter): string
|
||
- [`peer`](#spec-redirect-peer): string
|
||
- [`prioritizeByLocality`](#spec-prioritizebylocality): map | <EnterpriseAlert inline/>
|
||
- [`mode`](#spec-prioritizebylocality): string | `failover`
|
||
- [`failover`](#spec-failover): map
|
||
- [`service`](#spec-failover-service): string
|
||
- [`serviceSubset`](#spec-failover-servicesubset): string
|
||
- [`namespace`](#spec-failover-namespace): string <EnterpriseAlert inline />
|
||
- [`samenessGroup`](#spec-failover-samenessgroup): string <EnterpriseAlert inline />
|
||
- [`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` <EnterpriseAlert inline />
|
||
- [`partition`](#spec-failover-targets-partition): string | `default` <EnterpriseAlert inline />
|
||
- [`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): integer | `2`
|
||
- [`ringHashConfig`](#spec-loadbalancer-ringhashconfig): map
|
||
- [`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
|
||
- [`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`
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## Complete configuration
|
||
|
||
When every field is defined, a service resolver configuration entry has the following form:
|
||
|
||
<Tabs>
|
||
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver" ## required
|
||
Name = "<name-of-service-configuration-applies-to>"
|
||
Namespace = "<namespace-configuration-applies-to>"
|
||
Partition = "<partition-configuration-applies-to>"
|
||
Meta = {
|
||
<key> = "<value>"
|
||
}
|
||
|
||
ConnectTimeout = "10s"
|
||
RequestTimeout = "15s"
|
||
Subsets = {
|
||
<subset01-name> = {
|
||
Filter = "<expression.to.match.on == value01>"
|
||
OnlyPassing = true
|
||
}
|
||
<subset02-name> = {
|
||
Filter = "<expression.to.match.on == value02>"
|
||
OnlyPassing = true
|
||
}
|
||
}
|
||
DefaultSubset = "<subset01-name>"
|
||
|
||
Redirect = {
|
||
Service = "<destination-service>"
|
||
ServiceSubset = "<destination-subset>"
|
||
Namespace = "<destination-namespace>"
|
||
Partition = "<destination-partition>"
|
||
SamenessGroup = "<destination-sameness-group>"
|
||
Datacenter = "<destination-datacenter>"
|
||
Peer = "<destination-peer>"
|
||
}
|
||
|
||
PrioritizeByLocality = {
|
||
Mode = "failover"
|
||
}
|
||
|
||
Failover = { ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup
|
||
<local-subset-name> = {
|
||
Targets = [
|
||
{ Service = "<destination-service>" },
|
||
{ ServiceSubset = "<destination-service-subset>" },
|
||
{ Namespace = "<destination-namespace>" },
|
||
{ Partition = "<destination-partition>" },
|
||
{ Datacenter = "<destination-datacenter>" },
|
||
{ Peer = "<destination-peer>" }
|
||
]
|
||
}
|
||
"*" = {
|
||
Service = "<destination-service>"
|
||
ServiceSubset = "<destination-service-subset>"
|
||
Namespace = "<destination-namespace>"
|
||
Datacenters = ["<destination-datacenter-01>", "<destination-datacenter-02>"]
|
||
}
|
||
}
|
||
|
||
LoadBalancer = {
|
||
Policy = "random"
|
||
LeastRequestConfig = { ## requires Policy = "least_request"
|
||
ChoiceCount = 2
|
||
}
|
||
RingHashConfig = { ## requires Policy = "ring_hash"
|
||
MinimumRingSize = 1024
|
||
MaximumRingSize = 8192
|
||
}
|
||
HashPolicies = [
|
||
{
|
||
Field = "header" ## cannot specify with SourceIP
|
||
FieldValue = "<value-to-hash>" ## cannot specify with SourceIP
|
||
CookieConfig = {
|
||
Session = false
|
||
TTL = "0s"
|
||
Path = "<path/to/cookie>"
|
||
}
|
||
SourceIP = false ## cannot specify with Field or FieldValue
|
||
Terminal = false
|
||
}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind":"service-resolver", // required
|
||
"Name":"<name-of-service-configuration-applies-to>",
|
||
"Namespace":"<namespace-configuration-applies-to>",
|
||
"Partition":"partition-configuration-applies-to>",
|
||
"Meta":{
|
||
"<key>":"<value>"
|
||
},
|
||
|
||
"ConnectTimeout":"10s",
|
||
"RequestTimeout":"15s",
|
||
"Subsets":{
|
||
"<subset01-name>":{
|
||
"Filter":"<expression.to.match.on == value01",
|
||
"OnlyPassing":true
|
||
},
|
||
"<subset02-name>":{
|
||
"Filter":"<expression.to.match.on == value02>",
|
||
"OnlyPassing":true
|
||
}
|
||
},
|
||
"DefaultSubset ":"<subset01-name>",
|
||
"Redirect":{
|
||
"Service":"<destination-service>",
|
||
"ServiceSubset":"<destination-subset>",
|
||
"Namespace":"<destination-namespace>",
|
||
"Partition":"<destination-partition>",
|
||
"SamenessGroup":"<destination-sameness-group>",
|
||
"Datacenter":"<destination-datacenter>",
|
||
"Peer":"<destination-peer>"
|
||
},
|
||
"PrioritizeByLocality" : {
|
||
"Mode": "failover"
|
||
},
|
||
"Failover":{ // requires at least one of the following": Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup
|
||
"<local=subset-name>":{
|
||
"Targets":[
|
||
{"Service":"<destination-service>"},
|
||
{"ServiceSubset":"<destination-service-subset>"},
|
||
{"Namespace":"<destination-namespace>"},
|
||
{"Partition":"<destination-partition>"},
|
||
{"Datacenter":"<destination-datacenter>"},
|
||
{"Peer":"<destination-peer>"}
|
||
]
|
||
},
|
||
"*":{
|
||
"Service ":"<destination-service>",
|
||
"ServiceSubset":"<destination-service-subset>",
|
||
"Namespace":"<destination-namespace>",
|
||
"Datacenters":["<destination-datacenter-01>", "<destination-datacenter-02>"]
|
||
}
|
||
},
|
||
|
||
"LoadBalancer":{
|
||
"Policy":"random",
|
||
"LeastRequestConfig":{ // requires Policy":"least_request"
|
||
"ChoiceCount":2
|
||
},
|
||
"RingHashConfig":{ // requires Policy":"ring_hash"
|
||
"MinimumRingSize":1024,
|
||
"MaximumRingSize":8192
|
||
},
|
||
"HashPolicies":[
|
||
{
|
||
"Field":"header", // cannot specify with SourceIP
|
||
"FieldValue":"<value-to-hash>", // cannot specify with SourceIP
|
||
"CookieConfig":{
|
||
"Session":false,
|
||
"TTL":"0s",
|
||
"Path":"<path/to/cookie>"
|
||
},
|
||
"SourceIP":false, // cannot specify with Field or FieldValue
|
||
"Terminal":false
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1 # required
|
||
kind: ServiceResolver # required
|
||
metadata:
|
||
name: <serviceName>
|
||
namespace: <namespace>
|
||
spec:
|
||
connectTimeout: 10s
|
||
requestTimeout: 15s
|
||
subsets:
|
||
<subset01Name>:
|
||
filter: <expression.to.match.on == value01>
|
||
onlyPassing: false
|
||
<subset02Name>:
|
||
filter: <expression.to.match.on == value02>
|
||
onlyPassing: false
|
||
defaultSubset: <definedSubsetName>
|
||
redirect:
|
||
service: <serviceName>
|
||
servicesubset: <subsetName>
|
||
namespace: <namespaceName>
|
||
partition: <partitionName>
|
||
samenessGroup: <samenessGroupName>
|
||
peer: <peerName>
|
||
prioritizeByLocality:
|
||
mode: failover
|
||
failover: # requires at least one of the following: service, serviceSubset, namespace, targets, datacenters, samenessGroup
|
||
<localSubsetName>:
|
||
targets:
|
||
- service: <serviceName>
|
||
- serviceSubset: <serviceSubset>
|
||
- namespace: <namespaceName>
|
||
- partition: <partitionName>
|
||
- datacenter: <datacenterName>
|
||
- peer: <peerName>
|
||
`*`: <namespaceName>
|
||
service: <serviceName>
|
||
serviceSubset: <serviceSubset>
|
||
namespace: <namespaceName>
|
||
datacenters: ["<destinationDatacenter01>", "<destinationDatacenter02>"]
|
||
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: <valueToHashOn> # cannot specify with SourceIP
|
||
- cookieConfig:
|
||
session: false
|
||
ttl: 0s
|
||
path: <path/to/cookie>
|
||
- sourceIP: false # cannot specify with field or fieldValue
|
||
- terminal: false
|
||
```
|
||
|
||
</Tab>
|
||
|
||
</Tabs>
|
||
|
||
## Specification
|
||
|
||
This section provides details about the fields you can configure in the configuration entry.
|
||
|
||
<Tabs>
|
||
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
### `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` <EnterpriseAlert inline />
|
||
|
||
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` <EnterpriseAlert inline />
|
||
|
||
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
|
||
- `<KEY>`: String
|
||
- `<VALUE>`: String or integer
|
||
|
||
### `ConnectTimeout`
|
||
|
||
Specifies the timeout duration for establishing new network connections to this service. By default, the duration is measured in nanoseconds (ns).
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `RequestTimeout`
|
||
|
||
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
|
||
|
||
- Default: `15s`
|
||
- Data type: String
|
||
|
||
### `Subsets`
|
||
|
||
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
|
||
- Data type: Map containing a key-value pair.
|
||
- `<KEY>`: String that names the subset. The string must be valid as a DNS subdomain element.
|
||
- `<VALUE>`: 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). 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`
|
||
|
||
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
|
||
|
||
- 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 parameters:
|
||
- [`Service`](#redirect-service)
|
||
- [`ServiceSubset`](#redirect-servicesubset)
|
||
- [`Namespace`](#redirect-namespace)
|
||
- [`Partition`](#redirect-partition)
|
||
- [`SamenessGroup`](#redirect-samenessgroup)
|
||
- [`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` <EnterpriseAlert inline />
|
||
|
||
Specifies the namespace at the redirect’s destination that resolves local upstream requests.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `Redirect{}.Partition` <EnterpriseAlert inline />
|
||
|
||
Specifies the admin partition at the redirect’s destination that resolves local upstream requests.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `Redirect{}.SamenessGroup` <EnterpriseAlert inline />
|
||
|
||
Specifies the sameness group 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
|
||
|
||
### `PrioritizeByLocality`
|
||
|
||
Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the `mode` field:
|
||
|
||
- `failover`: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching `Locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: Map
|
||
|
||
### `Failover`
|
||
|
||
Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails.
|
||
|
||
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`, `SamenessGroup`, and `Datacenters` cannot all be empty at the same time.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: Map that can contain the following parameters:
|
||
- [`Service`](#failover-service)
|
||
- [`ServiceSubset`](#failover-servicesubset)
|
||
- [`Namespace`](#failover-namespace)
|
||
- [`SamenessGroup`](#failover-samenessgroup)
|
||
- [`Datacenters`](#failover-datacenters)
|
||
- [`Targets`](#failover-targets)
|
||
|
||
### `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` <EnterpriseAlert inline />
|
||
|
||
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{}.SamenessGroup` <EnterpriseAlert inline />
|
||
|
||
Specifies the sameness group at the failover location where the failover services are deployed.
|
||
|
||
#### 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`
|
||
|
||
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](#service-failover).
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: List of maps that can contain the following parameters:
|
||
- [`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` <EnterpriseAlert inline />
|
||
|
||
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` <EnterpriseAlert inline />
|
||
|
||
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`
|
||
|
||
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:
|
||
- [`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:
|
||
|
||
| 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
|
||
|
||
- Default: None
|
||
- Data type: String containing one of the following values:
|
||
|
||
- `random`
|
||
- `round_robin`
|
||
- `least_request`
|
||
- `ring_hash`
|
||
- `maglev`
|
||
|
||
### `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` |
|
||
|
||
### `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` |
|
||
|
||
### `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:
|
||
- [`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. 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 containing one of the following values:
|
||
- `cookie`
|
||
- `header`
|
||
- `query_parameter`
|
||
|
||
### `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`
|
||
|
||
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 |
|
||
|
||
### `LoadBalancer{}.HashPolicies[].SourceIP`
|
||
|
||
Determines if the hash type should be source 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
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
### `apiVersion`
|
||
|
||
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- This field is required.
|
||
- String value that must be set to `consul.hashicorp.com/v1alpha1`.
|
||
|
||
### `kind`
|
||
|
||
Specifies the type of configuration entry to implement. Must be set to `ServiceResolver`.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- This field is required.
|
||
- Data type: String value that must be set to `ServiceResolver`.
|
||
|
||
## `metadata`
|
||
|
||
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`<EnterpriseAlert inline />
|
||
|
||
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 `ServiceResolver` 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. By default, the duration is measured in nanoseconds (ns).
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `spec.requestTimeout`
|
||
|
||
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
|
||
|
||
- Default: `15s`
|
||
- Data type: String
|
||
|
||
### `spec.subsets`
|
||
|
||
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
|
||
- Data type: Map containing a key-value pair.
|
||
- `<KEY>`: String that names the subset. The string must be valid as a DNS subdomain element.
|
||
- `<VALUE>`: 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). 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`
|
||
|
||
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
|
||
|
||
- 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 parameters:
|
||
- [`service`](#spec-redirect-service)
|
||
- [`serviceSubset`](#spec-redirect-servicesubset)
|
||
- [`namespace`](#spec-redirect-namespace)
|
||
- [`partition`](#spec-redirect-partition)
|
||
- [`samenessGroup`](#spec-redirect-samenessgroup)
|
||
- [`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.
|
||
|
||
#### 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` <EnterpriseAlert inline />
|
||
|
||
Specifies the namespace at the redirect’s destination that resolves local upstream requests.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `spec.redirect.partition` <EnterpriseAlert inline />
|
||
|
||
Specifies the admin partition at the redirect’s destination that resolves local upstream requests.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `spec.redirect.samenessGroup` <EnterpriseAlert inline />
|
||
|
||
Specifies the sameness group 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.prioritizeByLocality`
|
||
|
||
Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the `mode` field:
|
||
|
||
- `failover`: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching `locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: Map
|
||
|
||
### `spec.failover`
|
||
|
||
Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails.
|
||
|
||
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`, `samenessGroup`, and `datacenters` cannot all be empty at the same time.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: Map that can contain the following parameters:
|
||
- [`service`](#spec-failover-service)
|
||
- [`serviceSubset`](#spec-failover-servicesubset)
|
||
- [`namespace`](#spec-failover-namespace)
|
||
- [`samenessGroup`](#spec-failover-samenessgroup)
|
||
- [`datacenters`](#spec-failover-datacenters)
|
||
- [`targets`](#spec-failover-targets)
|
||
|
||
### `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` <EnterpriseAlert inline />
|
||
|
||
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.samenessGroup` <EnterpriseAlert inline />
|
||
|
||
Specifies the sameness group at the failover location where the failover services are deployed.
|
||
|
||
#### 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`
|
||
|
||
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](#service-failover).
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: List of maps that can contain the following parameters:
|
||
- [`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` <EnterpriseAlert inline />
|
||
|
||
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` <EnterpriseAlert inline />
|
||
|
||
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`
|
||
|
||
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:
|
||
- [`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:
|
||
|
||
| 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
|
||
|
||
- Default: None
|
||
- Data type: String containing one of the following values:
|
||
|
||
- `random`
|
||
- `round_robin`
|
||
- `least_request`
|
||
- `ring_hash`
|
||
- `maglev`
|
||
|
||
### `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:
|
||
- [`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. 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 containing one of the following values:
|
||
- `cookie`
|
||
- `header`
|
||
- `query_parameter`
|
||
|
||
### `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.
|
||
|
||
#### 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 |
|
||
|
||
### `spec.loadBalancer.hashPolicies[].sourceIP`
|
||
|
||
Determines if the hash type should be source 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
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## Examples
|
||
|
||
The following examples demonstrate common service resolver configuration patterns for specific use cases.
|
||
|
||
### 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 defines `v1` as the default subset.
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "web"
|
||
DefaultSubset = "v1"
|
||
Subsets = {
|
||
v1 = {
|
||
Filter = "Service.Meta.version == v1"
|
||
}
|
||
v2 = {
|
||
Filter = "Service.Meta.version == v2"
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: web
|
||
spec:
|
||
defaultSubset: v1
|
||
subsets:
|
||
v1:
|
||
filter: 'Service.Meta.version == v1'
|
||
v2:
|
||
filter: 'Service.Meta.version == v2'
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "web",
|
||
"DefaultSubset": "v1",
|
||
"Subsets": {
|
||
"v1": {
|
||
"Filter": "Service.Meta.version == v1"
|
||
},
|
||
"v2": {
|
||
"Filter": "Service.Meta.version == v2"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### Resolve virtual upstreams
|
||
|
||
The following example uses the [`Redirect` parameter](#redirect) to expose a set of services to another datacenter as a virtual service.
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "web-dc2"
|
||
Redirect {
|
||
Service = "web"
|
||
Datacenter = "dc2"
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: web-dc2
|
||
spec:
|
||
redirect:
|
||
service: web
|
||
datacenter: dc2
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "web-dc2",
|
||
"Redirect": {
|
||
"Service": "web",
|
||
"Datacenter": "dc2"
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### 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`:
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "web"
|
||
ConnectTimeout = "15s"
|
||
Failover = {
|
||
v2 = {
|
||
Datacenters = ["dc2"]
|
||
}
|
||
"*" = {
|
||
Datacenters = ["dc3", "dc4"]
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: web
|
||
spec:
|
||
connectTimeout: 15s
|
||
failover:
|
||
v2:
|
||
datacenters: ['dc2']
|
||
'*':
|
||
datacenters: ['dc3', 'dc4']
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "web",
|
||
"ConnectTimeout": "15s",
|
||
"Failover": {
|
||
"v2": {
|
||
"Datacenters": ["dc2"]
|
||
},
|
||
"*": {
|
||
"Datacenters": ["dc3", "dc4"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
#### 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.
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "web"
|
||
ConnectTimeout = "15s"
|
||
Failover = {
|
||
"*" = {
|
||
Targets = [
|
||
{Datacenter = "dc3"},
|
||
{Peer = "peer-01"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: web
|
||
spec:
|
||
connectTimeout: 15s
|
||
failover:
|
||
'*':
|
||
targets:
|
||
- datacenter: "dc3"
|
||
- peer: "peer-01"
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "web",
|
||
"ConnectTimeout": "15s",
|
||
"Failover": {
|
||
"*": {
|
||
"Targets": [
|
||
{"Datacenter": "dc3"},
|
||
{"Peer": "peer-01"}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
#### Failover for all service subsets <EnterpriseAlert inline />
|
||
|
||
The following example enables failover to the `secondary` namespace in another datacenter for all service subsets.
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "product-api"
|
||
Namespace = "primary"
|
||
ConnectTimeout = "0s"
|
||
Failover = {
|
||
"*" = {
|
||
Datacenters = ["dc2"]
|
||
Namespace = "secondary"
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: product-api
|
||
namespace: primary
|
||
spec:
|
||
connectTimeout: 0s
|
||
failover:
|
||
namespace: 'secondary'
|
||
datacenters: ['dc2']
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "product-api",
|
||
"Namespace": "primary",
|
||
"ConnectTimeout": "0s",
|
||
"Failover": {
|
||
"*": {
|
||
"Datacenters": ["dc2"],
|
||
"Namespace": "secondary"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
#### Failover to a namespace <EnterpriseAlert inline />
|
||
|
||
The following example enables failover to a different namespace in the same datacenter.
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "product-api"
|
||
Namespace = "primary"
|
||
ConnectTimeout = "0s"
|
||
Failover = {
|
||
"*" = {
|
||
Service = "product-api-backup"
|
||
Namespace = "secondary"
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: product-api
|
||
namespace: primary
|
||
spec:
|
||
connectTimeout: 0s
|
||
failover:
|
||
service: 'product-api-backup'
|
||
namespace: 'secondary'
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "product-api",
|
||
"Namespace": "primary",
|
||
"ConnectTimeout": "0s",
|
||
"Failover": {
|
||
"*": {
|
||
"Service": "product-api-backup",
|
||
"Namespace": "secondary"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### Consistent load balancing
|
||
|
||
The following example applies a Maglev load balancing policy for requests with an `x-user-id` header:
|
||
|
||
<Tabs>
|
||
<Tab heading="HCL" group="hcl">
|
||
|
||
```hcl
|
||
Kind = "service-resolver"
|
||
Name = "web"
|
||
|
||
LoadBalancer = {
|
||
Policy = "maglev"
|
||
HashPolicies = [
|
||
{
|
||
Field = "header"
|
||
FieldValue = "x-user-id"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="YAML" group="yaml">
|
||
|
||
```yaml
|
||
apiVersion: consul.hashicorp.com/v1alpha1
|
||
kind: ServiceResolver
|
||
metadata:
|
||
name: web
|
||
spec:
|
||
loadBalancer:
|
||
policy: maglev
|
||
hashPolicies:
|
||
- field: header
|
||
fieldValue: x-user-id
|
||
```
|
||
|
||
</Tab>
|
||
|
||
<Tab heading="JSON" group="json">
|
||
|
||
```json
|
||
{
|
||
"Kind": "service-resolver",
|
||
"Name": "web",
|
||
"LoadBalancer": {
|
||
"Policy": "maglev",
|
||
"HashPolicies": [
|
||
{
|
||
"Field": "header",
|
||
"FieldValue": "x-user-id"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|