Configuring Gateway Network Topology (Development)

Configuring network topologies (Development)

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

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.

Example using X-Forwarded-For capability with httpbin

  1. 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
    
  2. Create an httpbin namespace:

    $ kubectl create namespace httpbin
    namespace/httpbin created
    
  3. Set the istio-injection label to enabled for sidecar injection:

    $ kubectl label --overwrite namespace httpbin istio-injection=enabled
    namespace/httpbin labeled
    
  4. Deploy httpbin in the httpbin namespace:

    $ kubectl apply -n httpbin -f samples/httpbin/httpbin.yaml
    
  5. Deploy a gateway associated with httpbin:

    $ kubectl apply -n httpbin -f samples/httpbin/httpbin-gateway.yaml
    
  6. 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}')
    
  7. 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:

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.

Was this information useful?
Do you have any suggestions for improvement?

Thanks for your feedback!