News HashiCorp to join IBM to accelerate multi-cloud automation. Read the blog →
Consul
Consul Home

Service resolver configuration reference

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.

Refer to L7 traffic management overview for additional information.

Configuration model

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.

Complete configuration

When every field is defined, a service resolver configuration entry has the following form:

Kind      = "service-resolver"                                     ## requiredName      = "<name-of-service-configuration-applies-to>"Namespace = "<namespace-configuration-applies-to>"Partition = "<partition-configuration-applies-to>"Meta = { <key> = "<value>"} ConnectTimeout = "10s"RequestTimeout = "15s"Subsets = { <subset01-name> = {   Filter      = "<expression.to.match.on == value01>"   OnlyPassing = true } <subset02-name> = {   Filter      = "<expression.to.match.on == value02>"   OnlyPassing = true }}DefaultSubset  = "<subset01-name>" Redirect = { Service       = "<destination-service>" ServiceSubset = "<destination-subset>" Namespace     = "<destination-namespace>" Partition     = "<destination-partition>" SamenessGroup = "<destination-sameness-group>" Datacenter    = "<destination-datacenter>" Peer          = "<destination-peer>"} PrioritizeByLocality = { Mode = "failover"} Failover = {                   ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup <local-subset-name> = {   Targets = [     { Service = "<destination-service>" },     { ServiceSubset = "<destination-service-subset>" },     { Namespace = "<destination-namespace>" },     { Partition = "<destination-partition>" },     { Datacenter = "<destination-datacenter>" },     { Peer = "<destination-peer>" }   ] } "*" = {   Service       = "<destination-service>"   ServiceSubset = "<destination-service-subset>"   Namespace     = "<destination-namespace>"   Datacenters   = ["<destination-datacenter-01>", "<destination-datacenter-02>"] }} LoadBalancer = { Policy = "random" LeastRequestConfig = {                     ## requires Policy = "least_request"   ChoiceCount = 2 } RingHashConfig = {                         ## requires Policy = "ring_hash"  MinimumRingSize = 1024  MaximumRingSize = 8192 } HashPolicies = [   {     Field      = "header"                  ## cannot specify with SourceIP     FieldValue = "<value-to-hash>"         ## cannot specify with SourceIP     CookieConfig = {       Session = false       TTL     = "0s"       Path    = "<path/to/cookie>"     }     SourceIP = false                        ## cannot specify with Field or FieldValue     Terminal = false   } ]} 

Specification

This section provides details about the fields you can configure in the configuration entry.

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 Enterprise

Specifies the namespace that the service resolver applies to. Refer to namespaces for more information.

Values

  • Default: None
  • Data type: String

Partition Enterprise

Specifies the admin partition that the service resolver applies to. Refer to 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

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

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:

      ParameterDescriptionData typeDefault
      FilterSpecifies 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. For more information about creating and using expressions to filter, refer to filtering.StringNone
      OnlyPassingDetermines 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.Booleanfalse

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

Redirect{}.Service

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, andDatacenter.

Values

  • Default: None
  • Data type: String

Redirect{}.Namespace Enterprise

Specifies the namespace at the redirect’s destination that resolves local upstream requests.

Values

  • Default: None
  • Data type: String

Redirect{}.Partition Enterprise

Specifies the admin partition at the redirect’s destination that resolves local upstream requests.

Values

  • Default: None
  • Data type: String

Redirect{}.SamenessGroup Enterprise

Specifies the sameness group at the redirect’s destination that resolves local upstream requests.

Values

  • Default: None
  • Data type: String

Redirect{}.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. 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.

Values

  • Default: None
  • Data type: String

PrioritizeByLocality

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 for additional information.

Values

  • Default: None
  • Data type: Map

Failover

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.

Service, ServiceSubset, Namespace, Targets, SamenessGroup, and Datacenters cannot all be empty at the same time.

Values

Failover{}.Service

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.

Values

  • Default: None
  • Data type: String

Failover{}.Namespace Enterprise

Specifies the namespace at the failover location where the failover services are deployed. If empty, the current namespace is used.

Values

  • Default: None
  • Data type: String

Failover{}.SamenessGroup Enterprise

Specifies the sameness group at the failover location where the failover services are deployed.

Values

  • Default: None
  • Data type: String

Failover{}.Datacenters

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.

Values

Failover{}.Targets[].Service

Specifies the service name to use for the failover target. If empty, the current service name is used.

Values

  • Default: None
  • Data type: String

Failover{}.Targets[].ServiceSubset

Specifies the named subset to use for the failover target. If empty, the default subset for the requested service name is used.

Values

  • Default: None
  • Data type: String

Failover{}.Targets[].Namespace Enterprise

Specifies the namespace to use for the failover target. If empty, the default namespace is used.

Values

  • Default: None
  • Data type: String

Failover{}.Targets[].Partition Enterprise

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

LoadBalancer{}.Policy

Specifies the type of load balancing policy for selecting a host. Supported load balancing policies include:

PolicyDescription
RandomThe load balancer forwards a client request to an available server chosen at random from a fixed list.
Round robinThe load balancer proceeds through a fixed list of servers and forwards a client request to each available server in order.
Least requestThe 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.
Ring hashThe 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.
MaglevThe load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in LoadBalancer{}.HashPolicies.

Values

LoadBalancer{}.LeastRequestConfig

Specifies configuration for the least_request policy type.

Values

  • Default: None

  • Data type: Map containing the following parameter:

    ParameterDescriptionData typeDefault
    ChoiceCountSpecifies the number of random healthy hosts from which to select the one with the least requests.Integer2

LoadBalancer{}.RingHashConfig

Specifies configuration for the ring_hash policy type.

Values

  • Default: None

  • Data type: List that can contain the following parameters:

    ParameterDescriptionData typeDefault
    MinimumRingSizeDetermines the minimum number of entries in the hash ring.Integer1024
    MaximumRingSizeDetermines the maximum number of entries in the hash ring.Integer8192

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

LoadBalancer{}.HashPolicies[].Field

Specifies the attribute type to hash on. You cannot specify the Field parameter if SourceIP is also configured.

Supported attribute types include the following:

AttributeDescription
CookieThe load balancer uses a cookie to obtain a hash key. Refer to the Envoy documentation for more information.
HeaderThe load balancer uses a request header to obtain a hash key. Refer to the Envoy documentation for more information.
Query ParameterThe load balancer uses a URL query parameter to obtain the hash key. Refer to the Envoy documentation for more information.

Values

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:

    ParameterDescriptionData typeDefault
    SessionDirects Consul to generate a session cookie with no expiration.Booleanfalse
    TTLSpecifies the TTL for generated cookies. Cannot be specified for session cookies.String0s
    PathSpecifies the path to set for the cookie.StringNone

LoadBalancer{}.HashPolicies[].SourceIP

Determines if the hash type should be source IP address. You cannot specify SourceIP if Field or FieldValue are configured.

Values

  • Default: false
  • Data type: Boolean

LoadBalancer{}.HashPolicies[].Terminal

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

Examples

The following examples demonstrate common service resolver configuration patterns for specific use cases.

Filter on service version

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.

Kind          = "service-resolver"Name          = "web"DefaultSubset = "v1"Subsets = {  v1 = {    Filter = "Service.Meta.version == v1"  }  v2 = {    Filter = "Service.Meta.version == v2"  }}

Resolve virtual upstreams

The following example uses the Redirect parameter to expose a set of services to another datacenter as a virtual service.

Kind = "service-resolver"Name = "web-dc2"Redirect {  Service    = "web"  Datacenter = "dc2"}

Service failover

The following example enables failover for subset v2 to dc2. All other subsets attempt failover to dc3, and when it is not available, to dc4:

Kind           = "service-resolver"Name           = "web"ConnectTimeout = "15s"Failover = {  v2 = {    Datacenters = ["dc2"]  }  "*" = {    Datacenters = ["dc3", "dc4"]  }}

Failover targets for federation and cluster peering

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.

Kind           = "service-resolver"Name           = "web"ConnectTimeout = "15s"Failover = {  "*" = {    Targets = [      {Datacenter = "dc3"},      {Peer = "peer-01"}    ]  }}

Failover for all service subsets Enterprise

The following example enables failover to the secondary namespace in another datacenter for all service subsets.

Kind           = "service-resolver"Name           = "product-api"Namespace      = "primary"ConnectTimeout = "0s"Failover = {  "*" = {    Datacenters = ["dc2"]    Namespace = "secondary"  }}

Failover to a namespace Enterprise

The following example enables failover to a different namespace in the same datacenter.

Kind           = "service-resolver"Name           = "product-api"Namespace      = "primary"ConnectTimeout = "0s"Failover = {  "*" = {    Service = "product-api-backup"    Namespace = "secondary"  }}

Consistent load balancing

The following example applies a Maglev load balancing policy for requests with an x-user-id header:

Kind = "service-resolver"Name = "web" LoadBalancer = {  Policy = "maglev"  HashPolicies = [    {      Field = "header"      FieldValue = "x-user-id"    }  ]}
Edit this page on GitHub