1---
2layout: "docs"
3page_title: "Configuration Entry Kind: Service Resolver"
4sidebar_current: "docs-agent-cfg_entries-service_resolver"
5description: |-
6  The `service-resolver` config entry kind controls which service instances should satisfy Connect upstream discovery requests for a given service name.
7---
8
9-> **1.6.0+:**  This config entry is available in Consul versions 1.6.0 and newer.
10
11# Service Resolver
12
13The `service-resolver` config entry kind controls which service instances
14should satisfy Connect upstream discovery requests for a given service name.
15
16If no resolver config is defined the chain assumes 100% of traffic goes to the
17healthy instances of the default service in the current datacenter+namespace
18and discovery terminates.
19
20## Interaction with other Config Entries
21
22- Service resolver config entries are a component of [L7 Traffic
23  Management](/docs/connect/l7-traffic-management.html).
24
25## Sample Config Entries
26
27Create service subsets based on a version metadata and override the defaults:
28
29```hcl
30kind           = "service-resolver"
31name           = "web"
32default_subset = "v1"
33subsets = {
34  "v1" = {
35    filter = "Service.Meta.version == v1"
36  }
37  "v2" = {
38    filter = "Service.Meta.version == v2"
39  }
40}
41```
42
43Expose a set of services in another datacenter as a virtual service:
44
45```hcl
46kind = "service-resolver"
47name = "web-dc2"
48redirect {
49  service    = "web"
50  datacenter = "dc2"
51}
52```
53
54Enable failover for all subsets:
55
56```hcl
57kind            = "service-resolver"
58name            = "web"
59connect_timeout = "15s"
60failover = {
61  "*" = {
62    datacenters = ["dc3", "dc4"]
63  }
64}
65```
66
67Representation of the defaults when a resolver is not configured:
68
69```hcl
70kind = "service-resolver"
71name = "web"
72```
73
74## Available Fields
75
76- `Kind` - Must be set to `service-resolver`
77
78- `Name` `(string: <required>)` - Set to the name of the service being configured.
79
80- `ConnectTimeout` `(duration: 0s)` - The timeout for establishing new network
81  connections to this service.
82
83- `DefaultSubset` `(string: "")` - The subset to use when no explicit subset is
84  requested. If empty the unnamed subset is used.
85
86- `Subsets` `(map[string]ServiceResolverSubset)` - A map of subset name to
87  subset definition for all usable named subsets of this service. The map key
88  is the name of the subset and all names must be valid DNS subdomain elements.
89
90    This may be empty, in which case only the unnamed default subset will be
91    usable.
92
93  - `Filter` `(string: "")` - The
94    [filter expression](/api/features/filtering.html) to be used for selecting
95    instances of the requested service. If empty all healthy instances are
96    returned. This expression can filter on the same selectors as the
97    [Health API endpoint](/api/health.html#filtering-2).
98
99  - `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's
100    health check interpretation. If this is set to false, instances with checks
101    in the passing as well as the warning states will be considered healthy. If
102    this is set to true, only instances with checks in the passing state will
103    be considered healthy.
104
105- `Redirect` `(ServiceResolverRedirect: <optional>)` - When configured, all
106  attempts to resolve the service this resolver defines will be substituted for
107  the supplied redirect EXCEPT when the redirect has already been applied.
108
109    When substituting the supplied redirect into the all other fields besides
110    `Kind`, `Name`, and `Redirect` will be ignored.
111
112  - `Service` `(string: "")` - A service to resolve instead of the current
113    service.
114
115  - `ServiceSubset` `(string: "")` - A named subset of the given service to
116    resolve instead of one defined as that service's DefaultSubset If empty the
117    default subset is used.
118
119        If this is specified at least one of Service, Datacenter, or Namespace
120        should be configured.
121
122  - `Namespace` `(string: "")` - The namespace to resolve the service from
123    instead of the current one.
124
125  - `Datacenter` `(string: "")` - The datacenter to resolve the service from
126    instead of the current one.
127
128- `Failover` `(map[string]ServiceResolverFailover`) - Controls when and how to
129  reroute traffic to an alternate pool of service instances.
130
131    The map is keyed by the service subset it applies to and the special
132    string `"*"` is a wildcard that applies to any subset not otherwise
133    specified here.
134
135    `Service`, `ServiceSubset`, `Namespace`, and `Datacenters` cannot all be
136    empty at once.
137
138  - `Service` `(string: "")` - The service to resolve instead of the default as
139    the failover group of instances during failover.
140
141  - `ServiceSubset` `(string: "")` - The named subset of the requested service
142    to resolve as the failover group of instances. If empty the default subset
143    for the requested service is used.
144
145  - `Namespace` `(string: "")` - The namespace to resolve the requested service
146    from to form the failover group of instances. If empty the current
147    namespace is used.
148
149  - `Datacenters` `(array<string>)` - A fixed list of datacenters to try during
150    failover.
151
152## Service Subsets
153
154A service subset assigns a concrete name to a specific subset of discoverable
155service instances within a datacenter, such as `"version2"` or `"canary"`.
156
157A service subset name is useful only when composed with an actual service name,
158a specific datacenter, and namespace.
159
160All services have an unnamed default subset that will return all healthy
161instances unfiltered.
162
163Subsets are defined in `service-resolver` configuration entries, but are
164referenced by their names throughout the other configuration entry kinds.
165
166## ACLs
167
168Configuration entries may be protected by
169[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
170
171Reading a `service-resolver` config entry requires `service:read` on itself.
172
173Creating, updating, or deleting a `service-resolver` config entry requires
174`service:write` on itself and `service:read` on any other service referenced by
175name in these fields:
176
177- [`Redirect.Service`](#service)
178
179- [`Failover[].Service`](#service-1)
180
181