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-to-service Traffic Across Partitions

Consul Enterprise 1.11.0+: Admin partitions are supported in Consul Enterprise versions 1.11.0 and newer.

Mesh gateways enable you to route service mesh traffic between different Consul admin partitions. Partitions can reside in different clouds or runtime environments where general interconnectivity between all services in all partitions isn't feasible.

Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. The gateway does not decrypt the data within the mTLS session.

»Prerequisites

Ensure that your Consul environment meets the following requirements.

»Consul

  • Consul Enterprise version 1.11.0 or newer.
  • A local Consul agent is required to manage its configuration.
  • Consul service mesh must be enabled in all partitions. Refer to the connect documentation for details.
  • Each partition must have a unique name. Refer to the admin partitions documentation for details.
  • If you want to enable gateways globally you must enable centralized configuration.

»Proxy

Envoy is the only proxy with mesh gateway capabilities in Consul.

Mesh gateway proxies receive their configuration through Consul, which automatically generates it based on the proxy's registration. Consul can only translate mesh gateway registration information into Envoy configuration.

Sidecar proxies that send traffic to an upstream service through a gateway need to know the location of that gateway. They discover the gateway based on their sidecar proxy registrations. Consul can only translate the gateway registration information into Envoy configuration.

Sidecar proxies that do not send upstream traffic through a gateway are not affected when you deploy gateways. If you are using Consul's built-in proxy as a Connect sidecar it will continue to work for intra-datacenter traffic and will receive incoming traffic even if that traffic has passed through a gateway.

»Configuration

Configure the following settings to register the mesh gateway as a service in Consul.

  • Specify mesh-gateway in the kind field to register the gateway with Consul.
  • Configure the proxy.upstreams parameters to route traffic to the correct service, namespace, and partition. Refer to the upstreams documentation for details. The service proxy.upstreams.destination_name is always required. The proxy.upstreams.destination_partition must be configured to enable cross-partition traffic. The proxy.upstreams.destination_namespace configuration is only necessary if the destination service is in a different namespace.
  • Configure the exported-services configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the Exported Services documentation for details.
  • Define the Proxy.Config settings using opaque parameters compatible with your proxy, i.e., Envoy. For Envoy, refer to the Gateway Options and Escape-hatch Overrides documentation for additional configuration information.
  • If ACLs are enabled, a token granting service:write for the gateway's service name and service:read for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications.

»Modes

Each upstream associated with a service mesh proxy can be configured so that it is routed through a mesh gateway. Depending on your network, the proxy's connection to the gateway can operate in one of the following modes:

  • none - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly to the destination services.

  • local - The service mesh connect proxy makes an outbound connection to a gateway running in the same datacenter. The gateway at the outbound connection is responsible for ensuring that the data is forwarded to gateways in the destination partition.

  • remote - The service mesh connect proxy makes an outbound connection to a gateway running in the destination datacenter. The gateway forwards the data to the final destination service.

»Connect Proxy Configuration

Set the proxy to the preferred mode to configure the service mesh proxy. You can specify the mode globally or within child configurations to control proxy behaviors at a lower level. Consul recognizes the following order of precedence if the gateway mode is configured in multiple locations the order of precedence:

  1. Upstream definition (highest priority)
  2. Service instance definition
  3. Centralized service-defaults configuration entry
  4. Centralized proxy-defaults configuration entry

»Example Configurations

Use the following example configurations to help you understand some of the common scenarios.

»Enabling Gateways Globally

The following proxy-defaults configuration will enable gateways for all Connect services in the local mode.

Example: Enabling gateways globally.
Example: Enabling gateways globally.
HCL
  • HCL
  • YAML
Kind = "proxy-defaults"
Name = "global"
MeshGateway {
   Mode = "local"
}
Kind = "proxy-defaults"
Name = "global"
MeshGateway {
   Mode = "local"
}
Kind: proxy-defaults
MeshGateway:
- Mode: local
Name: global
Kind: proxy-defaults
MeshGateway:
- Mode: local
Name: global

»Enabling Gateways Per Service

The following service-defaults configuration will enable gateways for all Connect services with the name web.

Example: Enabling gateways per service.
Example: Enabling gateways per service.
HCL
  • HCL
  • YAML
Kind = "service-defaults"
Name = "web"
MeshGateway {
   Mode = "local"
}
Kind = "service-defaults"
Name = "web"
MeshGateway {
   Mode = "local"
}
Kind: service-defaults
MeshGateway:
- Mode: local
Name: web
Kind: service-defaults
MeshGateway:
- Mode: local
Name: web

»Enabling Gateways for a Service Instance

The following Proxy Service Registration definition will enable gateways for web service instances in the finance partition.

Example: Enabling gateways for a service instance.
Example: Enabling gateways for a service instance.
HCL
  • HCL
  • YAML
service {
   name = "web-sidecar-proxy"
   kind = "connect-proxy"
   port = 8181
   proxy {
      destination_service_name = "web"
      mesh_gateway {
         mode = "local"
      }
      upstreams = [
         {
            destination_partition = "finance"
            destination_namespace = "default"
            destination_type = "service"
            destination_name = "billing"
            local_bind_port = 9090
         }
      ]
   }
}
service {
   name = "web-sidecar-proxy"
   kind = "connect-proxy"
   port = 8181
   proxy {
      destination_service_name = "web"
      mesh_gateway {
         mode = "local"
      }
      upstreams = [
         {
            destination_partition = "finance"
            destination_namespace = "default"
            destination_type = "service"
            destination_name = "billing"
            local_bind_port = 9090
         }
      ]
   }
}
service:
- kind: connect-proxy
  name: web-sidecar-proxy
  port: 8181
  proxy:
  - destination_service_name: web
    mesh_gateway:
    - mode: local
    upstreams:
    - destination_name: billing
      destination_namespace: default
      destination_partition: finance
      destination_type: service
      local_bind_port: 9090
service:
- kind: connect-proxy
  name: web-sidecar-proxy
  port: 8181
  proxy:
  - destination_service_name: web
    mesh_gateway:
    - mode: local
    upstreams:
    - destination_name: billing
      destination_namespace: default
      destination_partition: finance
      destination_type: service
      local_bind_port: 9090

»Enabling Gateways for a Proxy Upstream

The following service definition will enable gateways in local mode for three different partitions. Note that each service exists in the same namespace, but are separated by admin partition.

Example: Enabling gateways for a proxy upstream.
Example: Enabling gateways for a proxy upstream.
HCL
  • HCL
  • YAML
service {
   name = "web-sidecar-proxy"
   kind = "connect-proxy"
   port = 8181
   proxy {
      destination_service_name = "web"
      upstreams = [
         {
            destination_name = "api"
            destination_namespace = "dev"
            destination_partition = "api"
            local_bind_port = 10000
            mesh_gateway {
               mode = "local"
            }
         },
         {
            destination_name = "db"
            destination_namespace = "dev"
            destination_partition = "db"
            local_bind_port = 10001
            mesh_gateway {
               mode = "local"
            }
         },
         {
            destination_name = "logging"
            destination_namespace = "dev"
            destination_partition = "logging"
            local_bind_port = 10002
            mesh_gateway {
               mode = "local"
            }
         },
      ]
   }
}
service {
   name = "web-sidecar-proxy"
   kind = "connect-proxy"
   port = 8181
   proxy {
      destination_service_name = "web"
      upstreams = [
         {
            destination_name = "api"
            destination_namespace = "dev"
            destination_partition = "api"
            local_bind_port = 10000
            mesh_gateway {
               mode = "local"
            }
         },
         {
            destination_name = "db"
            destination_namespace = "dev"
            destination_partition = "db"
            local_bind_port = 10001
            mesh_gateway {
               mode = "local"
            }
         },
         {
            destination_name = "logging"
            destination_namespace = "dev"
            destination_partition = "logging"
            local_bind_port = 10002
            mesh_gateway {
               mode = "local"
            }
         },
      ]
   }
}
service:
- kind: connect-proxy
  name: web-sidecar-proxy
  port: 8181
  proxy:
  - destination_service_name: web
    upstreams:
    - destination_name: api
      destination_namespace: dev
      destination_partition: api
      local_bind_port: 10000
      mesh_gateway:
      - mode: local
    - destination_name: db
      destination_namespace: dev
      destination_partition: db
      local_bind_port: 10001
      mesh_gateway:
      - mode: local
    - destination_name: logging
      destination_namespace: dev
      destination_partition: logging
      local_bind_port: 10002
      mesh_gateway:
      - mode: local
service:
- kind: connect-proxy
  name: web-sidecar-proxy
  port: 8181
  proxy:
  - destination_service_name: web
    upstreams:
    - destination_name: api
      destination_namespace: dev
      destination_partition: api
      local_bind_port: 10000
      mesh_gateway:
      - mode: local
    - destination_name: db
      destination_namespace: dev
      destination_partition: db
      local_bind_port: 10001
      mesh_gateway:
      - mode: local
    - destination_name: logging
      destination_namespace: dev
      destination_partition: logging
      local_bind_port: 10002
      mesh_gateway:
      - mode: local
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager