Configuring Gateway Network Topology (Development)
- Configuring network topologies (Development)
  - Configuring X-Forwarded-For Headers
    - Example using X-Forwarded-For capability with httpbin
  - Configuring X-Forwarded-Client-Cert Headers
- See also

Configuring Gateway Network Topology (Development)

Configuring network topologies (Development)

This feature is actively in development and is considered pre-alpha.

Istio provides the ability to manage settings like X-Forwarded-For (XFF) and X-Forwarded-Client-Cert (XFCC), which are dependent on how the gateway workloads are deployed. This is currently an in-development feature. For more information on X-Forwarded-For, see the IETF’s RFC.

You might choose to deploy Istio ingress gateways in various network topologies (e.g. behind Cloud Load Balancers, a self-managed Load Balancer or directly expose the Istio ingress gateway to the Internet). As such, these topologies require different ingress gateway configurations for transporting correct client attributes like IP addresses and certificates to the workloads running in the cluster.

Configuration of XFF and XFCC headers is managed via MeshConfig during Istio installation or by adding a pod annotation. Note that the Meshconfig configuration is a global setting for all gateway workloads, while pod annotations override the global setting on a per-workload basis.

To simplify configuring network topology during installation, create a single YAML file to pass to istioctl:

$ cat <<EOF > topology.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      gatewayTopology:
EOF

If Istio ingress gateway was already running prior to application of the MeshConfig, restart any Istio ingress gateway pods.

You can configure both of these settings using the proxy.istio.io/config annotation to the Pod spec of your Istio ingress gateway.

...
  metadata:
    annotations:
      "proxy.istio.io/config": '{"gatewayTopology" : { "numTrustedProxies": 2 } }'

Configuring X-Forwarded-For Headers

Applications rely on reverse proxies to forward client attributes in a request, such as X-Forward-For header. However, due to the variety of network topologies Istio can be deployed in, you must set the number of trusted proxies deployed in front of the Istio gateway proxy, so that the client address can be extracted correctly.

To set the number of trusted proxies, add the following to your topology.yaml file.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      gatewayTopology:
        numTrustedProxies: <VALUE>

For example, if you have a cloud based Load Balancer, a reverse proxy, and an Istio gateway proxy, then <VALUE> would be 2.

Note that all proxies in front of the Istio gateway proxy must parse HTTP traffic and append to the X-Forwarded-For header at each hop. If the number of entries in the X-Forwarded-For header is less than the number of trusted hops configured, Envoy falls back to using the immediate downstream address as the trusted client address. Please refer to the Envoy documentation to understand how X-Forwarded-For headers and trusted client addresses are determined.

Example using X-Forwarded-For capability with httpbin

Specify numTrustedProxies as 2 either using MeshConfig or an proxy.istop/io/config annotation. If you are using MeshConfig, run the following command to create a file named topology.yaml and apply it to your cluster:
```
$ cat <<EOF > topology.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      gatewayTopology:
        numTrustedProxies: 2
EOF
$ istioctl install -f topology.yaml
```
If you previously installed an Istio ingress gateway, restart all ingress gateway pods after step 1.

Create an httpbin namespace:

$ kubectl create namespace httpbin
namespace/httpbin created

Set the istio-injection label to enabled for sidecar injection:

$ kubectl label --overwrite namespace httpbin istio-injection=enabled
namespace/httpbin labeled

Deploy httpbin in the httpbin namespace:

$ kubectl apply -n httpbin -f samples/httpbin/httpbin.yaml

Deploy a gateway associated with httpbin:

$ kubectl apply -n httpbin -f samples/httpbin/httpbin-gateway.yaml

Set a local GATEWAY_URL environmental variable based on your Istio ingress gateway’s IP address:

$ export GATEWAY_URL=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

Run the following curl command to verify the X-Envoy-External-Address and X-Forwarded-For are set correctly:

$ curl -H 'X-Forwarded-For: 56.5.6.7, 72.9.5.6, 98.1.2.3' $GATEWAY_URL/get?show_env=true
{
  "args": {
    "show_env": "true"
  },
  "headers": {
    ...
    "X-Envoy-External-Address": "72.9.5.6",
    ...
    "X-Forwarded-For": "56.5.6.7, 72.9.5.6, 98.1.2.3, <YOUR GATEWAY IP>",
    ...
  },
  ...
}

Note that the X-Envoy-External-Address is set to the “second” from last address in the X-Forwarded-For header as per your numTrustedProxies setting. Additionally, the gateway workload appends its IP in the X-Forwarded-For header before forwarding it to the upstream httpbin workload.

Configuring X-Forwarded-Client-Cert Headers

From Envoy’s documentation regarding XFCC:

x-forwarded-client-cert (XFCC) is a proxy header which indicates certificate information of part or all of the clients or proxies that a request has flowed through, on its way from the client to the server. A proxy may choose to sanitize/append/forward the XFCC header before proxying the request.

To configure how XFCC Headers are handled, add the following to your topology.yaml file.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      gatewayTopology:
        forwardClientCertDetails: <ENUM_VALUE>

where ENUM_VALUE can be of the following type.

`ENUM_VALUE`
`UNDEFINED`	Field is not set.
`SANITIZE`	Do not send the XFCC header to the next hop. This is the default value for a gateway.
`FORWARD_ONLY`	When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
`APPEND_FORWARD`	When the client connection is mTLS, append the client certificate information to the request’s XFCC header and forward it.
`SANITIZE_SET`	When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
`ALWAYS_FORWARD_ONLY`	Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.

See the Envoy documentation for examples of using this capability.

Configuring Gateway Network Topology (Development)

Configuring Gateway Network Topology (Development)

Configuring network topologies (Development)

Configuring X-Forwarded-For Headers

Example using X-Forwarded-For capability with httpbin

Configuring X-Forwarded-Client-Cert Headers

See also