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

»Transparent Proxy

Transparent proxy allows applications to communicate through the mesh without changing their configuration. Transparent proxy also hardens application security by preventing direct inbound connections that bypass the mesh.

»Without Transparent Proxy

Diagram demonstrating that without transparent proxy, applications must "opt in" to connecting to their dependencies through the mesh

Without transparent proxy, application owners need to:

  1. Explicitly configure upstream services, choosing a local port to access them.
  2. Change application to access localhost:<chosen port>.
  3. Configure application to listen only on the loopback interface to prevent unauthorized traffic from bypassing the mesh.

»With Transparent Proxy

Diagram demonstrating that with transparent proxy, connections are automatically routed through the mesh

With transparent proxy:

  1. Upstreams are inferred from service intentions, so no explicit configuration is needed.
  2. Outbound connections pointing to a KubeDNS name "just work" — network rules redirect them through the proxy.
  3. Inbound traffic is forced to go through the proxy to prevent unauthorized direct access to the application.

»Overview

Transparent proxy allows users to reach other services in the service mesh while ensuring that inbound and outbound traffic for services in the mesh are directed through the sidecar proxy. Traffic is secured and only reaches intended destinations since the proxy can enforce security and policy like TLS and Service Intentions.

Previously, service mesh users would need to explicitly define upstreams for a service as a local listener on the sidecar proxy, and dial the local listener to reach the appropriate upstream. Users would also have to set intentions to allow specific services to talk to one another. Transparent proxying reduces this duplication, by determining upstreams implicitly from Service Intentions. Explicit upstreams are still supported in the proxy service registration on VMs and via the annotation in Kubernetes.

To support transparent proxying, Consul's CLI now has a command consul connect redirect-traffic to redirect traffic through an inbound and outbound listener on the sidecar. Consul also watches Service Intentions and configures the Envoy proxy with the appropriate upstream IPs. If the default ACL policy is "allow", then Service Intentions are not required. In Consul on Kubernetes, the traffic redirection command is automatically set up via an init container.

»Prerequisites

»Kubernetes

  • To use transparent proxy on Kubernetes, Consul-helm >= 0.32.0 and Consul-k8s >= 0.26.0 are required in addition to Consul >= 1.10.0.
  • If the default policy for ACLs is "deny", then Service Intentions should be set up to allow intended services to connect to each other. Otherwise, all Connect services can talk to all other services.
  • If using Transparent Proxy, all worker nodes within a Kubernetes cluster must have the ip_tables kernel module running, e.g. modprobe ip_tables.

The Kubernetes integration takes care of registering Kubernetes services with Consul, injecting a sidecar proxy, and enabling traffic redirection.

»Upgrading to Transparent Proxy

When upgrading from older versions (i.e Consul-k8s < 0.26.0 or Consul-helm < 0.32.0) to Consul-k8s >= 0.26.0 and Consul-helm >= 0.32.0, please make sure to follow the upgrade steps here.

»Configuration

»Enabling Transparent Proxy

Transparent proxy can be enabled in Kubernetes on the whole cluster via the Helm value:

connectInject:
  transparentProxy:
    defaultEnabled: true
connectInject:
  transparentProxy:
    defaultEnabled: true

It can also be enabled on a per namespace basis by setting the label consul.hashicorp.com/transparent-proxy=true on the Kubernetes namespace. This will override the Helm value connectInject.transparentProxy.defaultEnabled and define the default behavior of Pods in the namespace. For example:

kubectl label namespaces my-app "consul.hashicorp.com/transparent-proxy=true"
kubectl label namespaces my-app "consul.hashicorp.com/transparent-proxy=true"

It can also be enabled on a per service basis via the annotation consul.hashicorp.com/transparent-proxy=true on the Pod for each service, which will override both the Helm value and the namespace label:

apiVersion: v1
kind: Service
metadata:
  name: static-server
spec:
  selector:
    app: static-server
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: static-server
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: static-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: static-server
  template:
    metadata:
      name: static-server
      labels:
        app: static-server
      annotations:
        'consul.hashicorp.com/connect-inject': 'true'
        'consul.hashicorp.com/transparent-proxy': 'true'
    spec:
      containers:
        - name: static-server
          image: hashicorp/http-echo:latest
          args:
            - -text="hello world"
            - -listen=:8080
          ports:
            - containerPort: 8080
              name: http
      serviceAccountName: static-server
apiVersion: v1
kind: Service
metadata:
  name: static-server
spec:
  selector:
    app: static-server
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: static-server
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: static-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: static-server
  template:
    metadata:
      name: static-server
      labels:
        app: static-server
      annotations:
        'consul.hashicorp.com/connect-inject': 'true'
        'consul.hashicorp.com/transparent-proxy': 'true'
    spec:
      containers:
        - name: static-server
          image: hashicorp/http-echo:latest
          args:
            - -text="hello world"
            - -listen=:8080
          ports:
            - containerPort: 8080
              name: http
      serviceAccountName: static-server

»Kubernetes HTTP Health Probes Configuration

Traffic redirection interferes with Kubernetes HTTP health probes since the probes expect that kubelet can directly reach the application container on the probe's endpoint, but that traffic will be redirected through the sidecar proxy, causing errors because kubelet itself is not encrypting that traffic using a mesh proxy. For this reason, Consul allows you to overwrite Kubernetes HTTP health probes to point to the proxy instead. This can be done using the Helm value connectInject.transparentProxy.defaultOverwriteProbes or the Pod annotation consul.hashicorp.com/transparent-proxy-overwrite-probes.

»Traffic Redirection Configuration

Pods with transparent proxy enabled will have an init container injected that sets up traffic redirection for all inbound and outbound traffic through the sidecar proxies. This will include all traffic by default, with the ability to configure exceptions on a per-Pod basis. The following Pod annotations allow you to exclude certain traffic from redirection to the sidecar proxies:

  • consul.hashicorp.com/transparent-proxy-exclude-inbound-ports
  • consul.hashicorp.com/transparent-proxy-exclude-outbound-ports
  • consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs
  • consul.hashicorp.com/transparent-proxy-exclude-uids

»Known Limitations

  • Traffic can only be transparently proxied when the address dialed corresponds to the address of a service in the transparent proxy's datacenter. Services can also dial explicit upstreams in other datacenters without transparent proxy, for example, by adding an annotation such as "consul.hashicorp.com/connect-service-upstreams": "my-service:1234:dc2" to reach an upstream service called my-service in the datacenter dc2.

  • In the deployment configuration where a single Consul datacenter spans multiple Kubernetes clusters, services in one Kubernetes cluster must explicitly dial a service in another Kubernetes cluster using the consul.hashicorp.com/connect-service-upstreams annotation. An example would be "consul.hashicorp.com/connect-service-upstreams": "my-service:1234", where my-service is the service that exists in another Kubernetes cluster and is exposed on port 1234. Although Transparent Proxy is enabled, KubeDNS is not utilized when communicating between services existing on separate Kubernetes clusters.

  • When dialing headless services, the request will be proxied using a plain TCP proxy. The upstream's protocol is not considered.

»Using Transparent Proxy

In Kubernetes, services can reach other services via their KubeDNS address or via Pod IPs, and that traffic will be transparently sent through the proxy. Connect services in Kubernetes are required to have a Kubernetes service selecting the Pods.

Note: In order to use KubeDNS, the Kubernetes service name will need to match the Consul service name. This will be the case by default, unless the service Pods have the annotation consul.hashicorp.com/connect-service overriding the Consul service name.

Transparent proxy is enabled by default in Consul-helm >=0.32.0. The Helm value used to enable/disable transparent proxy for all applications in a Kubernetes cluster is connectInject.transparentProxy.defaultEnabled.

Each Pod for the service will be configured with iptables rules to direct all inbound and outbound traffic through an inbound and outbound listener on the sidecar proxy. The proxy will be configured to know how to route traffic to the appropriate upstream services based on Service Intentions. This means Connect services no longer need to use the consul.hashicorp.com/connect-service-upstreams annotation to configure upstreams explicitly. Once the Service Intentions are set, they can simply address the upstream services using KubeDNS.

As of Consul-k8s >= 0.26.0 and Consul-helm >= 0.32.0, a Kubernetes service that selects application pods is required for Connect applications, i.e:

apiVersion: v1
kind: Service
metadata:
  name: sample-app
  namespace: default
spec:
  selector:
    app: sample-app
  ports:
    - protocol: TCP
      port: 80
apiVersion: v1
kind: Service
metadata:
  name: sample-app
  namespace: default
spec:
  selector:
    app: sample-app
  ports:
    - protocol: TCP
      port: 80

In the example above, if another service wants to reach sample-app via transparent proxying, it can dial sample-app.default.svc.cluster.local, using KubeDNS. If ACLs with default "deny" policy are enabled, it also needs a ServiceIntention allowing it to talk to sample-app.

»Headless Services

For services that are not addressed using a virtual cluster IP, the upstream service must be configured using the DialedDirectly option.

Individual instance addresses can then be discovered using DNS, and dialed through the transparent proxy. When this mode is enabled on the upstream, connect certificates will be presented for mTLS and intentions will be enforced at the destination.

Note that when dialing individual instances HTTP routing rules configured with config entries will not be considered. The transparent proxy acts as a TCP proxy to the original destination IP address.

github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager