On Universal, kuma-dp leverages the data plane proxy specification for receiving incoming requests on a pre-defined port.
To enable transparent proxying, the zone control plane must exist on a separate server.
If transparent proxying is on the same machine, you can’t run the zone control plane with PostgreSQL.
There are several advantages when using transparent proxying in Universal mode:
- The
Dataplane resource is simpler because you can omit the outbound section.
- Universal service naming with the
.mesh DNS domain instead of explicit outbounds like https://localhost:10001.
- Better service manageability (for example: security and tracing).
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.
To configure transparent proxying in Universal mode, you must first:
- Install
kuma-dp, envoy, and coredns on the node that runs your service mesh workload.
- Set
coredns in the path so that kuma-dp can access it. You can also set the location with the --dns-coredns-path flag in the kuma-dp command.
Kong Mesh comes with the kumactl executable, which can help you prepare the host for transparent proxying.
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:
-
Create a new dedicated user on the machine.
useradd -u 5678 -U kuma-dp
-
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 \
--redirect-dns \
--exclude-inbound-ports 22
If you’re running any other services on that machine, adjust the comma separated lists of --exclude-inbound-ports and --exclude-outbound-ports accordingly.
This command will change the host’s iptables rules.
The changes won’t persist over restarts. You must either add this command to your start scripts or use firewalld.
In transparent proxying mode, the Dataplane resource should omit the networking.outbound section and use networking.transparentProxying section instead:
type: Dataplane
mesh: default
name: {{ name }}
networking:
address: {{ address }}
inbound:
- port: {{ port }}
tags:
kuma.io/service: demo-client
transparentProxying:
redirectPortInbound: 15006
redirectPortOutbound: 15001
The ports used above are the default ones that kumactl install transparent-proxy will set. These can be changed using the relevant flags to that command.
It’s’ important that the kuma-dp process runs with the same system user that was passed to kumactl install transparent-proxy --kuma-dp-user.
The service itself should run with any other user than kuma-dp. Otherwise, it won’t be able to leverage transparent proxying.
When using systemd, you can invoke the data plane with a User=kuma-dp entry in the [Service] section of the service file.
When starting kuma-dp with a script or some other automation, you can use runuser:
runuser -u kuma-dp -- \
/usr/bin/kuma-dp run \
--cp-address=https://$CONTROL_PLANE_HOST:5678 \
--dataplane-token-file=$TOKEN_FILEPATH \
--dataplane-file=$DATAPLANE_CONFIG_FILE \
--dataplane-var name=dp-demo \
--dataplane-var address=$VM_IP \
--dataplane-var port=$SERVICE_PORT \
--binary-path /usr/local/bin/envoy
Once this is configured, you’ll be able to reach the Service on the same IP and port as before installing transparent proxy, but the traffic will go through Envoy. You can also connect to Services using Kong Mesh DNS.
The core iptables rules that Kong Mesh’s transparent proxy applies rarely change, but new features occasionally require updates.
Before upgrading to the next version of Kong Mesh, we recommend uninstalling the transparent proxy before replacing the kumactl binary:
kumactl uninstall transparent-proxy
v2.9+ If you’re upgrading from Kong Mesh version 2.9 or later, and you have not manually disabled comments by setting comments.disabled to true in the transparent proxy configuration, this step is unnecessary.
Starting with Kong Mesh 2.9, the transparent proxy tags all iptables rules with comments so Kong Mesh can track rule ownership. kumactl uses these comments to automatically clean up rules and custom chains created by previous transparent proxy versions. The cleanup runs at the start of the installation, so no manual cleanup is needed.
To manually remove existing iptables rules, either restart the host (if the rules weren’t persisted with system start-up scripts or firewalld) or run the following commands.
These commands remove all iptables rules and all custom chains in the specified tables, including those created by Kong Mesh and any other applications or services.
iptables --table nat --flush # Flush all rules in the NAT table (IPv4)
ip6tables --table nat --flush # Flush all rules in the NAT table (IPv6)
iptables --table nat --delete-chain # Delete all custom chains in the NAT table (IPv4)
ip6tables --table nat --delete-chain # Delete all custom chains in the NAT table (IPv6)
# The raw table contains rules for DNS traffic redirection
iptables --table raw --flush # Flush all rules in the raw table (IPv4)
ip6tables --table raw --flush # Flush all rules in the raw table (IPv6)
# The mangle table contains rules to drop invalid packets
iptables --table mangle --flush # Flush all rules in the mangle table (IPv4)
ip6tables --table mangle --flush # Flush all rules in the mangle table (IPv6)
Reinstall the transparent proxy:
kumactl install transparent-proxy --kuma-dp-user kuma-dp --redirect-dns --verbose
The command installs the latest version of the transparent proxy with the specified configuration. Adjust the flags as needed for your environment.