Service resolver configuration entry 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 EnterpriseEnterprise
• Partition: string | default EnterpriseEnterprise
• 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 EnterpriseEnterprise
  • Partition: string | default EnterpriseEnterprise
  • SamenessGroup: string EnterpriseEnterprise
  • Datacenter: list
  • Peer: string
• Failover: map
  • Service: string
  • ServiceSubset: string
  • Namespace: string EnterpriseEnterprise
  • SamenessGroup: string EnterpriseEnterprise
  • Datacenters: list
  • Targets: list
    • Service: string
    • ServiceSubset: string
    • Namespace: string EnterpriseEnterprise
    • Partition: string | default EnterpriseEnterprise
    • 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 EnterpriseEnterprise
• 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 EnterpriseEnterprise
    • partition: string EnterpriseEnterprise
    • samenessGroup: string EnterpriseEnterprise
    • datacenter: string
    • peer: string
  • failover: map
    • service: string
    • serviceSubset: string
    • namespace: string EnterpriseEnterprise
    • samenessGroup: string EnterpriseEnterprise
    • datacenters: string
    • targets: list
      • service: string
      • serviceSubset: string
      • namespace: string | default EnterpriseEnterprise
      • partition: string | default EnterpriseEnterprise
      • 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>"
}
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":"parition-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>"
  },
  "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>
  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 EnterpriseEnterprise

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

Values

• Default: None
• Data type: String

Partition EnterpriseEnterprise

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
  • : String
  • : 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.

  • : String that names the subset. The string must be valid as a DNS subdomain element.

  • : 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:
  • Service
  • ServiceSubset
  • Namespace
  • Partition
  • SamenessGroup
  • Datacenter
  • Peer

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 EnterpriseEnterprise

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

Values

• Default: None
• Data type: String

Redirect{}.Partition EnterpriseEnterprise

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

Values

• Default: None
• Data type: String

Redirect{}.SamenessGroup EnterpriseEnterprise

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

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:
  • Service
  • ServiceSubset
  • Namespace
  • SamenessGroup
  • Datacenters
  • Targets

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 EnterpriseEnterprise

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 EnterpriseEnterprise

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:
  • Service
  • ServiceSubset
  • Namespace
  • Partition
  • Datacenter
  • Peer

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 EnterpriseEnterprise

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 EnterpriseEnterprise

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:
  • Policy
  • RingHashConfig
  • LeastRequestConfig
  • HashPolicies

LoadBalancer{}.Policy

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

Values

• Default: None

• Data type: String containing one of the following values:

  • random
  • round_robin
  • least_request
  • ring_hash
  • maglev

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

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:
  • Field
  • FieldValue
  • CookieConfig
  • SourceIP
  • Terminal

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:

Values

• Default: None
• Data type: String containing one of the following values:
  • cookie
  • header
  • query_parameter

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

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

metadata.namespaceEnterpriseEnterprise

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

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

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

  • : String that names the subset. The string must be valid as a DNS subdomain element.

  • : 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:
  • service
  • serviceSubset
  • namespace
  • partition
  • samenessGroup
  • datacenter
  • peer

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 EnterpriseEnterprise

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

Values

• Default: None
• Data type: String

spec.redirect.partition EnterpriseEnterprise

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

Values

• Default: None
• Data type: String

spec.redirect.samenessGroup EnterpriseEnterprise

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

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

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:
  • service
  • serviceSubset
  • namespace
  • samenessGroup
  • datacenters
  • targets

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 EnterpriseEnterprise

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 EnterpriseEnterprise

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

Values

• Default: None
• Data type: String

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

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:
  • service
  • serviceSubset
  • namespace
  • partition
  • datacenter
  • `peer

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 EnterpriseEnterprise

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 EnterpriseEnterprise

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

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

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

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:
  • policy
  • leastRequestConfig
  • ringHashConfig
  • hashPolicies

spec.loadBalancer.policy

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

Values

• Default: None

• Data type: String containing one of the following values:

  • random
  • round_robin
  • least_request
  • ring_hash
  • maglev

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

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

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 that can contain the following parameters:
  • field
  • fieldValue
  • cookieConfig
  • sourceIP
  • terminal

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:

Values

• Default: None
• Data type: String containing one of the following values:
  • cookie
  • header
  • query_parameter

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 besource IP address. You cannot specify sourceIP if field or fieldValue are configured.

Values

• Default: false
• Data type: Boolean

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

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

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: web-dc2
spec:
  redirect:
    service: web
    datacenter: dc2

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

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 EnterpriseEnterprise

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