Customizing Transparent Proxy Configuration in Universal Mode

The default transparent proxy configuration works well for most scenarios, but there are cases where adjustments are needed. This guide explains the various methods available for modifying the configuration, along with their limitations and recommendations on when to use each one.

Configuration reference

Kuma uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the Full Reference section in the Transparent Proxy Configuration Reference.

If you’re only interested in specific parts of the reference, here are links to simplified sections:

Section	Description
Schema	A concise version of the configuration schema, including default values.
Environment Variables	A configuration structure showing fields and their corresponding environment variables.
CLI Flags	A configuration structure showing fields and their corresponding CLI flags.
Default Values	A structure displaying only the fields with their default values.

Methods of customizing the configuration

In Universal environments, Kuma provides three ways to adjust the transparent proxy configuration. Each method can be used on its own or combined with others if needed.

It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the Order of Precedence to see what the final configuration will look like based on the priority of each setting.

Here are the methods, listed by precedence, from lowest to highest.

Method 1: YAML or JSON configuration

You can provide the configuration in either YAML or JSON format by using the --config or --config-file flags.

For the configuration schema in YAML format, refer to the Schema section in the Transparent Proxy Configuration Reference.

For simplicity, the following examples use YAML format, but you can easily convert them to JSON if preferred. Both formats work exactly the same, so feel free to choose the one that best suits your needs.

Below are examples of using these flags in different ways:

Providing configuration via the --config-file flag

Assume you have a config.yaml file with the following content:
```
kumaDPUser: dataplane
verbose: true
```
You can install the transparent proxy using:
```
kumactl install transparent-proxy --config-file config.yaml
```

Passing configuration directly via the --config flag

To pass the configuration content directly:

kumactl install transparent-proxy --config "kumaDPUser: dataplane\nverbose: true"

Alternatively:

kumactl install transparent-proxy --config "{ kumaDPUser: dataplane, verbose: true }"

Both formats are valid YAML inputs.

Passing configuration via STDIN

If you need to pass the configuration via STDIN, set --config-file to - as shown below:
```
echo "
kumaDPUser: dataplane
verbose: true
" | kumactl install transparent-proxy --config-file -
```

Method 2: Using environment variables

You can customize configuration settings by using environment variables. For example:

KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy

To see all available environment variables, visit the Environment Variables section in the Transparent Proxy Configuration Reference.

Method 3: CLI flags

Most configuration values can also be specified directly through CLI flags. For example:

kumactl install transparent-proxy --kuma-dp-user dataplane --verbose

The following settings cannot be modified directly via CLI flags (corresponding flags are not available):

redirect.dns.resolvConfigPath
redirect.inbound.includePorts
redirect.inbound.excludePortsForUIDs
redirect.outbound.enabled
redirect.outbound.includePorts
ebpf.instanceIPEnvVarName
log.level
cniMode

To see all available CLI flags, visit the CLI Flags section in the Transparent Proxy Configuration Reference.

Order of precedence

Default Values
Values from --config / --config-file flags
Environment Variables
CLI Flags

To understand how the order of precedence works, consider this scenario:

You have a config.yaml file with the following content:
```
redirect:
  dns:
    port: 10001
```

You install the transparent proxy using this command:

KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT="10002" \
  kumactl install transparent-proxy \
    --config-file config.yaml \
    --redirect-dns-port 10003

In this situation, the possible values for redirect.dns.port are:
- 15053 (Default Value)
- 10001 (From Config File)
- 10002 (From Environment Variable)
- 10003 (From CLI Flag)
Since CLI flags have the highest precedence, the final value for redirect.dns.port will be 10003.