---
layout: "docs"
page_title: "Configuration Entry Kind: Service Resolver (beta)"
sidebar_current: "docs-agent-cfg_entries-service_resolver"
description: |-
The `service-resolver` config entry kind controls which service instances should satisfy Connect upstream discovery requests for a given service name.
---
# Service Resolver (beta)
The `service-resolver` config entry kind controls which service instances
should satisfy Connect upstream discovery requests for a given service name.
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.
## Interaction with other Config Entries
- Service resolver config entries are a component of [L7 Traffic
Management](/docs/connect/l7-traffic-management.html).
## Sample Config Entries
Create service subsets based on a version metadata and override the defaults:
```hcl
kind = "service-resolver"
name = "web"
default_subset = "v1"
subsets = {
"v1" = {
filter = "Service.Meta.version == v1"
}
"v2" = {
filter = "Service.Meta.version == v2"
}
}
```
Expose a set of services in another datacenter as a virtual service:
```hcl
kind = "service-resolver"
name = "web-dc2"
redirect {
service = "web"
datacenter = "dc2"
}
```
Enable failover for all subsets:
```hcl
kind = "service-resolver"
name = "web"
connect_timeout = "15s"
failover = {
"*" = {
datacenters = ["dc3", "dc4"]
}
}
```
Representation of the defaults when a resolver is not configured:
```hcl
kind = "service-resolver"
name = "web"
```
## Available Fields
- `Kind` - Must be set to `service-resolver`
- `Name` `(string: )` - Set to the name of the service being configured.
- `ConnectTimeout` `(duration: 0s)` - The timeout for establishing new network
connections to this service.
- `DefaultSubset` `(string: "")` - The subset to use when no explicit subset is
requested. If empty the unnamed subset is used.
- `Subsets` `(map[string]ServiceResolverSubset)` - 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.
- `Filter` `(string: "")` - The
[filter expression](/api/features/filtering.html) to be used for selecting
instances of the requested service. If empty all healthy instances are
returned.
- `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's
health check filtering. If this is set to false, the results will include
instances with checks in the passing as well as the warning states. If this
is set to true, only instances with checks in the passing state will be
returned.
- `Redirect` `(ServiceResolverRedirect: )` - 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 substituting the supplied redirect into the all other fields besides
`Kind`, `Name`, and `Redirect` will be ignored.
- `Service` `(string: "")` - A service to resolve instead of the current
service.
- `ServiceSubset` `(string: "")` - 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.
- `Namespace` `(string: "")` - The namespace to resolve the service from
instead of the current one.
- `Datacenter` `(string: "")` - The datacenter to resolve the service from
instead of the current one.
- `Failover` `(map[string]ServiceResolverFailover`) - 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`, and `Datacenters` cannot all be
empty at once.
- `Service` `(string: "")` - The service to resolve instead of the default as
the failover group of instances during failover.
- `ServiceSubset` `(string: "")` - 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.
- `Namespace` `(string: "")` - The namespace to resolve the requested service
from to form the failover group of instances. If empty the current
namespace is used.
- `Datacenters` `(array)` - A fixed list of datacenters to try during
failover.
- `OverprovisioningFactor` `(int: 0)` - OverprovisioningFactor is a pass
through for envoy's
[`overprovisioning_factor`](https://www.envoyproxy.io/docs/envoy/v1.10.0/intro/arch_overview/load_balancing/priority)
value.
If omitted the overprovisioning factor value will be set so high as to
imply binary failover (all or nothing).
## 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](https://learn.hashicorp.com/consul/security-networking/production-acls).
Reading a `service-resolver` config entry requires `service:read` on itself.
Creating, updating, or deleting a `service-resolver` config entry requires
`service:write` on itself and `service:read` on any other service referenced by
name in these fields:
- [`Redirect.Service`](#service)
- [`Failover[].Service`](#service-1)