consul/website/content/docs/agent/config-entries/service-resolver.mdx

---
layout: docs
page_title: 'Configuration Entry Kind: Service Resolver'
sidebar_title: 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

-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.

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

## Sample Config Entries

Create service subsets based on a version metadata and override the defaults:

```hcl
Kind          = "service-resolver"
Name          = "web"
DefaultSubset = "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"
ConnectTimeout = "15s"
Failover = {
  "*" = {
    Datacenters = ["dc3", "dc4"]
  }
}
```

Representation of the defaults when a resolver is not configured:

```hcl
Kind = "service-resolver"
Name = "web"
```

Apply consistent load balancing for requests based on `x-user-id` header:

```hcl
Kind = "service-resolver"
Name = "web"

LoadBalancer = {
  Policy = "maglev"
  HashPolicies = [
    {
      Field = "header"
      FieldValue = "x-user-id"
    }
  ]
}
```

## Available Fields

- `Kind` - Must be set to `service-resolver`

- `Name` `(string: <required>)` - Set to the name of the service being configured.

- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to.

- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.

- `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) to be used for selecting
    instances of the requested service. If empty all healthy instances are
    returned. This expression can filter on the same selectors as the
    [Health API endpoint](/api/health#filtering-2).

  - `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's
    health check interpretation. If this is set to false, instances with checks
    in the passing as well as the warning states will be considered healthy. If
    this is set to true, only instances with checks in the passing state will
    be considered healthy.

- `Redirect` `(ServiceResolverRedirect: <optional>)` - 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<string>)` - A fixed list of datacenters to try during
    failover.

- `LoadBalancer` `(LoadBalancer`) - Determines the load balancing policy and
  configuration for services issuing requests to this upstream.
  This option is available in Consul versions 1.9.0 and newer.

  - `Policy` `(string: "")` - The load balancing policy used to select a host.
    One of: `random`, `round_robin`, `least_request`, `ring_hash`, `maglev`.

  - `RingHashConfig` `(RingHashConfig)` - Configuration for the `ring_hash`
    policy type.

    - `MinimumRingRize` `(int: 1024)` - Determines the minimum number of entries
      in the hash ring.

    - `MaximumRingRize` `(int: 8192)` - Determines the maximum number of entries
      in the hash ring.

  - `LeastRequestConfig` `(LeastRequestConfig)` - Configuration for the `least_request`
    policy type.

    - `ChoiceCount` `(int: 2)` - Determines the number of random healthy hosts
      from which to select the one with the least requests.

  - `HashPolicies` `(array<HashPolicies>)` - a list of hash policies to use for
    hashing load balancing algorithms. Hash policies are evaluated individually
    and combined such that identical lists result in the same hash.
    If no hash policies are present, or none are successfully evaluated,
    then a random backend host will be selected.

    - `Field` `(string: "")` - The attribute type to hash on.
      Must be one of `header`,`cookie`, or `query_parameter`.
      Cannot be specified along with `SourceAddress`.
    - `FieldValue` `(string: "")` - The value to hash.
      ie. header name, cookie name, URL query parameter name.
      Cannot be specified along with `SourceAddress`.
    - `CookieConfig` `(CookieConfig)` - Additional configuration for the "cookie" hash policy type.
      This is specified to have Envoy generate a cookie for a client on its first request.

      - `Session` `(bool: false)` - Generates a session cookie with no expiration.

      - `TTL` `(duration: 0s)` - TTL for generated cookies. Cannot be specified for session cookies.
      - `Path` `(string: "")` - The path to set for the cookie.

    - `SourceIP` `(bool: false)` - Determines whether the hash should be of the source IP
      address rather than of a field and field value.
      Cannot be specified along with `Field` or `FieldValue`.
    - `Terminal` `(bool: false)` - Will short circuit the computation of the hash
      when multiple hash policies are present. If a hash is computed when a
      Terminal policy is evaluated, then that hash will be used and subsequent
      hash policies will be ignored.

## 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](/docs/security/acl).

Reading a `service-resolver` config entry requires `service:read` on the resource.

Creating, updating, or deleting a `service-resolver` config entry requires
`service:write` on the resource and `service:read` on any other service referenced by
name in these fields:

- [`Redirect.Service`](#service)

- [`Failover[].Service`](#service-1)