Careful!

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

Looking for even older versions? Learn more.

Upgrading Transparent Proxy

In Kubernetes mode, transparent proxy automatically updates with the Kuma version upgrade. No additional steps are required for workloads, as the transparent proxy aligns with the Kuma version. The following guide applies only to Universal mode.

The core iptables rules applied by Kuma’s transparent proxy rarely change, but occasionally new features may require updates. To upgrade the transparent proxy on Universal environments, follow these steps:

Step 1: Cleanup existing iptables rules

If you’re installing a new version of the transparent proxy, it’s crucial to clear any existing iptables rules or custom chains related to the previous installation.

To manually remove existing iptables rules, you can either restart the host (if the rules were not persisted using system start-up scripts or firewalld), or run the following commands:

These commands will remove all iptables rules and all custom chains in the specified tables, including those created by Kuma as well as 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)

Starting with Kuma 2.9, kumactl includes a built-in command to uninstall the transparent proxy, streamlining the cleanup process:

kumactl uninstall transparent-proxy

Step 2: Install new transparent proxy

After clearing the iptables rules, reinstall the transparent proxy by running:

kumactl install transparent-proxy [...]

This command will install the new version of the transparent proxy with the specified configuration. Adjust the flags as needed to suit your environment.

For a comprehensive guide on installing the transparent proxy, including details on preparing the environment, understanding any restrictions, and configuring Dataplane objects to work with the transparent proxy, refer to the Integrating Transparent Proxy into Your Service Environment guide.