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.
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.
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`
- 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:
| `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:
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`.
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.
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.
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.
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).
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:
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:
| 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:
| `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:
| 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:
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.
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.
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.
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:
| `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:
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`.
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.
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.
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.
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).
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:
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:
| 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:
| `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:
| 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.
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:
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.
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.
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.
