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