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.

Kind: string | required | must be set to service-resolver
Name: string | required
Namespace: string | default Enterprise
Partition: string | default Enterprise
Meta: map
ConnectTimeout: string | 0s
RequestTimeout: string | 15s
Subsets: map
- Filter: string
- OnlyPassing: boolean | false
DefaultSubset: string
Redirect: map
- Service: string
- ServiceSubset: string
- Namespace: string Enterprise
- Partition: string | default Enterprise
- SamenessGroup: string Enterprise
- Datacenter: string
- Peer: string
PrioritizeByLocality: map Enterprise
- Mode: string | failover
Failover: map
- Service: string
- ServiceSubset: string
- Namespace: string Enterprise
- SamenessGroup: string Enterprise
- Datacenters: list
- Targets: list
  - Service: string
  - ServiceSubset: string
  - Namespace: string Enterprise
  - Partition: string | default Enterprise
  - Datacenter: string
  - Peer: string
LoadBalancer: map
- Policy: string
- LeastRequestConfig: map
  - ChoiceCount: integer | 2
- RingHashConfig: map
  - MinimumRingSize: integer | 1024
  - MaximumRingSize: integer | 8192
- HashPolicies: map
  - Field: string
  - FieldValue: string
  - CookieConfig: map
    - Session: boolean | false
    - TTL: string
    - Path: string
  - SourceIP: boolean | false
  - Terminal: boolean | false

apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1
kind: string | required | must be set to ServiceResolver
metadata: map | required
- name: string | required
- namespace: string | optional Enterprise
spec: map | required
- connectTimeout: string | 0s
- requestTimeout: string | 15s
- subsets: map
  - filter: string
  - onlyPassing: boolean | false
- defaultSubset: string
- redirect: map
  - service: string
  - serviceSubset: string
  - namespace: string Enterprise
  - partition: string Enterprise
  - samenessGroup: string Enterprise
  - datacenter: string
  - peer: string
- prioritizeByLocality: map | Enterprise
  - mode: string | failover
- failover: map
  - service: string
  - serviceSubset: string
  - namespace: string Enterprise
  - samenessGroup: string Enterprise
  - datacenters: string
  - targets: list
    - service: string
    - serviceSubset: string
    - namespace: string | default Enterprise
    - partition: string | default Enterprise
    - datacenter: string
    - peer: string
- loadBalancer: map
  - policy: string
  - leastRequestConfig: map
    - choiceCount: integer | 2
  - ringHashConfig: map
    - minimumRingSize: integer | 1024
    - maximumRingSize: integer | 8192
- hashPolicies: list
  - field: string
  - fieldValue: string
  - cookieConfig: map
    - session: boolean | false
    - ttl: string | 0s
    - path: string
  - sourceIP: boolean | false
  - terminal: boolean | false

Complete configuration

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

Kind      = "service-resolver"                                     ## required
Name      = "<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
   }
 ]
}

{
  "Kind":"service-resolver",                             // required
  "Name":"<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
    }
   ]
  }
}

apiVersion: consul.hashicorp.com/v1alpha1         # required
kind: ServiceResolver                             # required
metadata:
  name: <serviceName>
  namespace: <namespace>
spec:
  connectTimeout: 10s
  requestTimeout: 15s
  subsets:
    <subset01Name>:
      filter: <expression.to.match.on == value01>
      onlyPassing: false
    <subset02Name>:
      filter: <expression.to.match.on == value02>
      onlyPassing: false
  defaultSubset: <definedSubsetName>
  redirect:
    service: <serviceName>
    servicesubset: <subsetName>
    namespace: <namespaceName>
    partition: <partitionName>
    samenessGroup: <samenessGroupName>
    peer: <peerName>
  prioritizeByLocality: 
    mode: failover
  failover:                         # requires at least one of the following: service, serviceSubset, namespace, targets, datacenters, samenessGroup
    <localSubsetName>:
      targets:
      - service: <serviceName>
      - serviceSubset: <serviceSubset>
      - namespace: <namespaceName>
      - partition: <partitionName>
      - datacenter: <datacenterName>
      - peer: <peerName>
    `*`: <namespaceName>
      service: <serviceName>
      serviceSubset: <serviceSubset>
      namespace: <namespaceName>
      datacenters: ["<destinationDatacenter01>", "<destinationDatacenter02>"]
  loadBalancer:
    policy: random
    leastRequestConfig:                # requires policy: leastRequestConfig
      choiceCount: 2
    ringHashConfig:                    # requires policy: ringHashConfig
      minimumRingSize: 1024
      maximumRingSize: 8192
    hashPolicies:
      - field: header                  # cannot specify with SourceIP
      - fieldValue: <valueToHashOn>    # 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
- <KEY>: String
- <VALUE>: String or integer

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

Parameter	Description	Data type	Default
`Filter`	Specifies 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.	String	None
`OnlyPassing`	Determines 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.	Boolean	`false`

`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

Default: None
Data type: Map that can contain the following parameters:

`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

Default: None
Data type: Map that can contain the following parameters:

`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

Default: None
Data type: List of maps that can contain the following parameters:

`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

Default: None
Data type: Map that can contain the following parameters:

`LoadBalancer{}.Policy`

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

Policy	Description
Random	The load balancer forwards a client request to an available server chosen at random from a fixed list.
Round robin	The load balancer proceeds through a fixed list of servers and forwards a client request to each available server in order.
Least request	The 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 hash	The 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`.
Maglev	The 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

Default: None
Data type: String containing one of the following values:

`LoadBalancer{}.LeastRequestConfig`

Specifies configuration for the least_request policy type.

Values

Default: None
Data type: Map containing the following parameter:
Parameter Description Data type Default
ChoiceCount Specifies the number of random healthy hosts from which to select the one with the least requests. Integer 2

Parameter	Description	Data type	Default
`ChoiceCount`	Specifies the number of random healthy hosts from which to select the one with the least requests.	Integer	`2`

`LoadBalancer{}.RingHashConfig`

Specifies configuration for the ring_hash policy type.

Values

Default: None

Data type: List that can contain the following parameters:

Parameter	Description	Data type	Default
`MinimumRingSize`	Determines the minimum number of entries in the hash ring.	Integer	`1024`
`MaximumRingSize`	Determines the maximum number of entries in the hash ring.	Integer	`8192`

`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

Default: None
Data type: List of maps for the following parameters:

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

Attribute	Description
Cookie	The load balancer uses a cookie to obtain a hash key. Refer to the Envoy documentation for more information.
Header	The load balancer uses a request header to obtain a hash key. Refer to the Envoy documentation for more information.
Query Parameter	The load balancer uses a URL query parameter to obtain the hash key. Refer to the Envoy documentation for more information.

Values

Default: None
Data type: String containing one of the following 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:

Parameter	Description	Data type	Default
`Session`	Directs Consul to generate a session cookie with no expiration.	Boolean	`false`
`TTL`	Specifies the TTL for generated cookies. Cannot be specified for session cookies.	String	`0s`
`Path`	Specifies the path to set for the cookie.	String	None

`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

`apiVersion`

Specifies the version of the Consul API for integrating with Kubernetes. The value must be consul.hashicorp.com/v1alpha1.

Values

Default: None
This field is required.
String value that must be set to consul.hashicorp.com/v1alpha1.

`kind`

Specifies the type of configuration entry to implement. Must be set to ServiceResolver.

Values

Default: None
This field is required.
Data type: String value that must be set to ServiceResolver.

`metadata`

Map that contains an arbitrary name for the configuration entry and the namespace it applies to.

Values

Default: None
Data type: Map

`metadata.name`

Values

Default: None
This field is required.
Data type: String

`metadata.namespace`Enterprise

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

Values

Default: None
Data type: String

`spec`

Map that contains the details about the ServiceResolver configuration entry. The apiVersion, kind, and metadata fields are siblings of the spec field. All other configurations are children.

Values

Default: None
This field is required.
Data type: Map

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

`spec.requestTimeout`

Values

Default: 15s
Data type: String

`spec.subsets`

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:

Parameter	Description	Data type	Default
`filter`	Specifies 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.	String	None
`onlyPassing`	Determines 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.	Boolean	`false`

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

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

Default: None
Data type: Map that can contain the following parameters:

`spec.redirect.service`

Specifies the name of a service at the redirect’s destination that resolves local upstream requests.

Values

Default: None
Data type: String

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

`spec.redirect.namespace` Enterprise

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

Values

Default: None
Data type: String

`spec.redirect.partition` Enterprise

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

Values

Default: None
Data type: String

`spec.redirect.samenessGroup` Enterprise

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

Values

Default: None
Data type: String

`spec.redirect.datacenter`

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

Values

Default: None
Data type: String

`spec.redirect.peer`

Values

Default: None
Data type: String

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

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

Default: None
Data type: Map that can contain the following parameters:

`spec.failover.service`

Specifies the name of the service to resolve at the failover location during a failover scenario.

Values

Default: None
Data type: String

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

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

`spec.failover.samenessGroup` Enterprise

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

Values

Default: None
Data type: String

`spec.failover.datacenters`

Values

Default: None
Data type: String

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

Default: None
Data type: List of maps that can contain the following parameters:

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

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

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

`spec.failover.targets.partition` Enterprise

Values

Default: None
Data type: String

`spec.failover.targets.datacenter`

Values

Default: None
Data type: String

`spec.failover.targets.peer`

Values

Default: None
Data type: String

`spec.loadBalancer`

Specifies the load balancing policy and configuration for services issuing requests to this upstream.

Values

Default: None
Data type: Map that can contain the following parameters:

`spec.loadBalancer.policy`

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

Policy	Description
Random	The load balancer forwards a client request to an available server chosen at random from a fixed list.
Round robin	The load balancer proceeds through a fixed list of servers and forwards a client request to each available server in order.
Least request	The load balancer forwards a client request to the server with the fewest connections. When using this policy, you can specify additional parameters in `spec.loadBalancer.leastRequestConfig`.
Ring hash	The load balancer forwards requests from the same client to the same group of servers. When using this policy, you can specify additional parameters in `spec.loadBalancer.ringHashConfig`.
Maglev	The load balancer uses a hashing algorithm to spread requests evenly across servers. When using this policy, you can specify additional parameters in `spec.loadBalancer.hashPolicies`.

Values

Default: None
Data type: String containing one of the following values:

`spec.loadBalancer.leastRequestConfig`

Specifies configuration for the least_request policy type.

Values

Default: None
Data type: Map containing the following parameter:
Parameter Description Data type Default
choiceCount Specifies the number of random healthy hosts from which to select the one with the least requests. Integer 2

Parameter	Description	Data type	Default
`choiceCount`	Specifies the number of random healthy hosts from which to select the one with the least requests.	Integer	`2`

`spec.loadBalancer.ringHashConfig`

Specifies configuration for the ring_hash policy type.

Values

Default: None

Data type: List that can contain the following parameters:

Parameter	Description	Data type	Default
`minimumRingSize`	Determines the minimum number of entries in the hash ring.	Integer	`1024`
`maximumRingSize`	Determines the maximum number of entries in the hash ring.	Integer	`8192`

`spec.loadBalancer.hashPolicies`

Values

Default: None
Data type: List that can contain the following parameters:

`spec.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:

Attribute	Description
Cookie	The load balancer uses a cookie to obtain a hash key. Refer to the Envoy documentation for more information.
Header	The load balancer uses a request header to obtain a hash key. Refer to the Envoy documentation for more information.
Query Parameter	The load balancer uses a URL query parameter to obtain the hash key. Refer to the Envoy documentation for more information.

Values

Default: None
Data type: String containing one of the following values:

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

`spec.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:

Parameter	Description	Data type	Default
`session`	Directs Consul to generate a session cookie with no expiration.	Boolean	`false`
`ttl`	Specifies the TTL for generated cookies. Cannot be specified for session cookies.	String	`0s`
`path`	Specifies the path to set for the cookie.	String	None

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

`spec.loadBalancer.hashPolicies[].terminal`

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

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: web
spec:
  defaultSubset: v1
  subsets:
    v1:
      filter: 'Service.Meta.version == v1'
    v2:
      filter: 'Service.Meta.version == v2'

{
  "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"]
  }
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: web
spec:
  connectTimeout: 15s
  failover:
    v2:
      datacenters: ['dc2']
    '*':
      datacenters: ['dc3', '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"}
    ]
  }
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: web
spec:
  connectTimeout: 15s
  failover:
    '*':
      targets:
      - datacenter: "dc3"
      - peer: "peer-01"

{
  "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"
  }
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: product-api
  namespace: primary
spec:
  connectTimeout: 0s
  failover:
    namespace: 'secondary'
    datacenters: ['dc2']

{
  "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"
  }
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: product-api
  namespace: primary
spec:
  connectTimeout: 0s
  failover:
    service: 'product-api-backup'
    namespace: 'secondary'

{
  "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"
    }
  ]
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: web
spec:
  loadBalancer:
    policy: maglev
    hashPolicies:
      - field: header
        fieldValue: x-user-id

{
  "Kind": "service-resolver",
  "Name": "web",
  "LoadBalancer": {
    "Policy": "maglev",
    "HashPolicies": [
      {
        "Field": "header",
        "FieldValue": "x-user-id"
      }
    ]
  }
}

Service resolver configuration reference

Configuration model

Complete configuration

Specification

Kind

Values

Name

Values

Namespace EnterpriseEnterprise

Values

Partition EnterpriseEnterprise

Values

Meta

Values

ConnectTimeout

Values

RequestTimeout

Values

Subsets

Values

DefaultSubset

Values

Redirect

Values

Redirect{}.Service

Values

Redirect{}.ServiceSubset

Values

Redirect{}.Namespace EnterpriseEnterprise

Values

Redirect{}.Partition EnterpriseEnterprise

Values

Redirect{}.SamenessGroup EnterpriseEnterprise

Values

Redirect{}.Datacenter

Values

Redirect{}.Peer

Values

PrioritizeByLocality

Values

Failover

Values

Failover{}.Service

Values

Failover{}.ServiceSubset

Values

Failover{}.Namespace EnterpriseEnterprise

Values

Failover{}.SamenessGroup EnterpriseEnterprise

Values

Failover{}.Datacenters

Values

Failover{}.Targets

Values

Failover{}.Targets[].Service

Values

Failover{}.Targets[].ServiceSubset

Values

Failover{}.Targets[].Namespace EnterpriseEnterprise

Values

Failover{}.Targets[].Partition EnterpriseEnterprise

Values

Failover{}.Targets[].Datacenter

Values

Failover{}.Targets[].Peer

Values

LoadBalancer

Values

LoadBalancer{}.Policy

Values

LoadBalancer{}.LeastRequestConfig

Values

LoadBalancer{}.RingHashConfig

Values

LoadBalancer{}.HashPolicies

Values

LoadBalancer{}.HashPolicies[].Field

Values

LoadBalancer{}.HashPolicies[].FieldValue

Values

`Kind`

`Name`

`Namespace` Enterprise

`Partition` Enterprise

`Meta`

`ConnectTimeout`

`RequestTimeout`

`Subsets`

`DefaultSubset`

`Redirect`

`Redirect{}.Service`

`Redirect{}.ServiceSubset`

`Redirect{}.Namespace` Enterprise

`Redirect{}.Partition` Enterprise

`Redirect{}.SamenessGroup` Enterprise

`Redirect{}.Datacenter`

`Redirect{}.Peer`

`PrioritizeByLocality`

`Failover`

`Failover{}.Service`

`Failover{}.ServiceSubset`

`Failover{}.Namespace` Enterprise

`Failover{}.SamenessGroup` Enterprise

`Failover{}.Datacenters`

`Failover{}.Targets`

`Failover{}.Targets[].Service`

`Failover{}.Targets[].ServiceSubset`

`Failover{}.Targets[].Namespace` Enterprise

`Failover{}.Targets[].Partition` Enterprise

`Failover{}.Targets[].Datacenter`

`Failover{}.Targets[].Peer`

`LoadBalancer`

`LoadBalancer{}.Policy`

`LoadBalancer{}.LeastRequestConfig`

`LoadBalancer{}.RingHashConfig`

`LoadBalancer{}.HashPolicies`

`LoadBalancer{}.HashPolicies[].Field`

`LoadBalancer{}.HashPolicies[].FieldValue`

`LoadBalancer{}.HashPolicies[].CookieConfig`

`LoadBalancer{}.HashPolicies[].SourceIP`

`LoadBalancer{}.HashPolicies[].Terminal`