Integrating Transparent Proxy into Your Service Environment

This guide provides a step-by-step walk-through on integrating a transparent proxy into your service environment using Kuma. Transparent proxy simplifies service management and traffic routing within a mesh, ensuring that all traffic flows through the designated data plane proxy without requiring changes to your application code.

By the end of this guide, your service will be running under a transparent proxy, allowing you to leverage Kuma’s advanced service management features, such as traffic control, observability, and security.

Make sure to review the key assumptions and information outlined in the guide before proceeding with the installation. Adjust the parameters as needed to match your environment’s specific details, such as IP addresses, custom ports, and DNS configurations.

Terminology overview

• Service: In this guide, service refers to an application running in the environment where the transparent proxy is deployed. An exception is when we refer to systemd services; in these cases, service specifically means a systemd service unit.

Prerequisites

1. Control plane deployment and network accessibility: Ensure Kuma’s Control Plane is already deployed and accessible from the service via an IP address or DNS name. Adapt the steps below to reflect the correct address for your setup.

   For this guide, the Control Plane should not be deployed in the same environment as the transparent proxy. This is because the transparent proxy redirects all traffic (unless specifically excluded) to kuma-dp, including traffic meant for the Control Plane.

   While it is technically possible to manually exclude Control Plane traffic during setup, this is complex and easy to misconfigure, as it requires excluding all necessary ports and routes.

   In real deployments, you can work around it by running the Control Plane and other components in separate network namespaces using systemd, which keeps Control Plane traffic separate from kuma-dp and the service.

   For deployment instructions, see Deploy a Single Zone Control Plane.

2. Service accessibility: Ensure the environment with the transparent proxy and service is reachable by other services in the mesh via IP or DNS. Adjust the setup steps to match the appropriate address where the service is accessible.

3. Data plane proxy token: Place the data plane proxy token at /kuma/example-server-token (or adjust the steps if stored elsewhere).

   For instructions on generating this token, refer to the Data Plane Proxy Token section in the Authentication with the Data Plane Proxy documentation.

4. Binary availability: Ensure kuma-dp, envoy, and coredns binaries are accessible in /usr/local/bin/, and kumactl is in the system’s PATH. Adjust any subsequent commands if the binaries are located elsewhere.

   To easily download all necessary binaries, you can use the following script, which automatically detects your operating system and fetches the required binaries:

   curl -L https://kuma.io/installer.sh | VERSION=2.9.0 sh -

   Omitting the VERSION variable will install the latest version.

Step 1: Create a dedicated user for kuma-dp

For proper functionality, the service must run under a different user than the one designated for running kuma-dp. If both the service and kuma-dp are run by the same user, the transparent proxy will not work correctly, causing service traffic (inbound and outbound) to fail. To create a dedicated user for kuma-dp, use the following command:

useradd -u kuma-dp -U kuma-dp

Step 2: Prepare Dataplane resource

In transparent proxy mode, configure your Dataplane resource without the networking.outbound section. Instead, use networking.transparentProxying for handling traffic redirection. Here’s an example:

If your /kuma/example-server-dataplane.yaml looks like this:

type: Dataplane
mesh: default
name: {{ name }}
networking:
  address: {{ address }}
  inbound:
    - port: {{ port }}
      tags:
        kuma.io/service: example-server
  outbound:
    - port: 6379
      tags:
        kuma.io/service: redis

After updating it for transparent proxy, it should look like this:

type: Dataplane
mesh: default
name: {{ name }}
networking:
  address: {{ address }}
  inbound:
    - port: {{ port }}
      tags:
        kuma.io/service: example-server
  transparentProxying:
    redirectPortInbound: 15006
    redirectPortOutbound: 15001

Redirect ports

In this example, 15006 and 15001 are the default ports for inbound and outbound traffic redirection. You can change these ports in the transparent proxy configuration during installation (redirect.inbound.port and redirect.outbound.port). For more details, see the Transparent Proxy Configuration Reference.

Using variables in your configuration

The placeholders {{ name }}, {{ address }}, and {{ port }} are Mustache templates, which will be dynamically filled using values passed via --dataplane-var CLI flags in a later step.

In practice, if these values are static, you can simply hard-code them in your configuration. This feature is designed to allow more flexible and reusable resources, making it easier to dynamically adjust values when starting kuma-dp.

More resources

For additional information on setting up the Dataplane resource, refer to the Data Plane on Universal documentation.

Step 3: Start service

The service can be started in various ways depending on your environment and requirements. To keep this guide simple, we’ll use Python 3’s built-in HTTP server. This server will listen on port 8080, with both STDOUT and STDERR redirected to a service.log file in the current directory, running in the background.

To start the service:

python3 -m http.server 8080 > service.log 2>&1 &

Step 4: Start kuma-dp

If you are using systemd to manage processes, you can refer to the Systemd documentation for an example of a systemd resource that can be customized to run kuma-dp in your environment.

Alternatively, if you’re starting kuma-dp using a script or another form of automation, you can use runuser to run the process as the kuma-dp user. Below is an example of how to start kuma-dp with the necessary parameters:

# Set the Control Plane address (IP or DNS) accessible by this environment
export CP_ADDRESS="..."  

# Set the Data Plane address (IP or DNS) for the current environment, accessible by
# other services
export DP_ADDRESS="..."

runuser -u kuma-dp -- \
  /usr/local/bin/kuma-dp run \
    --cp-address="https://$CP_ADDRESS:5678" \
    --dataplane-token-file="/kuma/example-server-token" \
    --dataplane-file="/kuma/example-server-dataplane.yaml" \
    --dataplane-var="name=example-server-dataplane" \
    --dataplane-var="address=$DP_ADDRESS" \
    --dataplane-var="port=8080" \
    --binary-path="/usr/local/bin/envoy" \
    --dns-coredns-path="/usr/local/bin/coredns"

This command runs kuma-dp under the kuma-dp user, connects it to the control plane, and configures it with the necessary settings for the example server. Adjust the paths and values as needed for your specific setup.

Step 5: Install transparent proxy

Before proceeding with this step, please keep the following in mind:

kumactl install transparent-proxy --redirect-dns --exclude-inbound-ports "22"

To install the transparent proxy in your environment, run the following command:

kumactl install transparent-proxy --redirect-dns

This will result in the following:

• The transparent proxy will be set up to use the kuma-dp user as the designated user for running the kuma-dp process.

  By default, kumactl searches for a user with UID 5678 or the username kuma-dp. If you prefer to use a custom username or UID, you can specify it using the --kuma-dp-user flag. If the specified user cannot be found, the installation process will fail with an error.

• All incoming traffic will be redirected to kuma-dp on port 15006.

  Port 15006 is the default for redirecting incoming traffic. If you used a different port in your Dataplane resource definition, ensure it aligns with the transparent proxy configuration. To update it, modify the redirect.inbound.port setting during installation, for example by using the --redirect-inbound-port flag.

• All outgoing traffic will be redirected to kuma-dp on default port 15001.

  Port 15001 is the default used for redirecting outgoing traffic. If you used a different port in your Dataplane resource definition, ensure it aligns with the transparent proxy configuration. To update it, modify the redirect.outbound.port setting during installation, for example by using the --redirect-outbound-port flag.

• DNS traffic directed to the DNS servers configured in /etc/resolv.conf will be redirected to the coredns managed by kuma-dp on port 15053.

  Port 15053 is the default used for redirecting DNS traffic. If you wish to modify this port, it is crucial to ensure consistency between the transparent proxy and kuma-dp. In this case, you must update the kuma-dp run command to include the --dns-coredns-port flag with the desired custom port. To adjust it for the transparent proxy, modify the redirect.dns.port setting during installation, for example by using the --redirect-dns-port flag.

  /etc/resolv.conf is the file used by default to parse DNS servers for redirecting DNS traffic through the transparent proxy. This file is relevant only if you opt to redirect DNS traffic specifically to the DNS servers listed within it (for example, by using the --redirect-dns flag during installation). If you’re redirecting all DNS traffic (for example, by using the --redirect-all-dns-traffic flag), this path becomes irrelevant.

  We strongly recommend against changing this path. However, if your environment uses a different file to specify DNS servers (which must follow the same format as /etc/resolv.conf), you can adjust it by modifying the redirect.dns.resolvConfigPath setting during installation. This can be done, for example, using the KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_RESOLV_CONFIG_PATH environment variable.

Additional resources

• Excluding traffic from transparent proxy redirection: If you need to prevent certain services or specific types of traffic from being routed through kuma-dp, you can fine-tune the transparent proxy configuration to exclude them. For more information, refer to the Excluding Traffic From Transparent Proxy Redirection guide.

• Customizing transparent proxy configuration: For detailed instructions on customizing the transparent proxy configuration, see the Configure transparent proxying documentation.

• Upgrading transparent proxy: If you need to upgrade your transparent proxy, refer to the Upgrading Transparent Proxy guide for the necessary steps and best practices.

• Configuration reference: For detailed information on transparent proxy settings, check the Transparent Proxy Configuration Reference.