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:
-
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 (experimental) 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 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.
Follow the Kubernetes Quickstart guide to set up a zone control plane and demo application.
Exclude traffic on certain ports
This example shows how to exclude incoming traffic on port 1234 and outgoing traffic on ports 5678 and 8900.
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 |
runtime.kubernetes.injector.redirect.inbound.excludePorts |
KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS |
runtime.kubernetes.injector.redirect.outbound.excludePorts |
KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS |
| 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 |
|
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.
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 |
runtime.kubernetes.injector.redirect.inbound.excludePortsForIPs |
KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS |
runtime.kubernetes.injector.redirect.outbound.excludePortsForIPs |
KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS |
| 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 |
|