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.istio.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.

See the Envoy documentation for examples of using this capability.