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

»Discovery Chain

1.6.0+: This feature is available in Consul versions 1.6.0 and newer.

This topic is part of a low-level API primarily targeted at developers building external Connect proxy integrations.

The service discovery process can be modeled as a "discovery chain" which passes through three distinct stages: routing, splitting, and resolution. Each of these stages is controlled by a set of configuration entries. By configuring different phases of the discovery chain a user can control how proxy upstreams are ultimately resolved to specific instances for load balancing.

Note: The discovery chain is currently only used to discover Connect proxy upstreams.

»Configuration

The configuration entries used in the discovery chain are designed to be simple to read and modify for narrowly tailored changes, but at discovery-time the various configuration entries interact in more complex ways. For example:

  • If a service-resolver is created with a service redirect defined, then all references made to the original service in any other configuration entry is replaced with the redirect destination.

  • If a service-resolver is created with a default subset defined then all references made to the original service in any other configuration entry that did not specify a subset will be replaced with the default.

  • If a service-splitter is created with a service split, and the target service has its own service-splitter then the overall effect is flattened and only a single aggregate traffic split is ultimately configured in the proxy.

  • service-resolver redirect loops must be rejected as invalid.

  • service-router and service-splitter configuration entries require an L7 compatible protocol be set for the service via either a service-defaults or proxy-defaults config entry. Violations must be rejected as invalid.

  • If an upstream configuration datacenter parameter is defined then any configuration entry that does not explicitly refer to a desired datacenter should use that value from the upstream.

»Compilation

To correctly interpret a collection of configuration entries as a valid discovery chain, we first compile them into a form more directly usable by the layers responsible for configuring Connect sidecar proxies.

You can interact with the compiler directly using the discovery-chain API.

»Compilation Parameters

  • Service Name - The service being discovered by name.
  • Datacenter - The datacenter to use as the basis of compilation.
  • Overrides - Discovery-time tweaks to apply when compiling. These should be derived from either the proxy or upstream configurations if either are set.

»Compilation Results

The response is a single wrapped CompiledDiscoveryChain field:

{
    "Chain": {...<CompiledDiscoveryChain>...}
}
{
    "Chain": {...<CompiledDiscoveryChain>...}
}

»CompiledDiscoveryChain

The chain encodes a digraph of nodes and targets. Nodes are the compiled representation of various discovery chain stages and targets are instructions on how to use the health API to retrieve relevant service instance lists.

You should traverse the nodes starting with StartNode. The nodes can be resolved by name using the Nodes field. Targets can be resolved by name using the Targets field.

  • ServiceName (string) - The requested service.

  • Partition (string) - The requested partition.

  • Namespace (string) - The requested namespace.

  • Datacenter (string) - The requested datacenter.

  • CustomizationHash (string: <optional>) - A unique hash of any overrides that affected the compilation of the discovery chain.

    If set, this value should be used to prefix/suffix any generated load balancer data plane objects to avoid sharing customized and non-customized versions.

  • Default (bool: <optional>) - Indicates if this discovery chain is based on no service-resolver, service-splitter, or service-router config entries.

  • Protocol (string) - The overall protocol shared by everything in the chain.

  • ServiceMeta (map<string|string>) - The metadata from the underlying service-defaults config entry for the service named ServiceName.

  • StartNode (string) - The first key into the Nodes map that should be followed when traversing the discovery chain.

  • Nodes (map<string|DiscoveryGraphNode>) - All nodes available for traversal in the chain keyed by a unique name. You can walk this by starting with StartNode.

    The names should be treated as opaque values and are only guaranteed to be consistent within a single compilation.

  • Targets (map<string|DiscoveryTarget>) - A list of all targets used in this chain.

    The names should be treated as opaque values and are only guaranteed to be consistent within a single compilation.

»DiscoveryGraphNode

A single node in the compiled discovery chain.

  • Type (string) - The type of the node. Valid values are: router, splitter, and resolver.

  • Name (string) - The unique name of the node.

  • Routes (array<DiscoveryRoute>) - Only set for Type:router. List of routes to render.

    • Definition (ServiceRoute) - Relevant portion of underlying service-router route.

    • NextNode (string) - The name of the next node in the chain in Nodes.

  • Splits (array<DiscoverySplit>) - Only set for Type:splitter. List of traffic splits.

    • Weight (float32) - Copy of underlying service-splitter weight field.

    • NextNode (string) - The name of the next node in the chain in Nodes.

  • Resolver (DiscoveryResolver: <optional>) - Only set for Type:resolver. How to resolve the service instances.

    • Default (bool) - Set to true if no service-resolver config entry is defined for this node and the default was synthesized.

    • ConnectTimeout (duration) - Copy of the underlying service-resolver ConnectTimeout field. If one is not defined the default of 5s is returned.

    • Target (string) - The name of the target to use found in Targets.

    • Failover (DiscoveryFailover: <optional>) - Compiled form of the underlying service-resolver Failover definition to use for this request.

      • Targets (array<string>) - List of targets found in Targets to failover to in order of preference.
    • LoadBalancer (LoadBalancer: <optional>) - Copy of the underlying service-resolver LoadBalancer field.

      If a service-splitter splits between services with differing LoadBalancer configuration the first hash-based load balancing policy is copied.

»DiscoveryTarget

  • ID (string) - The unique name of this target.

  • Service (string) - The service to query when resolving a list of service instances.

  • ServiceSubset (string: <optional>) - The subset of the service to resolve.

  • Partition (string) - The partition to use when resolving a list of service instances.

  • Namespace (string) - The namespace to use when resolving a list of service instances.

  • Datacenter (string) - The datacenter to use when resolving a list of service instances.

  • Subset (ServiceResolverSubset) - Copy of the underlying service-resolver Subsets definition for this target.

    • Filter (string: "") - The filter expression to be used for selecting instances of the requested service. If empty all healthy instances are returned.

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

  • MeshGateway (MeshGatewayConfig) - The mesh gateway configuration to use when connecting to this target's service instances.

    • Mode (string: "") - One of none, local, or remote.
  • External (bool: false) - True if this target is outside of this consul cluster.

  • ConnectTimeout (duration) - Copy of the underlying service-resolver ConnectTimeout field. If one is not defined the default of 5s is returned.

  • SNI (string) - This value should be used as the SNI value when connecting to this set of endpoints over TLS.

  • Name (string) - The unique name for this target for use when generating load balancer objects. This has a structure similar to SNI, but will not be affected by SNI customizations such as ExternalSNI.

github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager