docs: update to use PROXY config (#13568)

* docs: update to use PROXY config Signed-off-by: Kuat Yessenov <kuat@google.com> * gen Signed-off-by: Kuat Yessenov <kuat@google.com> * review Signed-off-by: Kuat Yessenov <kuat@google.com> --------- Signed-off-by: Kuat Yessenov <kuat@google.com>
2023-11-13 18:08:28 -08:00 · 2023-11-13 18:08:28 -08:00 · 0de72af162
parent b4560f89e9
commit 0de72af162
5 changed files with 73 additions and 144 deletions
--- a/content/en/docs/ops/common-problems/upgrade-issues/index.md
+++ b/content/en/docs/ops/common-problems/upgrade-issues/index.md
@ -72,7 +72,9 @@ for deployment of Wasm code.
 ### Use gateway topology to set the number of the trusted hops

 The usage of `EnvoyFilter` to configure the number of the trusted hops in the
-HTTP connection manager has been replaced by the `gatewayTopology` field in
+HTTP connection manager has been replaced by the
+[`gatewayTopology`](/docs/reference/config/istio.mesh.v1alpha1/#Topology)
+field in
 [`ProxyConfig`](/docs/ops/configuration/traffic-management/network-topologies).
 For example, the following `EnvoyFilter` configuration should use an annotation
 on the pod or the mesh default. Instead of:
@ -102,7 +104,7 @@ spec:
      istio: ingress-gateway
 {{< /text >}}

-Use the equivalent ingress gateway proxy configuration annotation:
+Use the equivalent ingress gateway pod proxy configuration annotation:

 {{< text yaml >}}
 metadata:
@ -110,6 +112,44 @@ metadata:
    "proxy.istio.io/config": '{"gatewayTopology" : { "numTrustedProxies": 1 }}'
 {{< /text >}}

+### Use gateway topology to enable PROXY protocol on the ingress gateways
+
+The usage of `EnvoyFilter` to enable [PROXY
+protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) on the
+ingress gateways has been replaced by the
+[`gatewayTopology`](/docs/reference/config/istio.mesh.v1alpha1/#Topology)
+field in
+[`ProxyConfig`](/docs/ops/configuration/traffic-management/network-topologies).
+For example, the following `EnvoyFilter` configuration should use an annotation
+on the pod or the mesh default. Instead of:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: EnvoyFilter
+metadata:
+  name: proxy-protocol
+spec:
+  configPatches:
+  - applyTo: LISTENER_FILTER
+    patch:
+      operation: INSERT_FIRST
+      value:
+        name: proxy_protocol
+        typed_config:
+          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
+  workloadSelector:
+    labels:
+      istio: ingress-gateway
+{{< /text >}}
+
+Use the equivalent ingress gateway pod proxy configuration annotation:
+
+{{< text yaml >}}
+metadata:
+  annotations:
+    "proxy.istio.io/config": '{"gatewayTopology" : { "proxyProtocol": {} }}'
+{{< /text >}}
+
 ### Use a proxy annotation to customize the histogram bucket sizes

 The usage of `EnvoyFilter` and the experimental bootstrap discovery service to
--- a/content/en/docs/ops/configuration/traffic-management/network-topologies/index.md
+++ b/content/en/docs/ops/configuration/traffic-management/network-topologies/index.md
@ -246,60 +246,27 @@ PROXY protocol is only supported for TCP traffic forwarding by Envoy. See the [E
 PROXY protocol should not be used for L7 traffic, or for Istio gateways behind L7 load balancers.
 {{< /warning >}}

-If your external TCP load balancer is configured to forward TCP traffic and use the PROXY protocol, the Istio Gateway TCP listener must also be configured to accept the PROXY protocol. Enabling this requires adding the [Envoy Proxy Protocol filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/listener_filters/proxy_protocol) using an `EnvoyFilter` applied on the gateway workload. For example:
-
-{{< tabset category-name="config-api" >}}
-
-{{< tab name="Istio APIs" category-value="istio-apis" >}}
+If your external TCP load balancer is configured to forward TCP traffic and use the PROXY protocol, the Istio Gateway TCP listener must also be configured to accept the PROXY protocol.
+To enable PROXY protocol on all TCP listeners on the gateways, set `proxyProtocol` in your `IstioOperator`. For example:

 {{< text syntax=yaml snip_id=none >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
-  name: proxy-protocol
-  namespace: istio-system
+apiVersion: install.istio.io/v1alpha1
+kind: IstioOperator
 spec:
-  configPatches:
-  - applyTo: LISTENER_FILTER
-    patch:
-      operation: INSERT_FIRST
-      value:
-        name: proxy_protocol
-        typed_config:
-          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
-  workloadSelector:
-    labels:
-      istio: ingressgateway
+  meshConfig:
+    defaultConfig:
+      gatewayTopology:
+        proxyProtocol: {}
 {{< /text >}}

-{{< /tab >}}
+Alternatively, deploy a gateway with the following pod annotation:

-{{< tab name="Gateway API" category-value="gateway-api" >}}
-
-{{< text syntax=yaml snip_id=none >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
+{{< text yaml >}}
 metadata:
-  name: proxy-protocol
-  namespace: istio-system
-spec:
-  configPatches:
-  - applyTo: LISTENER_FILTER
-    patch:
-      operation: INSERT_FIRST
-      value:
-        name: proxy_protocol
-        typed_config:
-          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
-  workloadSelector:
-    labels:
-      istio.io/gateway-name: <GATEWAY_NAME>
+  annotations:
+    "proxy.istio.io/config": '{"gatewayTopology" : { "proxyProtocol": {} }}'
 {{< /text >}}

-{{< /tab >}}
-
-{{< /tabset >}}
-
 The client IP is retrieved from the PROXY protocol by the gateway and set (or appended) in the `X-Forwarded-For` and `X-Envoy-External-Address` header. Note that the PROXY protocol is mutually exclusive with L7 headers like `X-Forwarded-For` and `X-Envoy-External-Address`. When PROXY protocol is used in conjunction with the `gatewayTopology` configuration, the `numTrustedProxies` and the received `X-Forwarded-For` header takes precedence in determining the trusted client addresses, and PROXY protocol client information will be ignored.

 Note that the above example only configures the Gateway to accept incoming PROXY protocol TCP traffic - See the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_features/ip_transparency#proxy-protocol) for examples of how to configure Envoy itself to communicate with upstream services using PROXY protocol.
--- a/content/en/docs/ops/configuration/traffic-management/network-topologies/snips.sh
+++ b/content/en/docs/ops/configuration/traffic-management/network-topologies/snips.sh
@ -99,3 +99,9 @@ curl -s -H 'X-Forwarded-For: 56.5.6.7, 72.9.5.6, 98.1.2.3' "$GATEWAY_URL/get?sho
  "url": ...
 }
 ENDSNIP
+
+! read -r -d '' snip_proxy_protocol_2 <<\ENDSNIP
+metadata:
+  annotations:
+    "proxy.istio.io/config": '{"gatewayTopology" : { "proxyProtocol": {} }}'
+ENDSNIP
--- a/content/en/docs/tasks/security/authorization/authz-ingress/index.md
+++ b/content/en/docs/tasks/security/authorization/authz-ingress/index.md
@ -179,61 +179,9 @@ spec:

 ### TCP/UDP Proxy Load Balancer {#tcp-proxy}

-If you are using a TCP/UDP Proxy external load balancer (AWS Classic ELB), it can use the [Proxy Protocol](https://www.haproxy.com/blog/haproxy/proxy-protocol/) to embed the original client IP address in the packet data.  Both the external load balancer and the Istio ingress gateway must support the proxy protocol for it to work.  In Istio, you can enable it with an `EnvoyFilter` like below:
+If you are using a TCP/UDP Proxy external load balancer (AWS Classic ELB), it can use the [PROXY Protocol](https://www.haproxy.com/blog/haproxy/proxy-protocol/) to embed the original client IP address in the packet data.  Both the external load balancer and the Istio ingress gateway must support the PROXY protocol for it to work.

-{{< tabset category-name="config-api" >}}
-
-{{< tab name="Istio APIs" category-value="istio-apis" >}}
-
-{{< text yaml >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
-  name: proxy-protocol
-  namespace: istio-system
-spec:
-  configPatches:
-  - applyTo: LISTENER_FILTER
-    patch:
-      operation: INSERT_FIRST
-      value:
-        name: proxy_protocol
-        typed_config:
-          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
-  workloadSelector:
-    labels:
-      istio: ingressgateway
-{{< /text >}}
-
-{{< /tab >}}
-
-{{< tab name="Gateway API" category-value="gateway-api" >}}
-
-{{< text yaml >}}
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
-  name: proxy-protocol
-  namespace: foo
-spec:
-  configPatches:
-  - applyTo: LISTENER_FILTER
-    patch:
-      operation: INSERT_FIRST
-      value:
-        name: proxy_protocol
-        typed_config:
-          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
-  workloadSelector:
-    labels:
-      istio.io/gateway-name: httpbin-gateway
-{{< /text >}}
-
-{{< /tab >}}
-
-{{< /tabset >}}
-
-Here is a sample configuration that shows how to make an ingress gateway on AWS EKS support the Proxy Protocol:
+Here is a sample configuration that shows how to make an ingress gateway on AWS EKS support the PROXY Protocol:

 {{< tabset category-name="config-api" >}}

@ -246,6 +194,9 @@ spec:
  meshConfig:
    accessLogEncoding: JSON
    accessLogFile: /dev/stdout
+    defaultConfig:
+      gatewayTopology:
+        proxyProtocol: {}
  components:
    ingressGateways:
    - enabled: true
@ -270,6 +221,7 @@ metadata:
  name: httpbin-gateway
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"
+    proxy.istio.io/config: '{"gatewayTopology" : { "proxyProtocol": {} }}'
 spec:
  gatewayClassName: istio
  ...
@ -340,11 +292,11 @@ spec:

 ## IP-based allow list and deny list

-**When to use `ipBlocks` vs. `remoteIpBlocks`:** If you are using the X-Forwarded-For HTTP header or the Proxy Protocol to determine the original client IP address, then you should use `remoteIpBlocks` in your `AuthorizationPolicy`. If you are using `externalTrafficPolicy: Local`, then you should use `ipBlocks` in your `AuthorizationPolicy`.
+**When to use `ipBlocks` vs. `remoteIpBlocks`:** If you are using the X-Forwarded-For HTTP header or the PROXY Protocol to determine the original client IP address, then you should use `remoteIpBlocks` in your `AuthorizationPolicy`. If you are using `externalTrafficPolicy: Local`, then you should use `ipBlocks` in your `AuthorizationPolicy`.

 |Load Balancer Type |Source of Client IP   | `ipBlocks` vs. `remoteIpBlocks`
 --------------------|----------------------|---------------------------
-| TCP Proxy         | Proxy Protocol       | `remoteIpBlocks`
+| TCP Proxy         | PROXY Protocol       | `remoteIpBlocks`
 | Network           | packet source address| `ipBlocks`
 | HTTP/HTTPS        | X-Forwarded-For      | `remoteIpBlocks`

--- a/content/en/docs/tasks/security/authorization/authz-ingress/snips.sh
+++ b/content/en/docs/tasks/security/authorization/authz-ingress/snips.sh
@ -88,52 +88,15 @@ spec:
 ENDSNIP

 ! read -r -d '' snip_tcpudp_proxy_load_balancer_1 <<\ENDSNIP
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
-  name: proxy-protocol
-  namespace: istio-system
-spec:
-  configPatches:
-  - applyTo: LISTENER_FILTER
-    patch:
-      operation: INSERT_FIRST
-      value:
-        name: proxy_protocol
-        typed_config:
-          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
-  workloadSelector:
-    labels:
-      istio: ingressgateway
-ENDSNIP
-
-! read -r -d '' snip_tcpudp_proxy_load_balancer_2 <<\ENDSNIP
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
-  name: proxy-protocol
-  namespace: foo
-spec:
-  configPatches:
-  - applyTo: LISTENER_FILTER
-    patch:
-      operation: INSERT_FIRST
-      value:
-        name: proxy_protocol
-        typed_config:
-          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"
-  workloadSelector:
-    labels:
-      istio.io/gateway-name: httpbin-gateway
-ENDSNIP
-
-! read -r -d '' snip_tcpudp_proxy_load_balancer_3 <<\ENDSNIP
 apiVersion: install.istio.io/v1alpha1
 kind: IstioOperator
 spec:
  meshConfig:
    accessLogEncoding: JSON
    accessLogFile: /dev/stdout
+    defaultConfig:
+      gatewayTopology:
+        proxyProtocol: {}
  components:
    ingressGateways:
    - enabled: true
@ -147,13 +110,14 @@ spec:
        ...
 ENDSNIP

-! read -r -d '' snip_tcpudp_proxy_load_balancer_4 <<\ENDSNIP
+! read -r -d '' snip_tcpudp_proxy_load_balancer_2 <<\ENDSNIP
 apiVersion: gateway.networking.k8s.io/v1beta1
 kind: Gateway
 metadata:
  name: httpbin-gateway
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"
+    proxy.istio.io/config: '{"gatewayTopology" : { "proxyProtocol": {} }}'
 spec:
  gatewayClassName: istio
  ...