Kuma Star

Transparent Proxy Configuration

During transparent proxy installation Kuma under the hood is using a common structure, which can be modified in multiple different ways. By modifying it you are able to for example exclude some ports or IPs from transparent proxy redirection, configure if it should handle both IPv4 and IPv6 or just IPv4 traffic and more.

Simplified reference

This section provides a simplified version of the Full Reference. It’s useful when you want to view the entire configuration in context without diving into the specifics of each individual setting.

Schema

Below is a concise schema of the transparent proxy configuration, including default values:

# The username or UID of the user that will run kuma-dp
kumaDPUser: string
# The IP family mode used for configuring traffic redirection in the transparent proxy
ipFamilyMode: enum # default: "dualstack"
redirect:
  inbound:
    # Enables inbound traffic redirection
    enabled: bool # default: true
    # Port used for redirecting inbound traffic
    port: Port # default: 15006
    # List of ports to include in inbound traffic redirection
    includePorts: []Port
    # List of ports to exclude from inbound traffic redirection
    excludePorts: []Port
    # List of IP addresses to exclude from inbound traffic redirection for specific ports
    excludePortsForIPs: []string
    # List of UIDs to exclude from inbound traffic redirection for specific ports
    excludePortsForUIDs: []string
    # Inserts the redirection rule at the beginning of the chain instead of appending it
    insertRedirectInsteadOfAppend: bool
  outbound:
    # Enables outbound traffic redirection
    enabled: bool # default: true
    # Port used for redirecting outbound traffic
    port: Port # default: 15001
    # List of ports to include in outbound traffic redirection
    includePorts: []Port
    # List of ports to exclude from outbound traffic redirection
    excludePorts: []Port
    # List of IP addresses to exclude from outbound traffic redirection for specific ports
    excludePortsForIPs: []string
    # List of UIDs to exclude from outbound traffic redirection for specific ports
    excludePortsForUIDs: []string
    # Inserts the redirection rule at the beginning of the chain instead of appending it
    insertRedirectInsteadOfAppend: bool
  dns:
    # Enables DNS redirection in the transparent proxy
    enabled: bool
    # The port on which the DNS server listens
    port: Port # default: 15053
    # Redirect all DNS queries
    captureAll: bool
    # Disables conntrack zone splitting, which can prevent potential DNS issues
    skipConntrackZoneSplit: bool
    # Path to the system's resolv.conf file
    resolvConfigPath: string # default: "/etc/resolv.conf"
  vnet:
    # Specifies virtual networks using the format interfaceName:CIDR
    networks: []string
ebpf:
  # Enables eBPF support for handling traffic redirection in the transparent proxy
  enabled: bool
  instanceIP: string
  # The name of the environment variable containing the IP address of the instance (pod/vm) where transparent proxy will be installed
  instanceIPEnvVarName: string
  # The path of the BPF filesystem
  bpffsPath: string # default: "/run/kuma/bpf"
  # The path of cgroup2
  cgroupPath: string # default: "/sys/fs/cgroup"
  # Path where compiled eBPF programs and other necessary files for eBPF mode can be found
  programsSourcePath: string # default: "tmp/kuma-ebpf"
  # The network interface for TC eBPF programs to bind to
  tcAttachIface: string
retry:
  # The maximum number of retry attempts for operations
  maxRetries: uint # default: 4
  # The time duration to wait between retry attempts
  sleepBetweenRetries: Duration # default: "2s"
iptablesExecutables:
  # Custom path for the iptables executable (IPv4)
  iptables: string
  # Custom path for the iptables-save executable (IPv4)
  iptables-save: string
  # Custom path for the iptables-restore executable (IPv4)
  iptables-restore: string
  # Custom path for the ip6tables executable (IPv6)
  ip6tables: string
  # Custom path for the ip6tables-save executable (IPv6)
  ip6tables-save: string
  # Custom path for the ip6tables-restore executable (IPv6)
  ip6tables-restore: string
log:
  # Specifies the log level for iptables logging as defined by netfilter
  level: enum # default: 7
  # Enables logging of iptables rules for diagnostics and monitoring
  enabled: bool
comments:
  # Disables comments in the generated iptables rules
  disabled: bool
# Time in seconds to wait for acquiring the xtables lock before failing
wait: uint # default: 5
# Time interval between retries to acquire the xtables lock in seconds
waitInterval: uint
# Drops invalid packets to avoid connection resets in high-throughput scenarios
dropInvalidPackets: bool
# Enables firewalld support to store iptables rules
storeFirewalld: bool
cniMode: bool
dryRun: bool
# Enables verbose mode with longer argument/flag names and additional comments
verbose: bool

Custom Types

  • Port - uint16 value greater than 0
  • Duration - string representation of time duration, that is "10s", "20m", "1h" etc.

Environment variables

The following structure lists the settings along with their corresponding environment variables for customization:

kumaDPUser: KUMA_TRANSPARENT_PROXY_KUMA_DP_USER
ipFamilyMode: KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE
redirect:
  inbound:
    enabled: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_ENABLED
    port: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_PORT
    includePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_INCLUDE_PORTS
    excludePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS
    excludePortsForIPs: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS
    excludePortsForUIDs: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_UIDS
    insertRedirectInsteadOfAppend: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND
  outbound:
    enabled: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_ENABLED
    port: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_PORT
    includePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_INCLUDE_PORTS
    excludePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS
    excludePortsForIPs: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS
    excludePortsForUIDs: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_UIDS
    insertRedirectInsteadOfAppend: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND
  dns:
    enabled: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_ENABLED
    port: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT
    captureAll: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_CAPTURE_ALL
    skipConntrackZoneSplit: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_SKIP_CONNTRACK_ZONE_SPLIT
    resolvConfigPath: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_RESOLV_CONFIG_PATH
  vnet:
    networks: KUMA_TRANSPARENT_PROXY_REDIRECT_VNET_NETWORKS
ebpf:
  enabled: KUMA_TRANSPARENT_PROXY_EBPF_ENABLED
  instanceIP: KUMA_TRANSPARENT_PROXY_EBPF_INSTANCE_IP
  instanceIPEnvVarName: KUMA_TRANSPARENT_PROXY_EBPF_INSTANCE_IP_ENV_VAR_NAME
  bpffsPath: KUMA_TRANSPARENT_PROXY_EBPF_BPFFS_PATH
  cgroupPath: KUMA_TRANSPARENT_PROXY_EBPF_CGROUP_PATH
  programsSourcePath: KUMA_TRANSPARENT_PROXY_EBPF_PROGRAMS_SOURCE_PATH
  tcAttachIface: KUMA_TRANSPARENT_PROXY_EBPF_TC_ATTACH_IFACE
retry:
  maxRetries: KUMA_TRANSPARENT_PROXY_RETRY_MAX_RETRIES
  sleepBetweenRetries: KUMA_TRANSPARENT_PROXY_RETRY_SLEEP_BETWEEN_RETRIES
iptablesExecutables: KUMA_TRANSPARENT_PROXY_IPTABLES_EXECUTABLES
log:
  enabled: KUMA_TRANSPARENT_PROXY_LOG_ENABLED
  level: KUMA_TRANSPARENT_PROXY_LOG_LEVEL
comments:
  disabled: KUMA_TRANSPARENT_PROXY_COMMENTS_DISABLED
wait: KUMA_TRANSPARENT_PROXY_WAIT
waitInterval: KUMA_TRANSPARENT_PROXY_WAIT_INTERVAL
dropInvalidPackets: KUMA_TRANSPARENT_PROXY_DROP_INVALID_PACKETS
storeFirewalld: KUMA_TRANSPARENT_PROXY_STORE_FIREWALLD
cniMode: KUMA_TRANSPARENT_PROXY_CNI_MODE
dryRun: KUMA_TRANSPARENT_PROXY_DRY_RUN
verbose: KUMA_TRANSPARENT_PROXY_VERBOSE

CLI flags

This structure outlines the settings and their associated CLI flags for modification:

kumaDPUser: --kuma-dp-user
ipFamilyMode: --ip-family-mode
redirect:
  dns:
    enabled: --redirect-dns
    port: --redirect-dns-port
    captureAll: --redirect-all-dns-traffic
    skipConntrackZoneSplit: --skip-dns-conntrack-zone-split
    resolvConfigPath: # can't be modified via CLI flag
  inbound:
    enabled: --redirect-inbound
    port: --redirect-inbound-port
    includePorts: # can't be modified via CLI flag
    excludePorts: --exclude-inbound-ports
    excludePortsForIPs: --exclude-inbound-ips
    excludePortsForUIDs: # can't be modified via CLI flag
    insertRedirectInsteadOfAppend: --redirect-inbound-insert-instead-of-append
  outbound:
    enabled: # can't be modified via CLI flag
    port: --redirect-outbound-port
    includePorts: # can't be modified via CLI flag
    excludePorts: --exclude-outbound-ports
    excludePortsForIPs: --exclude-outbound-ips
    excludePortsForUIDs: --exclude-outbound-ports-for-uids
    insertRedirectInsteadOfAppend: --redirect-outbound-insert-instead-of-append
  vnet:
    networks: --vnet
ebpf:
  enabled: --ebpf-enabled
  instanceIP: --ebpf-instance-ip
  instanceIPEnvVarName: # can't be modified via CLI flag
  bpffsPath: --ebpf-bpffs-path
  cgroupPath: --ebpf-cgroup-path
  programsSourcePath: --ebpf-programs-source-path
  tcAttachIface: --ebpf-tc-attach-iface
retry:
  maxRetries: --max-retries
  sleepBetweenRetries: --sleep-between-retries
iptablesExecutables: --iptables-executables
log:
  enabled: --iptables-logs
  level: # can't be modified via CLI flag
comments:
  disabled: --disable-comments
wait: --wait
waitInterval: --wait-interval
dropInvalidPackets: --drop-invalid-packets
storeFirewalld: --store-firewalld
cniMode: # can't be modified via CLI flag
dryRun: --dry-run
verbose: --verbose

Default values

Here is a configuration that only shows the settings with their default values:

ipFamilyMode: "dualstack"
redirect:
  inbound:
    enabled: true
    port: 15006
  outbound:
    enabled: true
    port: 15001
  dns:
    port: 15053
    resolvConfigPath: "/etc/resolv.conf"
ebpf:
  bpffsPath: "/run/kuma/bpf"
  cgroupPath: "/sys/fs/cgroup"
  programsSourcePath: "/tmp/kuma-ebpf"
retry:
  maxRetries: 4
  sleepBetweenRetries: "2s"
log:
  level: 7
wait: 5

Full reference

  • kumaDPUser

    The username or UID of the user that will run kuma-dp

    If this value is not provided, the system will default to using the UID 5678 or the username kuma-dp

    Type string
    CLI Flag --kuma-dp-user
    Environment Variable KUMA_TRANSPARENT_PROXY_KUMA_DP_USER
    Control Plane Runtime Configuration
    Field runtime.kubernetes.injector.sidecarContainer.uid
    Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_UID

    Examples

    kumactl install transparent-proxy --kuma-dp-user bob

    KUMA_TRANSPARENT_PROXY_KUMA_DP_USER="5679" kumactl install transparent-proxy

  • ipFamilyMode

    The IP family mode used for configuring traffic redirection in the transparent proxy

    Type enum
    Default Value dualstack
    Values dualstack, ipv4
    CLI Flag --ip-family-mode
    Environment Variable KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE
    Kubernetes Annotation kuma.io/transparent-proxying-ip-family-mode
    Control Plane Runtime Configuration
    Field runtime.kubernetes.injector.sidecarContainer.ipFamilyMode
    Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_IP_FAMILY_MODE

  • redirect

    • inbound

      • enabled

        Enables inbound traffic redirection

        Type bool
        Default Value true
        CLI Flag --redirect-inbound
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_ENABLED

      • port

        Port used for redirecting inbound traffic

        Type Port
        Default Value 15006
        CLI Flag --redirect-inbound-port
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_PORT
        Control Plane Runtime Configuration
        Field runtime.kubernetes.injector.sidecarContainer.redirectPortInbound
        Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_INBOUND

      • includePorts

        List of ports to include in inbound traffic redirection

        This option cannot be used together with redirect.inbound.excludePorts. If both are specified, redirect.inbound.includePorts will take precedence

        Type []Port
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_INCLUDE_PORTS

      • excludePorts

        List of ports to exclude from inbound traffic redirection

        This option cannot be used together with redirect.inbound.includePorts. If both are specified, redirect.inbound.includePorts will take precedence.

        Type []Port
        CLI Flag --exclude-inbound-ports
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS
        Kubernetes Annotation traffic.kuma.io/exclude-inbound-ports
        Control Plane Runtime Configuration
        Field runtime.kubernetes.injector.sidecarTraffic.excludeInboundPorts
        Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS

      • excludePortsForIPs

        List of IP addresses to exclude from inbound traffic redirection for specific ports

        Type []string
        Format ip[,...]
        CLI Flag --exclude-inbound-ips
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS
        Kubernetes Annotation traffic.kuma.io/exclude-inbound-ips
        Control Plane Runtime Configuration
        Field runtime.kubernetes.injector.sidecarTraffic.excludeInboundIPs
        Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS

        This CLI flag can be repeated. For example:

        kumactl install transparent-proxy \
  --exclude-outbound-ips "10.0.0.1,172.1.0.0/24" \
  --exclude-outbound-ips "fe80::/10"

      • excludePortsForUIDs

        List of UIDs to exclude from inbound traffic redirection for specific ports

        Type []string
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_UIDS

      • insertRedirectInsteadOfAppend

        Inserts the redirection rule at the beginning of the chain instead of appending it

        Details: For inbound traffic, by default, the last applied iptables rule in the PREROUTING chain of the nat table redirects traffic to our custom chain (KUMA_MESH_INBOUND_REDIRECT) for handling transparent proxying. If there is an existing rule in this chain that redirects traffic to another chain, our default behavior of appending the rule would cause it to be added after the existing one, making our rule ineffective. Specifying this flag changes the behavior to insert the rule at the beginning of the chain, ensuring our rule takes precedence

        Note that if the redirect.vnet setting is also specified, the default behavior is already to insert the rule, so using this setting will not change that behavior

        Type bool
        Default Value false
        CLI Flag --redirect-inbound-insert-instead-of-append
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND

    • outbound

      • enabled

        Enables outbound traffic redirection

        Type bool
        Default Value true
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_ENABLED

      • port

        Port used for redirecting outbound traffic

        Type Port
        Default Value 15001
        CLI Flag --redirect-outbound-port
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_PORT
        Control Plane Runtime Configuration
        Field runtime.kubernetes.injector.sidecarContainer.redirectPortOutbound
        Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_OUTBOUND

      • includePorts

        List of ports to include in outbound traffic redirection

        This option cannot be used together with redirect.outbound.excludePorts. If both are specified, redirect.outbound.includePorts will take precedence.

        Type []Port
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_INCLUDE_PORTS

      • excludePorts

        List of ports to exclude from outbound traffic redirection

        This option cannot be used together with redirect.outbound.includePorts. If both are specified, redirect.outbound.includePorts will take precedence.

        Type []Port
        CLI Flag --exclude-outbound-ports
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS
        Kubernetes Annotation traffic.kuma.io/exclude-outbound-ports
        Control Plane Runtime Configuration
        Field runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts
        Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS

      • excludePortsForIPs

        List of IP addresses to exclude from outbound traffic redirection for specific ports.

        Type []string
        Format ip[,...]
        CLI Flag --exclude-outbound-ips
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS
        Kubernetes Annotation traffic.kuma.io/exclude-outbound-ips
        Control Plane Runtime Configuration
        Field runtime.kubernetes.injector.sidecarTraffic.excludeOutboundIPs
        Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS

      • excludePortsForUIDs

        List of UIDs to exclude from outbound traffic redirection for specific ports

        Type []string
        Format [[protocol:][ports:]uids][;...]
        CLI Flag --exclude-outbound-ports-for-uids
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_UIDS
        Kubernetes Annotation traffic.kuma.io/exclude-outbound-ports-for-uids

        Examples

        • Exclude outbound TCP and UDP traffic to all ports for processes owned by user with UID 1000:

          kumactl install transparent-proxy \
  --exclude-outbound-ports-for-uids "1000"

        • Exclude outbound UDP traffic to all ports for processes owned by user with UID 1000:

          kumactl install transparent-proxy \
  --exclude-outbound-ports-for-uids "udp:*:1000"

        • Exclude outbound TCP traffic to port 22 and ports 80–88 for processes owned by users with UIDs in the range 1000–1002:

          kumactl install transparent-proxy \
  --exclude-outbound-ports-for-uids "tcp:22,80-88:1000-1002"

        • Exclude outbound TCP and UDP traffic to all ports for processes owned by users with UIDs in the range 1000–1100, and exclude outbound UDP traffic to all ports for processes owned by user with UID 2000:

          kumactl install transparent-proxy \
  --exclude-outbound-ports-for-uids "1000-1100;udp:*:2000"

          kumactl install transparent-proxy \
  --exclude-outbound-ports-for-uids "1000-1100" \
  --exclude-outbound-ports-for-uids "udp:*:2000"

      • insertRedirectInsteadOfAppend

        Inserts the redirection rule at the beginning of the chain instead of appending it

        Details: For outbound traffic, by default, the last applied iptables rule in the OUTPUT chain of the nat table redirects traffic to our custom chain (KUMA_MESH_OUTBOUND_REDIRECT), where it is processed for transparent proxying. However, if there is an existing rule in this chain that already redirects traffic to another chain, our default behavior of appending the rule will cause our rule to be added after the existing one, effectively ignoring it. When this flag is specified, it changes the behavior from appending to inserting the rule at the beginning of the chain, ensuring that our iptables rule takes precedence

        Type bool
        Default Value false
        CLI Flag --redirect-outbound-insert-instead-of-append
        Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND

  • dns

    • enabled

      Enables redirection of DNS queries to the DNS server managed by Kuma, listening on the port specified in the redirect.dns.port setting

      When redirect.dns.captureAll is disabled, only queries directed to servers listed in the file specified via redirect.dns.resolvConfigPath) will be redirected. If redirect.dns.captureAll is enabled, all DNS queries will be redirected, regardless of the target DNS server

      Type bool
      Default Value true
      Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_ENABLED
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.builtinDNS.enabled
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_ENABLED

    • port

      The port where the DNS server managed by Kuma is listening

      Type Port
      Default Value 15053
      CLI Flag --redirect-dns-port
      Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.builtinDNS.port
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_PORT

    • captureAll

      Redirect all DNS traffic to the DNS server managed by Kuma, listening on the port specified in the redirect.dns.port setting

      This setting requires redirect.dns.enabled, which is disabled by default. However, using the --redirect-all-dns-traffic flag automatically enables it. Note that combining --redirect-all-dns-traffic with --redirect-dns is incorrect and will result in an error. In all other cases, ensure redirect.dns.enabled is explicitly enabled via the appropriate environment variable or in the JSON / YAML configuration.

      Type bool
      Default Value false
      CLI Flag --redirect-all-dns-traffic
      Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_CAPTURE_ALL

    • skipConntrackZoneSplit

      Disables conntrack zone splitting, which can prevent potential DNS issues

      Details: The conntrack zone splitting feature is used to avoid DNS resolution errors when applications make numerous DNS UDP requests. Normally, we separate conntrack zones to ensure proper handling of DNS traffic: Zone 2 handles DNS packets between the application and the local proxy, while Zone 1 manages packets between the proxy and upstream DNS resolvers. Disabling this feature should only be done if necessary, for example, in environments where custom iptables rules are already manipulating DNS traffic (for example, inside Docker containers in custom networks when redirecting all DNS traffic [redirect.dns.captureAll is enabled])

      Type bool
      Default Value false
      CLI Flag --skip-dns-conntrack-zone-split
      Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_SKIP_CONNTRACK_ZONE_SPLIT

    • resolvConfigPath

      Specifies the path to the resolv.conf file used to parse the DNS servers for redirecting DNS queries

      This setting is taken into account only when redirect.dns.captureAll is not enabled.

      Type string
      Default Value /etc/resolv.conf
      Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_RESOLV_CONFIG_PATH

  • vnet

    • networks

      Specifies virtual networks using the format interfaceName:CIDR Allows matching traffic on specific network interfaces

      Examples:

      • docker0:172.17.0.0/16
      • br+:172.18.0.0/16 (matches any interface with name starting with br)
      • iface:::1/64 (for IPv6)
      Type []string
      CLI Flag --vnet
      Environment Variable KUMA_TRANSPARENT_PROXY_REDIRECT_VNET_NETWORKS

  • ebpf

    eBPF implementation is experimental. Use with caution

    • enabled

      Enables eBPF support for handling traffic redirection in the transparent proxy

      Type bool
      Default Value false
      CLI Flag --ebpf-enabled
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_ENABLED
      Kubernetes Annotation kuma.io/transparent-proxying-ebpf
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.ebpf.enabled
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_ENABLED

    • instanceIP

      IP address of the instance (pod/vm) where transparent proxy will be installed

      Mutually exclusive with ebpf.instanceIPEnvVarName.

      Type string
      CLI Flag --ebpf-instance-ip
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_INSTANCE_IP

    • instanceIPEnvVarName

      The name of the environment variable containing the IP address of the instance (pod/vm) where transparent proxy will be installed

      Mutually exclusive with ebpf.instanceIP.

      Type string
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_INSTANCE_IP_ENV_VAR_NAME
      Kubernetes Annotation kuma.io/transparent-proxying-ebpf-instance-ip-env-var-name
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.ebpf.instanceIPEnvVarName
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_INSTANCE_IP_ENV_VAR_NAME

    • bpffsPath

      The path of the BPF filesystem

      Type string
      Default Value /run/kuma/bpf
      CLI Flag --ebpf-bpffs-path
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_BPFFS_PATH
      Kubernetes Annotation kuma.io/transparent-proxying-ebpf-bpf-fs-path
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.ebpf.bpffsPath
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_BPFFS_PATH

    • cgroupPath

      The path of cgroup2

      Type string
      Default Value /sys/fs/cgroup
      CLI Flag --ebpf-cgroup-path
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_CGROUP_PATH
      Kubernetes Annotation kuma.io/transparent-proxying-ebpf-cgroup-path
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.ebpf.cgroupPath
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_CGROUP_PATH

    • programsSourcePath

      Path where compiled eBPF programs and other necessary files for eBPF mode can be found

      Type string
      Default Value /tmp/kuma-ebpf
      CLI Flag --ebpf-programs-source-path
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_PROGRAMS_SOURCE_PATH
      Kubernetes Annotation kuma.io/transparent-proxying-ebpf-programs-source-path
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.ebpf.programSourcePath
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_PROGRAMS_SOURCE_PATH

    • tcAttachIface

      The network interface for TC eBPF programs to bind to. If not provided, it will be automatically determined

      Type string
      CLI Flag --ebpf-tc-attach-iface
      Environment Variable KUMA_TRANSPARENT_PROXY_EBPF_TC_ATTACH_IFACE
      Kubernetes Annotation kuma.io/transparent-proxying-ebpf-tc-attach-iface
      Control Plane Runtime Configuration
      Field runtime.kubernetes.injector.ebpf.tcAttachIface
      Environment Variable KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_TC_ATTACH_IFACE

  • retry

    • maxRetries

      The maximum number of retry attempts for operations

      Type uint
      Default Value 4
      CLI Flag --max-retries
      Environment Variable KUMA_TRANSPARENT_PROXY_RETRY_MAX_RETRIES

    • sleepBetweenRetries

      The time duration to wait between retry attempts

      Type Duration
      Default Value 2s
      CLI Flag --sleep-between-retries
      Environment Variable KUMA_TRANSPARENT_PROXY_RETRY_SLEEP_BETWEEN_RETRIES

  • iptablesExecutables

    Specifies custom paths for iptables executables

    You must provide all three executables for each IP version you want to customize (IPv4 or IPv6), meaning if you configure one for IPv6 (for example, ip6tables), you must also specify ip6tables-save and ip6tables-restore. Partial configurations for either IPv4 or IPv6 are not allowed.

    Provided paths are not extensively validated, so ensure you specify correct paths and that the executables are actual iptables binaries to avoid misconfigurations and unexpected behavior.

    Configuration values can be set through a combination of sources: config file (via --config or --config-file), environment variables, and the --iptables-executables flag. For example, you can specify ip6tables in the config file, ip6tables-save as an environment variable, and ip6tables-restore via the --iptables-executables flag.

    Type object
    CLI Flag --iptables-executables
    Environment Variable KUMA_TRANSPARENT_PROXY_IPTABLES_EXECUTABLES

  • log

    • enabled

      Determines whether iptables rules logging is activated. When true, each packet matching an iptables rule will have its details logged, aiding in diagnostics and monitoring of packet flows

      Type bool
      Default Value false
      CLI Flag --iptables-logs
      Environment Variable KUMA_TRANSPARENT_PROXY_LOG_ENABLED
      Kubernetes Annotation traffic.kuma.io/iptables-logs

    • level

      Specifies the log level for iptables logging as defined by netfilter. This level controls the verbosity and detail of the log entries for matching packets. Higher values increase the verbosity. The exact behavior can depend on the system’s syslog configuration

      Available log levels:

      • 0 - emergency (system is unusable)
      • 1 - alert (action must be taken immediately)
      • 2 - critical (critical conditions)
      • 3 - error (error conditions)
      • 4 - warning (warning conditions)
      • 5 - notice (normal but significant condition)
      • 6 - info (informational)
      • 7 - debug (debug-level messages)
      Type enum
      Default Value 7
      Values 0, 1, 2, 3, 4, 5, 6, 7
      Environment Variable KUMA_TRANSPARENT_PROXY_LOG_LEVEL

  • comments

    • disabled

      Disables the addition of comments to iptables rules

      Disabling comments is strongly discouraged, as they are essential for properly uninstalling the transparent proxy. If comments are disabled, the kumactl uninstall transparent-proxy command will not function, and you’ll need to manually remove the related iptables rules when necessary.

      Type bool
      Default Value false
      CLI Flag --disable-comments
      Environment Variable KUMA_TRANSPARENT_PROXY_COMMENTS_DISABLED

  • wait

    Time in seconds to wait for acquiring the xtables lock before failing. Value 0 means wait indefinitely

    Type uint
    Default Value 5
    CLI Flag --wait
    Environment Variable KUMA_TRANSPARENT_PROXY_WAIT

  • waitInterval

    Time interval between retries to acquire the xtables lock in seconds

    Type uint
    Default Value 0
    CLI Flag --wait-interval
    Environment Variable KUMA_TRANSPARENT_PROXY_WAIT_INTERVAL

  • dropInvalidPackets

    Drops invalid packets to avoid connection resets in high-throughput scenarios

    Details: This setting enables dropping of packets in invalid states, improving application stability by preventing them from reaching the backend. This is particularly beneficial during high-throughput requests where out-of-order packets might bypass DNAT

    Note that enabling this flag may introduce slight performance overhead. Weigh the trade-off between connection stability and performance before enabling it.

    Type bool
    Default Value false
    CLI Flag --drop-invalid-packets
    Environment Variable KUMA_TRANSPARENT_PROXY_DROP_INVALID_PACKETS
    Kubernetes Annotation traffic.kuma.io/drop-invalid-packets

  • storeFirewalld

    Enables firewalld support to store iptables rules

    Type bool
    Default Value false
    CLI Flag --store-firewalld
    Environment Variable KUMA_TRANSPARENT_PROXY_STORE_FIREWALLD

  • cniMode

    Type bool
    Default Value false
    Environment Variable KUMA_TRANSPARENT_PROXY_CNI_MODE

  • dryRun

    Enables dry-run mode

    Type bool
    Default Value false
    CLI Flag --dry-run
    Environment Variable KUMA_TRANSPARENT_PROXY_DRY_RUN

  • verbose

    Enables verbose mode with longer argument/flag names and additional comments

    Type bool
    Default Value false
    CLI Flag --verbose
    Environment Variable KUMA_TRANSPARENT_PROXY_VERBOSE