Configure sidecar listeners for exact balancing without using Envoy filters#

Introduction#

You can increase the throughput of an Envoy sidecar proxy by configuring its listeners for exact balancing so that TCP connections are nearly evenly distributed between worker threads.

Availability#

To use exact balancing without using Envoy filters, you need to be running Aspen Mesh 1.14.5-am1 or later.

When to use exact balancing#

Use exact balancing when there are a small number of connections that rarely cycle (for example, service-mesh gRPC egress). Exact balancing may also be beneficial in other situations, but you should verify that using it provides the throughput you expect. For ideas on how to test throughput and information on how to enable sidecar connection-level metrics, see the articles Sailing Faster with Istio, Part 1 and Sailing Faster with Istio, Part 2.

When to follow these instructions#

Follow the instructions below only if you want to configure sidecar listeners for exact balancing without using Envoy filters and only after you’ve installed Aspen Mesh.

About configuring sidecar listeners for exact balancing#

You can configure all sidecars or individual workloads’ sidecars so their listeners use exact balancing. Configuration affects both manually and automatically injected sidecars.

Configure all sidecars so their listeners use exact balancing#

Important

Before configuring all sidecars so their listeners use exact balancing, configure several individual workloads’ sidecars to determine whether exact balancing provides the throughput you expect.

Learn how to configure an individual workload’s sidecars so its listeners use exact balancing.

If you previously configured sidecar listeners for exact balancing using Envoy filters, delete all Envoy filters used to configure sidecar listeners for exact balancing.
Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

Add the ISTIO_META_INBOUND_LISTENER_EXACT_BALANCE and ISTIO_META_OUTBOUND_LISTENER_EXACT_BALANCE fields to the file and set their values to "false":

meshConfig:
  defaultConfig:
    proxyMetadata:
      ISTIO_META_INBOUND_LISTENER_EXACT_BALANCE: "false"
      ISTIO_META_OUTBOUND_LISTENER_EXACT_BALANCE: "false"

If you want the inbound listener for each sidecar (regardless of whether its pod acts only as a server) to use exact balancing, set the value of ISTIO_META_INBOUND_LISTENER_EXACT_BALANCE to "true".
If you want the outbound listeners for each sidecar (whose pod acts as a client) to use exact balancing, set the value of ISTIO_META_OUTBOUND_LISTENER_EXACT_BALANCE to "true".
Save and close the file.
Upgrade the control plane and gateway components from the current version to the same version.
Restart your sidecars.

If you configured inbound listeners to use exact balancing, verify for any pod with a sidecar that its sidecar’s inbound listener is using exact balancing:

$ istioctl proxy-config listeners --port 15006 -o json <podName>.<namespaceName> | grep -A2 connectionBalance

Expected output

"connectionBalanceConfig": {
    "exactBalance": {}
},

If you configured outbound listeners to use exact balancing:
- For any pod with a sidecar, list all of the listeners:
```
$ istioctl proxy-config listeners <podName>.<namespaceName>
```
- Choose any port number from the list other than 15001 or 15006.
- Verify for the pod that the outbound listener for that port is using exact balancing:
```
$ istioctl proxy-config listeners --port <portNumber> -o json <podName>.<namespaceName> | grep -A2 connectionBalance
```
  Expected output
```
"connectionBalanceConfig": {
    "exactBalance": {}
},
```

Configure an individual workload’s sidecars so its listeners use exact balancing#

For this workload, if you previously configured sidecar listeners for exact balancing using Envoy filters (1.11 version), delete the Envoy filters used to configure sidecar listeners for this workload for exact balancing.
Open the workload’s manifest.

In the pod template, add the ISTIO_META_INBOUND_LISTENER_EXACT_BALANCE and ISTIO_META_OUTBOUND_LISTENER_EXACT_BALANCE fields to the file and set their values to "false" (note the required pipe character):

spec:
  template:
    metadata:
      annotations:
        proxy.istio.io/config: |
          proxyMetadata:
            ISTIO_META_INBOUND_LISTENER_EXACT_BALANCE: "false"
            ISTIO_META_OUTBOUND_LISTENER_EXACT_BALANCE: "false"

If you want the inbound listeners for the sidecars (regardless of whether the workload acts only as a server) to use exact balancing, set the value of ISTIO_META_INBOUND_LISTENER_EXACT_BALANCE to "true".
If you want the outbound listeners for the sidecars (whose workload acts as a client) to use exact balancing, set the value of ISTIO_META_OUTBOUND_LISTENER_EXACT_BALANCE to "true".
Save and close the file.
Apply the changes.

Note

If the workload is already running, Kubernetes will restart its pods.

Example
```
$ kubectl apply -f <deploymentManifestFilename> --namespace <namespaceName>
```

If you configured inbound listeners to use exact balancing, verify for any pod in the workload that its sidecar’s inbound listener is using exact balancing:

$ istioctl proxy-config listeners --port 15006 -o json <podName>.<namespaceName> | grep -A2 connectionBalance

Expected output

"connectionBalanceConfig": {
    "exactBalance": {}
},

If you configured outbound listeners to use exact balancing:
- For any pod in the workload, list all of the listeners:
```
$ istioctl proxy-config listeners <podName>.<namespaceName>
```
- Choose any port number from the list other than 15001 or 15006.
- Verify for the pod that the outbound listener for that port is using exact balancing:
```
$ istioctl proxy-config listeners --port <portNumber> -o json <podName>.<namespaceName> | grep -A2 connectionBalance
```
  Expected output
```
"connectionBalanceConfig": {
    "exactBalance": {}
},
```