Careful!

You are browsing documentation for a version of Kuma that is not the latest release.

Looking for even older versions? Learn more.

Excluding Traffic from Transparent Proxy

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 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:
- Customizing Transparent Proxy Configuration in Kubernetes Mode

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 Transparent Proxying documentation.
- To install the transparent proxy in Universal mode, refer to Integrating Transparent Proxy into Your Service Environment.
- For upgrade steps, see Upgrading Transparent Proxy.
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 prepare your service environment and start the data plane proxy, follow the Integrating Transparent Proxy into Your Service Environment guide 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

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

To exclude specific ports in Universal mode, use the --exclude-inbound-ports and --exclude-outbound-ports 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

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

To exclude these addresses in Universal mode, use the --exclude-inbound-ips and --exclude-outbound-ips flags:

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