Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Mesh
2.0.x
  • Home icon
  • Kong Mesh
  • Networking
  • Transparent Proxying
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.4.x (latest)
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Kubernetes
  • Universal
    • Setting up the service host
    • Data plane proxy resource
    • Invoking the Kong Mesh data plane
    • firewalld support
    • Upgrades
  • Configuration
    • Intercepted traffic
    • Reachable Services
    • Transparent Proxy with eBPF (experimental)
You are browsing documentation for an outdated version. See the latest documentation here.

Transparent Proxying

In order to automatically intercept traffic from and to a service through a kuma-dp data plane proxy instance, Kong Mesh utilizes a transparent proxying using iptables.

Transparent proxying helps with a smoother rollout of a Service Mesh to a current deployment by preserving existing service naming and as the result - avoid changes to the application code.

Kubernetes

On Kubernetes kuma-dp leverages transparent proxying automatically via iptables installed with kuma-init container or CNI. All incoming and outgoing traffic is automatically intercepted by kuma-dp without having to change the application code.

Kong Mesh integrates with a service naming provided by Kubernetes DNS as well as providing its own Kong Mesh DNS for multizone service naming.

Universal

On Universal kuma-dp leverages the data plane proxy specification associated to it for receiving incoming requests on a pre-defined port.

There are several advantages for using transparent proxying in universal mode:

  • Simpler Dataplane resource, as the outbound section becomes obsolete and can be skipped.
  • Universal service naming with .mesh DNS domain instead of explicit outbound like https://localhost:10001.
  • Support for hostnames of your choice using VirtualOutbounds that lets you preserve existing service naming.
  • Better service manageability (security, tracing).

Setting up the service host

Prerequisites:

  • kuma-dp, envoy, and coredns must run on the worker node – that is, the node that runs your service mesh workload.
  • coredns must be in the PATH so that kuma-dp can access it.
    • You can also set the location with the --dns-coredns-path flag to kuma-dp.

Kong Mesh comes with kumactl executable which can help us to prepare the host. Due to the wide variety of Linux setup options, these steps may vary and may need to be adjusted for the specifics of the particular deployment. The host that will run the kuma-dp process in transparent proxying mode needs to be prepared with the following steps executed as root:

  1. Create a new dedicated user on the machine.

    useradd -u 5678 -U kuma-dp
    
  2. Redirect all the relevant inbound, outbound and DNS traffic to the Kong Mesh data plane proxy.

    kumactl install transparent-proxy \
      --kuma-dp-user kuma-dp \
      --skip-resolv-conf \
      --redirect-dns
    

Please note that this command will change the host iptables rules.

The changes will persist over restarts, so this command is needed only once. Reverting to the original state of the host can be done by issuing kumactl uninstall transparent-proxy.

Data plane proxy resource

In transparent proxying mode, the Dataplane resource should omit the networking.outbound section and use networking.transparentProxying section instead.

type: Dataplane
mesh: default
name: 
networking:
  address: 
  inbound:
  - port: 
    tags:
      kuma.io/service: demo-client
  transparentProxying:
    redirectPortInbound: 15006
    redirectPortOutbound: 15001

The ports illustrated above are the default ones that kumactl install transparent-proxy will set. These can be changed using the relevant flags to that command.

Invoking the Kong Mesh data plane

It is important that the kuma-dp process runs with the same system user that was passed to kumactl install transparent-proxy --kuma-dp-user.

When systemd is used, this can be done with an entry User=kuma-dp in the [Service] section of the service file.

When starting kuma-dp with a script or some other automation instead, we can use runuser with the aforementioned yaml resource as follows:

runuser -u kuma-dp -- \
  /usr/bin/kuma-dp run \
    --cp-address=https://<IP or hostname of CP>:5678 \
    --dataplane-token-file=/kuma/token-demo \
    --dataplane-file=/kuma/dpyaml-demo \
    --dataplane-var name=dp-demo \
    --dataplane-var address=<IP of VM> \
    --dataplane-var port=<Port of the service>  \
    --binary-path /usr/local/bin/envoy

You can now reach the service on the same IP and port as before installing transparent proxy, but now the traffic goes through Envoy. At the same time, you can now connect to services using Kong Mesh DNS.

firewalld support

If you run firewalld to manage firewalls and wrap iptables, add the --store-firewalld flag to kumactl install transparent-proxy. This persists the relevant rules across host restarts. The changes are stored in /etc/firewalld/direct.xml. There is no uninstall command for this feature.

Upgrades

Before upgrading to the next version of Kong Mesh, make sure to run kumactl uninstall transparent-proxy and only then replace the kumactl binary. This will ensure smooth upgrade and no leftovers from the previous installations.

Configuration

Intercepted traffic

Kubernetes
Universal

By default, all the traffic is intercepted by Envoy. You can exclude which ports are intercepted by Envoy with the following annotations placed on the Pod

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  ...
  template:
    metadata:
      ...
      annotations:
        # all incomming connections on ports 1234 won't be intercepted by Envoy
        traffic.kuma.io/exclude-inbound-ports: "1234"
        # all outgoing connections on ports 5678, 8900 won't be intercepted by Envoy
        traffic.kuma.io/exclude-outbound-ports: "5678,8900"
    spec:
      containers:
        ...

You can also control this value on whole Kong Mesh deployment with the following Kong Mesh CP configuration

KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS=1234
KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS=5678,8900

The default settings will exclude the SSH port 22 from the redirection, thus allowing the remote access to the host to be preserved. If the host is set up to use other remote management mechanisms, use --exclude-inbound-ports to provide a comma separated list of the TCP ports that will be excluded from the redirection.

Execute kumactl install transparent-proxy --help to see available options.

Reachable Services

By default, every data plane proxy in the mesh follows every other data plane proxy. This may lead to performance problems in larger deployments of the mesh. It is highly recommended to define a list of services that your service connects to.

Kubernetes
Universal
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  ...
  template:
    metadata:
      ...
      annotations:
        # a comma separated list of kuma.io/service values
        kuma.io/transparent-proxying-reachable-services: "redis_kuma-demo_svc_6379,elastic_kuma-demo_svc_9200"
    spec:
      containers:
        ...
type: Dataplane
mesh: default
name: 
networking:
  address: 
  inbound:
  - port: 
    tags:
      kuma.io/service: demo-client
  transparentProxying:
    redirectPortInbound: 15006
    redirectPortOutbound: 15001
    reachableServices:
      - redis_kuma-demo_svc_6379
      - elastic_kuma-demo_svc_9200 

Transparent Proxy with eBPF (experimental)

Starting from Kong Mesh 2.0 you can setup transparent proxy to use eBPF instead of iptables.

To use Transparent Proxy with eBPF your environment has to use Kernel >= 5.7 and have cgroup2 available

Kubernetes
Universal
kumactl install control-plane \
  --set "kuma.experimental.ebpf.enabled=true" | kubectl apply -f-
kumactl install transparent-proxy \
  --experimental-transparent-proxy-engine \
  --ebpf-enabled \
  --ebpf-instance-ip <IP_ADDRESS> \
  --ebpf-programs-source-path <PATH>

If your environment contains more than one non-loopback network interface, and you want to specify explicitly which one should be used for transparent proxying you should provide it using--ebpf-tc-attach-iface <IFACE_NAME> flag, during transparent proxy installation.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023