Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • Overview
      • Overview
      • What is a Service Mesh?
      • Overview
      • Chef, Puppet, etc.
      • Nagios
      • SkyDNS
      • SmartStack
      • Serf
      • Eureka
      • Istio
      • Envoy and Other Proxies
      • Custom Solutions
    • Overview
    • Manual Bootstrap
    • Consul Agent
    • Glossary
    • Required Ports
    • Bootstrapping a Datacenter
    • Cloud Auto-join
    • Server Performance
    • Kubernetes
  • API
  • Commands (CLI)
    • Register Services - Service Definitions
    • Find Services - DNS Interface
    • Monitor Services - Check Definitions
    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
      • Overview
      • Envoy
      • Built-in Proxy
      • Proxy Integration
      • Managed (Deprecated)
      • Overview
      • Proxy Service Registration
      • Sidecar Service Registration
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
      • Overview
      • UI Visualization
      • Overview
      • Discovery Chain
    • Connectivity Tasks
    • Distributed Tracing
      • Overview
        • WAN Federation
        • Enabling Service-to-service Traffic Across Datacenters
        • Enabling Service-to-service Traffic Across Admin Partitions
      • Ingress Gateways
      • Terminating Gateways
      • What is Cluster Peering
      • Create and Manage Peering Connections
      • Cluster Peering on Kubernetes
    • Nomad
    • Kubernetes
      • Overview
      • Go Integration
      • Overview
      • Built-In CA
      • Vault
      • ACM Private CA
    • Develop and Debug
    • Security
    • Overview
    • Installation
    • Technical Specifications
    • Common Errors
    • Upgrades
    • Overview
    • Architecture
      • Installing Consul on Kubernetes
      • Installing Consul K8s CLI
        • Minikube
        • Kind
        • AKS (Azure)
        • EKS (AWS)
        • GKE (Google Cloud)
        • Red Hat OpenShift
        • Self Hosted Kubernetes
        • Consul Clients Outside Kubernetes
        • Consul Servers Outside Kubernetes
        • Single Consul Datacenter in Multiple Kubernetes Clusters
        • Consul Enterprise
        • Overview
        • Federation Between Kubernetes Clusters
        • Federation Between VMs and Kubernetes
        • Overview
        • Systems Integration
          • Overview
          • Bootstrap Token
          • Enterprise License
          • Gossip Encryption Key
          • Partition Token
          • Replication Token
          • Server TLS
          • Service Mesh Certificates
          • Snapshot Agent Config
          • Webhook Certificates
        • WAN Federation
      • Overview
      • Transparent Proxy
      • Ingress Gateways
      • Terminating Gateways
      • Ingress Controllers
      • Configuring a Connect CA Provider
      • Health Checks
        • Metrics
    • Service Sync
      • Overview
      • Upgrade An Existing Cluster to CRDs
    • Annotations and Labels
    • Consul DNS
      • Upgrading Consul on Kubernetes
      • Upgrading Consul K8s CLI
      • Uninstall
      • Certificate Rotation
      • Gossip Encryption Key Rotation
      • Configure TLS on an Existing Cluster
      • Common Error Messages
      • FAQ
    • Compatibility Matrix
    • Helm Chart Configuration
    • Consul K8s CLI Reference
    • Overview
    • Requirements
    • Task Resource Usage
      • Installation
      • Secure Configuration
      • Migrate Existing Tasks
      • Installation
      • Secure Configuration
      • ACL Controller
    • Architecture
    • Consul Enterprise
    • Configuration Reference
    • Overview
    • Register Lambda Functions
    • Invoke Lambda Functions
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Health
      • Overview
      • task
      • start
    • Configuration
    • Tasks
    • Terraform Modules
      • Overview
      • License
      • Terraform Cloud Driver
      • Overview
      • Terraform
      • Terraform Cloud
    • Compatibility
    • Consul KV
    • Sessions
    • Watches
    • Overview
      • General
      • CLI Reference
      • Configuration Reference
    • Configuration Entries
    • Telemetry
    • Sentinel
    • RPC
    • Overview
      • ACL System Overview
      • Tokens
      • Policies
      • Roles
      • Rules Reference
      • Legacy Mode
      • Token Migration
      • ACLs in Federated Datacenters
        • Overview
        • Kubernetes
        • JWT
        • OIDC
        • AWS IAM
    • Encryption
      • Overview
      • Core
      • Network Infrastructure Automation
    • Overview
    • Admin Partitions
    • Audit Logging
    • Automated Backups
    • Automated Upgrades
    • Enhanced Read Scalability
    • Single sign-on - OIDC
    • Redundancy Zones
    • Advanced Federation
    • Network Segments
    • Namespaces
    • NIA with TFE
    • Sentinel
      • Overview
      • FAQ
    • Overview
    • Improving Consul Resilience
    • Anti-Entropy
    • Consensus Protocol
    • Gossip Protocol
    • Jepsen Testing
    • Network Coordinates
    • Consul Integration Program
    • NIA Integration Program
    • Vault Integration
    • Proxy Integration
  • Consul Tools
    • Overview
    • Compatibility Promise
    • Specific Version Details
      • Overview
      • General Process
      • Upgrading to 1.2.4
      • Upgrading to 1.6.9
      • Upgrading to 1.8.13
      • Upgrading to 1.10.0
    • Common Error Messages
    • FAQ
    • Overview
      • v1.11.x
      • v1.10.x
      • v1.9.x
      • v0.3.x
      • v0.2.x
      • v0.1.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.6.x
      • v0.5.x
    • Overview
    • ACL
  • Guides
Type '/' to Search

»Service Resolver

v1.8.4+: On Kubernetes, the ServiceResolver custom resource is supported in Consul versions 1.8.4+.
v1.6.0+: On other platforms, this config entry is supported in Consul versions 1.6.0+.

The service-resolver config entry kind (ServiceResolver on Kubernetes) controls which service instances should satisfy Connect upstream discovery requests for a given service name.

If no resolver config is defined the chain assumes 100% of traffic goes to the healthy instances of the default service in the current datacenter+namespace and discovery terminates.

»Interaction with other Config Entries

  • Service resolver config entries are a component of L7 Traffic Management.

»UI

Once a service-resolver is successfully entered, you can view it in the UI. Service routers, service splitters, and service resolvers can all be viewed by clicking on your service then switching to the routing tab.

screenshot of service resolver in the UI

»Sample Config Entries

»Filter on service version

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

HCL
  • HCL
  • Kubernetes YAML
  • JSON
Kind          = "service-resolver"
Name          = "web"
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"
  }
}
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'
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"
    }
  }
}
{
  "Kind": "service-resolver",
  "Name": "web",
  "DefaultSubset": "v1",
  "Subsets": {
    "v1": {
      "Filter": "Service.Meta.version == v1"
    },
    "v2": {
      "Filter": "Service.Meta.version == v2"
    }
  }
}

»Other datacenters

Expose a set of services in another datacenter as a virtual service:

HCL
  • HCL
  • Kubernetes YAML
  • JSON
Kind = "service-resolver"
Name = "web-dc2"
Redirect {
  Service    = "web"
  Datacenter = "dc2"
}
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
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"
  }
}
{
  "Kind": "service-resolver",
  "Name": "web-dc2",
  "Redirect": {
    "Service": "web",
    "Datacenter": "dc2"
  }
}

»Failover

Enable failover for subset v2 to dc2, and all other subsets to dc3 or dc4:

HCL
  • HCL
  • Kubernetes YAML
  • JSON
Kind           = "service-resolver"
Name           = "web"
ConnectTimeout = "15s"
Failover = {
  v2 = {
    Datacenters = ["dc2"]
  }
  "*" = {
    Datacenters = ["dc3", "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']
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"]
    }
  }
}
{
  "Kind": "service-resolver",
  "Name": "web",
  "ConnectTimeout": "15s",
  "Failover": {
    "v2": {
      "Datacenters": ["dc2"]
    },
    "*": {
      "Datacenters": ["dc3", "dc4"]
    }
  }
}
Enterprise

Failover to another datacenter and namespace for all service subsets.

HCL
  • HCL
  • Kubernetes YAML
  • JSON
Kind           = "service-resolver"
Name           = "product-api"
Namespace      = "primary"
ConnectTimeout = "0s"
Failover = {
  "*" = {
    Datacenters = ["dc2"]
    Namespace = "secondary"
  }
}
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']
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"
    }
  }
}
{
  "Kind": "service-resolver",
  "Name": "product-api",
  "Namespace": "primary",
  "ConnectTimeout": "0s",
  "Failover": {
    "*": {
      "Datacenters": ["dc2"],
      "Namespace": "secondary"
    }
  }
}
Enterprise

Failover within a datacenter and a different namespace.

HCL
  • HCL
  • Kubernetes YAML
  • JSON
Kind           = "service-resolver"
Name           = "product-api"
Namespace      = "primary"
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"
  }
}
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: product-api
  namespace: primary
spec:
  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"
    }
  }
}
{
  "Kind": "service-resolver",
  "Name": "product-api",
  "Namespace": "primary",
  "ConnectTimeout": "0s",
  "Failover": {
    "*": {
      "Service": "product-api-backup",
      "Namespace": "secondary"
    }
  }
}

»Consistent load balancing

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

HCL
  • HCL
  • Kubernetes YAML
  • JSON
Kind = "service-resolver"
Name = "web"

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"
    }
  ]
}
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: web
spec:
  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"
      }
    ]
  }
}
{
  "Kind": "service-resolver",
  "Name": "web",
  "LoadBalancer": {
    "Policy": "maglev",
    "HashPolicies": [
      {
        "Field": "header",
        "FieldValue": "x-user-id"
      }
    ]
  }
}

»Available Fields

  • Kind - Must be set to service-resolver

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

  • Namespace (string: "default")

    Enterprise
    - Specifies the namespace in which the configuration entry will apply.

  • Partition (string: "default")

    Enterprise
    - Specifies the admin partition in which the configuration entry will apply.

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

  • ConnectTimeout (duration: 0s) - The timeout for establishing new network connections to this service.

  • DefaultSubset (string: "") - The subset to use when no explicit subset is requested. If empty the unnamed subset is used.

  • Subsets (map[string]ServiceResolverSubset) - A map of subset name to subset definition for all usable named subsets of this service. The map key is the name of the subset and all names must be valid DNS subdomain elements.

    This may be empty, in which case only the unnamed default subset will be usable.

    • Filter (string: "") - The filter expression to be used for selecting instances of the requested service. If empty all healthy instances are returned. This expression can filter on the same selectors as the Health API endpoint.

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

  • Redirect (ServiceResolverRedirect: <optional>) - When configured, all attempts to resolve the service this resolver defines will be substituted for the supplied redirect EXCEPT when the redirect has already been applied.

    When Redirect is set, all other fields besides Kind, Name, Namespace and Redirect will be ignored.

    • Service (string: "") - A service to resolve instead of the current service.

    • ServiceSubset (string: "") - A named subset of the given service to resolve instead of one defined as that service's DefaultSubset. If empty, the default subset is used.

      If this is specified at least one of Service, Datacenter, or Namespace should be configured.

    • Namespace (string: "")

      Enterprise
      - Specifies the destination namespace to resolve the service from.

    • Partition (string: "")

      Enterprise
      - Specifies the destination admin partition to resolve the service from.

    • Datacenter (string: "") - Specifies the destination datacenter to resolve the service from.

  • Failover (map[string]ServiceResolverFailover) - Controls when and how to reroute traffic to an alternate pool of service instances.

    The map is keyed by the service subset it applies to and the special string "*" is a wildcard that applies to any subset not otherwise specified here.

    Service, ServiceSubset, Namespace, and Datacenters cannot all be empty at once.

    • Service (string: "") - The service to resolve instead of the default as the failover group of instances during failover.

    • ServiceSubset (string: "") - The named subset of the requested service to resolve as the failover group of instances. If empty the default subset for the requested service is used.

    • Namespace (string: "")

      Enterprise
      - The namespace to resolve the requested service from to form the failover group of instances. If empty the current namespace is used.

    • Datacenters (array<string>) - A fixed list of datacenters to try during failover.

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

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

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

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

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

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

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

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

      • Field (string: "") - The attribute type to hash on. Must be one of header, cookie, or query_parameter. Cannot be specified along with SourceIP.

      • FieldValue (string: "") - The value to hash. ie. header name, cookie name, URL query parameter name. Cannot be specified along with SourceIP.

      • CookieConfig (CookieConfig) - Additional configuration for the "cookie" hash policy type. This is specified to have Envoy generate a cookie for a client on its first request.

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

        • TTL (duration: 0s) - TTL for generated cookies. Cannot be specified for session cookies.

        • Path (string: "") - The path to set for the cookie.

      • SourceIP (bool: false) - Determines whether the hash should be of the source IP address rather than of a field and field value. Cannot be specified along with Field or FieldValue.

      • Terminal (bool: false) - Will short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a Terminal policy is evaluated, then that hash will be used and subsequent hash policies will be ignored.

»Service Subsets

A service subset assigns a concrete name to a specific subset of discoverable service instances within a datacenter, such as "version2" or "canary".

A service subset name is useful only when composed with an actual service name, a specific datacenter, and namespace.

All services have an unnamed default subset that will return all healthy instances unfiltered.

Subsets are defined in service-resolver configuration entries, but are referenced by their names throughout the other configuration entry kinds.

»ACLs

Configuration entries may be protected by ACLs.

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

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

  • Redirect.Service

  • Failover[].Service

github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager