Excluding Traffic from Transparent Proxy Redirection

This guide will show you how to exclude specific types of traffic from being redirected by the transparent proxy. It includes instructions for both Universal and a Kubernetes modes and covers different types of traffic you might want to exclude, such as:

Exclude traffic on certain ports (incoming & outgoing)
Exclude traffic to and from specific IP addresses

Use this guide to control which traffic the transparent proxy intercepts and which it allows through directly.

Key information

This guide shows how to set up the transparent proxy to exclude certain types of traffic from redirection for selected workloads. We’ll cover some methods for both Kubernetes and Universal modes, but not all possible scenarios are explained in detail. For more information on options briefly mentioned here, check out:
Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with Kubernetes Annotations, since the Configuration in ConfigMap option is still experimental. Once it’s stable, it will become the suggested method.

Terminology overview

Workload: In this guide, workload refers to an application running in a Kubernetes cluster, usually represented by a Pod. Kubernetes resources like Deployment, ReplicaSet, and StatefulSet are used to define and manage these workloads, resulting in one or more Pods where the application actually runs.
ConfigMap: In this guide, ConfigMap refers to the Kubernetes ConfigMap resource. It’s used to store configuration data as key-value pairs that can be easily accessed by other resources in the cluster, such as Pods, Deployments, and StatefulSets.
Service: In this guide, service means the application running in a Universal mode environment where the transparent proxy will be installed. This term does not refer to Kubernetes Service resources.

Prerequisites

Understand transparent proxy basics: You should already be familiar with what a transparent proxy is, how to install it, and how to adjust its settings. This guide won’t cover those basics. The following resources can help:
- For options to customize transparent proxy settings, check the resources listed in the Key Information section.
- For an in-depth look at how the transparent proxy works in Kuma and its mechanisms, see the Technical Overview page from its documentation.
- To install the transparent proxy on Universal, refer to Installing Transparent Proxy on Universal.
- For upgrade steps, see Upgrading Transparent Proxy on Universal.
Set up Kuma: Ensure Kuma is installed and running.
- Kubernetes
- Universal
Follow the Kubernetes Quickstart guide to set up a zone control plane and demo application.
Confirm that all necessary components are up and running. The following resources may be useful:
- To set up a single-zone control plane, follow the Single Zone Control Plane Deployment guide.
- To generate a data plane proxy token (needed to authorize data plane proxies), refer to Data Plane Proxy Token documentation.
- To set up your service environment and start the data plane proxy, follow the steps in the Installing section of the Transparent Proxy on Universal documentation up to Step 5: Install the Transparent Proxy.

Exclude traffic on certain ports

This example shows how to exclude incoming traffic on port 1234 and outgoing traffic on ports 5678 and 8900.

Kubernetes
Universal

To exclude these ports in Kubernetes mode, add the traffic.kuma.io/exclude-inbound-ports annotation for incoming traffic and traffic.kuma.io/exclude-outbound-ports for outgoing traffic. For example, your Pod configuration could look like this:

apiVersion: apps/v1
kind: Pod
metadata:
  name: example-app
  annotations:
    traffic.kuma.io/exclude-inbound-ports: "1234"
    traffic.kuma.io/exclude-outbound-ports: "5678,8900"
...

You can add these annotations manually in your Kubernetes manifests or by using this command:

kubectl annotate pods example-app \
  "traffic.kuma.io/exclude-inbound-ports=1234" \
  "traffic.kuma.io/exclude-outbound-ports=5678,8900"

Other configuration options

Configuration in ConfigMap
Field	Environment Variable
`redirect.inbound.excludePorts`	`KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS`
`redirect.outbound.excludePorts`	`KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS`

Control Plane Runtime Configuration
Field	Environment Variable
`runtime.kubernetes.injector.sidecarTraffic.excludeInboundPorts`	`KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS`
`runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts`	`KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS`

To exclude specific ports in Universal mode, configure the transparent proxy with redirect.inbound.excludePorts and redirect.outbound.excludePorts settings. Here’s an example:

echo "
redirect:
  inbound:
    excludePorts: [1234]
  outbound:
    excludePorts: [5678, 8900]
" | kumactl install transparent-proxy --config-file -

Other configuration options

Environment Variables

KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS="1234" \
KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS="5678,8900" \
kumactl install transparent-proxy

CLI Flags

kumactl install transparent-proxy \
  --exclude-inbound-ports "1234" \
  --exclude-outbound-ports "5678,8900"

Exclude traffic to and from specific IP addresses

This example shows how to exclude incoming traffic coming from addresses in range 10.0.0.0/8 and outgoing traffic directed to address 192.168.10.1 or addresses in range fd10::/16.

Kubernetes
Universal

To exclude these addresses in Kubernetes mode, add the traffic.kuma.io/exclude-inbound-ips annotation for incoming traffic and traffic.kuma.io/exclude-outbound-ips for outgoing traffic. For example, your Pod configuration could look like this:

apiVersion: apps/v1
kind: Pod
metadata:
  name: example-app
  annotations:
    traffic.kuma.io/exclude-inbound-ips: "10.0.0.0/8"
    traffic.kuma.io/exclude-outbound-ips: "192.168.10.1,fd10::/16"
...

You can add these annotations manually in your Kubernetes manifests or by using this command:

kubectl annotate pods example-app \
  "traffic.kuma.io/exclude-inbound-ips=10.0.0.0/8" \
  "traffic.kuma.io/exclude-outbound-ips=192.168.10.1,fd10::/16"

Other configuration options

Configuration in ConfigMap
Field	Environment Variable
`redirect.inbound.excludePortsForIPs`	`KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS`
`redirect.outbound.excludePortsForIPs`	`KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS`

Control Plane Runtime Configuration
Field	Environment Variable
`runtime.kubernetes.injector.sidecarTraffic.excludeInboundIPs`	`KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS`
`runtime.kubernetes.injector.sidecarTraffic.excludeOutboundIPs`	`KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS`

To exclude these addresses in Universal mode, configure the transparent proxy with redirect.inbound.excludePortsForIPs and redirect.outbound.excludePortsForIPs settings. Here’s an example:

echo "
redirect:
  inbound:
    excludePortsForIPs: [10.0.0.0/8]
  outbound:
    excludePortsForIPs: [192.168.10.1, fd10::/16]
" | kumactl install transparent-proxy --config-file -

Other configuration options

Environment Variables

KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS="10.0.0.0/8" \
KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS="192.168.10.1,fd10::/16" \
kumactl install transparent-proxy

CLI Flags

kumactl install transparent-proxy \
  --exclude-inbound-ips "10.0.0.0/8" \
  --exclude-outbound-ips "192.168.10.1,fd10::/16"