From b66566d4162a8fbba85248a23f7cad3e3a0d3cb6 Mon Sep 17 00:00:00 2001 From: Jukie <10012479+Jukie@users.noreply.github.com> Date: Fri, 16 May 2025 08:48:06 -0600 Subject: [PATCH 1/6] Add zone aware routing docs Signed-off-by: Jukie <10012479+Jukie@users.noreply.github.com> --- examples/kubernetes/zone-routing.yaml | 131 ++++++++++++++++++ ...kubernetes-traffic-distribution-support.md | 115 +++++++++++++++ ...kubernetes-traffic-distribution-support.md | 115 +++++++++++++++ 3 files changed, 361 insertions(+) create mode 100644 examples/kubernetes/zone-routing.yaml create mode 100644 site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md create mode 100644 site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md diff --git a/examples/kubernetes/zone-routing.yaml b/examples/kubernetes/zone-routing.yaml new file mode 100644 index 0000000000..9f8bb50704 --- /dev/null +++ b/examples/kubernetes/zone-routing.yaml @@ -0,0 +1,131 @@ +apiVersion: v1 +kind: Service +metadata: + annotations: + service.kubernetes.io/topology-mode: Auto + name: zone-routing-backend + labels: + app: zone-routing-backend + service: zone-routing-backend +spec: + ports: + - name: http + port: 3000 + targetPort: 3000 + selector: + app: zone-routing-backend +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: zone-routing-backend-local +spec: + replicas: 1 + selector: + matchLabels: + app: zone-routing-backend + version: v1 + template: + metadata: + labels: + app: zone-routing-backend + version: v1 + spec: + affinity: + podAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchExpressions: + - key: "gateway.envoyproxy.io/owning-gateway-name" + operator: In + values: + - eg + - key: "app.kubernetes.io/component" + operator: In + values: + - proxy + topologyKey: topology.kubernetes.io/zone + namespaceSelector: {} + containers: + - image: gcr.io/k8s-staging-gateway-api/echo-basic:v20231214-v1.0.0-140-gf544a46e + imagePullPolicy: IfNotPresent + name: backend + ports: + - containerPort: 3000 + env: + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: zone-routing-backend-nonlocal +spec: + replicas: 1 + selector: + matchLabels: + app: zone-routing-backend + version: v1 + template: + metadata: + labels: + app: zone-routing-backend + version: v1 + spec: + affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchExpressions: + - key: "gateway.envoyproxy.io/owning-gateway-name" + operator: In + values: + - same-namespace + - key: "app.kubernetes.io/component" + operator: In + values: + - proxy + topologyKey: topology.kubernetes.io/zone + namespaceSelector: {} + containers: + - image: gcr.io/k8s-staging-gateway-api/echo-basic:v20231214-v1.0.0-140-gf544a46e + imagePullPolicy: IfNotPresent + name: backend + ports: + - containerPort: 3000 + env: + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: zone-routing +spec: + parentRefs: + - name: eg + hostnames: + - "www.example.com" + rules: + - backendRefs: + - group: "" + kind: Service + name: zone-routing-backend + port: 3000 + weight: 1 + matches: + - path: + type: PathPrefix + value: /zone-routing \ No newline at end of file diff --git a/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md b/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md new file mode 100644 index 0000000000..47fc9162b0 --- /dev/null +++ b/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md @@ -0,0 +1,115 @@ +--- +title: "Kubernetes Traffic Distribution Support" +--- + +EnvoyGateway supports Kubernetes [Traffic Distribution][Traffic Distribution] and [Topology Aware Routing][Topology Aware Routing] +which is useful for keeping network traffic in the originating zone. Preferring same-zone traffic between Pods in your +cluster can help with reliability, performance (network latency and throughput), or cost. + +{{% alert title="Note" color="primary" %}} +The current implementation for Topology Aware Routing support doesn't respect the minimum of 3 endpoints per zone +requirement and applies the same logic as `spec.TrafficDistribution=PreferClose`. This will be fixed in the next release. +{{% /alert %}} + + +## Prerequisites +* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. +* There must be at least two valid topology zones for scheduling. +* {{< boilerplate prerequisites >}} + +## Configuration + +Apply the example manifests with zonal based routing enabled: +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-routing.yaml -n default +``` + +Ensure that both example Deployments are marked as ready and produces the following output: +```shell +kubectl get deployment/zone-routing-backend-local deployment/zone-routing-backend-nonlocal -n default +NAME READY UP-TO-DATE AVAILABLE AGE +zone-routing-backend-local 1/1 1 1 9m1s +zone-routing-backend-nonlocal 1/1 1 1 9m1s + +``` + +An HTTPRoute resource is created for the `/zone-routing` path prefix along with two example Deployment resources that +are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/zone-routing -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-routing" -XPOST -d '{}' +``` + +We will see the following output. The `pod` header identifies which backend received the request and should have +a name prefix of `zone-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should +not receive requests. + +``` +{ + "path": "/zone-routing", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.1.5" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "zone-routing-backend-local-5586cd668d-md8sf" +} +``` + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the zone-routing example resources BackendTrafficPolicy and HTTPRoute: + +```shell +kubectl delete service/zone-routing-backend +kubectl delete deployment/zone-routing-backend-local +kubectl delete deployment/zone-routing-backend-nonlocal +kubectl delete httproute/zone-routing +``` + +[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution +[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ +[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone \ No newline at end of file diff --git a/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md b/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md new file mode 100644 index 0000000000..47fc9162b0 --- /dev/null +++ b/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md @@ -0,0 +1,115 @@ +--- +title: "Kubernetes Traffic Distribution Support" +--- + +EnvoyGateway supports Kubernetes [Traffic Distribution][Traffic Distribution] and [Topology Aware Routing][Topology Aware Routing] +which is useful for keeping network traffic in the originating zone. Preferring same-zone traffic between Pods in your +cluster can help with reliability, performance (network latency and throughput), or cost. + +{{% alert title="Note" color="primary" %}} +The current implementation for Topology Aware Routing support doesn't respect the minimum of 3 endpoints per zone +requirement and applies the same logic as `spec.TrafficDistribution=PreferClose`. This will be fixed in the next release. +{{% /alert %}} + + +## Prerequisites +* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. +* There must be at least two valid topology zones for scheduling. +* {{< boilerplate prerequisites >}} + +## Configuration + +Apply the example manifests with zonal based routing enabled: +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-routing.yaml -n default +``` + +Ensure that both example Deployments are marked as ready and produces the following output: +```shell +kubectl get deployment/zone-routing-backend-local deployment/zone-routing-backend-nonlocal -n default +NAME READY UP-TO-DATE AVAILABLE AGE +zone-routing-backend-local 1/1 1 1 9m1s +zone-routing-backend-nonlocal 1/1 1 1 9m1s + +``` + +An HTTPRoute resource is created for the `/zone-routing` path prefix along with two example Deployment resources that +are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/zone-routing -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-routing" -XPOST -d '{}' +``` + +We will see the following output. The `pod` header identifies which backend received the request and should have +a name prefix of `zone-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should +not receive requests. + +``` +{ + "path": "/zone-routing", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.1.5" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "zone-routing-backend-local-5586cd668d-md8sf" +} +``` + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the zone-routing example resources BackendTrafficPolicy and HTTPRoute: + +```shell +kubectl delete service/zone-routing-backend +kubectl delete deployment/zone-routing-backend-local +kubectl delete deployment/zone-routing-backend-nonlocal +kubectl delete httproute/zone-routing +``` + +[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution +[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ +[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone \ No newline at end of file From d9ac35d55fdcaf93cac89f86833c414c6db63687 Mon Sep 17 00:00:00 2001 From: Jukie <10012479+Jukie@users.noreply.github.com> Date: Fri, 16 May 2025 08:57:40 -0600 Subject: [PATCH 2/6] lint Signed-off-by: Jukie <10012479+Jukie@users.noreply.github.com> --- examples/kubernetes/zone-routing.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/kubernetes/zone-routing.yaml b/examples/kubernetes/zone-routing.yaml index 9f8bb50704..94ae13bd51 100644 --- a/examples/kubernetes/zone-routing.yaml +++ b/examples/kubernetes/zone-routing.yaml @@ -128,4 +128,4 @@ spec: matches: - path: type: PathPrefix - value: /zone-routing \ No newline at end of file + value: /zone-routing From c247c08d7f17175ca89cba7f9deda836ccd4051e Mon Sep 17 00:00:00 2001 From: Jukie <10012479+Jukie@users.noreply.github.com> Date: Fri, 16 May 2025 10:31:53 -0600 Subject: [PATCH 3/6] typo Signed-off-by: Jukie <10012479+Jukie@users.noreply.github.com> --- .../tasks/traffic/kubernetes-traffic-distribution-support.md | 2 +- .../tasks/traffic/kubernetes-traffic-distribution-support.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md b/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md index 47fc9162b0..c02f809424 100644 --- a/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md +++ b/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md @@ -101,7 +101,7 @@ not receive requests. Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. -Delete the zone-routing example resources BackendTrafficPolicy and HTTPRoute: +Delete the zone-routing example resources and HTTPRoute: ```shell kubectl delete service/zone-routing-backend diff --git a/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md b/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md index 47fc9162b0..c02f809424 100644 --- a/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md +++ b/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md @@ -101,7 +101,7 @@ not receive requests. Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. -Delete the zone-routing example resources BackendTrafficPolicy and HTTPRoute: +Delete the zone-routing example resources and HTTPRoute: ```shell kubectl delete service/zone-routing-backend From f4337d948ca3acb6402e5f219ddce036081a730d Mon Sep 17 00:00:00 2001 From: jukie <10012479+Jukie@users.noreply.github.com> Date: Fri, 30 May 2025 18:59:10 -0600 Subject: [PATCH 4/6] updates Signed-off-by: jukie <10012479+Jukie@users.noreply.github.com> --- ...e-routing.yaml => zone-aware-routing.yaml} | 35 +-- ...kubernetes-traffic-distribution-support.md | 115 --------- .../tasks/traffic/zone-aware-routing.md | 219 ++++++++++++++++++ ...kubernetes-traffic-distribution-support.md | 115 --------- .../v1.4/tasks/traffic/zone-aware-routing.md | 219 ++++++++++++++++++ 5 files changed, 447 insertions(+), 256 deletions(-) rename examples/kubernetes/{zone-routing.yaml => zone-aware-routing.yaml} (81%) delete mode 100644 site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md create mode 100644 site/content/en/latest/tasks/traffic/zone-aware-routing.md delete mode 100644 site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md create mode 100644 site/content/en/v1.4/tasks/traffic/zone-aware-routing.md diff --git a/examples/kubernetes/zone-routing.yaml b/examples/kubernetes/zone-aware-routing.yaml similarity index 81% rename from examples/kubernetes/zone-routing.yaml rename to examples/kubernetes/zone-aware-routing.yaml index 94ae13bd51..e1af430d79 100644 --- a/examples/kubernetes/zone-routing.yaml +++ b/examples/kubernetes/zone-aware-routing.yaml @@ -1,34 +1,17 @@ -apiVersion: v1 -kind: Service -metadata: - annotations: - service.kubernetes.io/topology-mode: Auto - name: zone-routing-backend - labels: - app: zone-routing-backend - service: zone-routing-backend -spec: - ports: - - name: http - port: 3000 - targetPort: 3000 - selector: - app: zone-routing-backend ---- apiVersion: apps/v1 kind: Deployment metadata: - name: zone-routing-backend-local + name: zone-aware-routing-backend-local spec: replicas: 1 selector: matchLabels: - app: zone-routing-backend + app: zone-aware-routing-backend version: v1 template: metadata: labels: - app: zone-routing-backend + app: zone-aware-routing-backend version: v1 spec: affinity: @@ -65,17 +48,17 @@ spec: apiVersion: apps/v1 kind: Deployment metadata: - name: zone-routing-backend-nonlocal + name: zone-aware-routing-backend-nonlocal spec: replicas: 1 selector: matchLabels: - app: zone-routing-backend + app: zone-aware-routing-backend version: v1 template: metadata: labels: - app: zone-routing-backend + app: zone-aware-routing-backend version: v1 spec: affinity: @@ -112,7 +95,7 @@ spec: apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: - name: zone-routing + name: zone-aware-routing spec: parentRefs: - name: eg @@ -122,10 +105,10 @@ spec: - backendRefs: - group: "" kind: Service - name: zone-routing-backend + name: zone-aware-routing-backend port: 3000 weight: 1 matches: - path: type: PathPrefix - value: /zone-routing + value: /zone-aware-routing diff --git a/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md b/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md deleted file mode 100644 index c02f809424..0000000000 --- a/site/content/en/latest/tasks/traffic/kubernetes-traffic-distribution-support.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Kubernetes Traffic Distribution Support" ---- - -EnvoyGateway supports Kubernetes [Traffic Distribution][Traffic Distribution] and [Topology Aware Routing][Topology Aware Routing] -which is useful for keeping network traffic in the originating zone. Preferring same-zone traffic between Pods in your -cluster can help with reliability, performance (network latency and throughput), or cost. - -{{% alert title="Note" color="primary" %}} -The current implementation for Topology Aware Routing support doesn't respect the minimum of 3 endpoints per zone -requirement and applies the same logic as `spec.TrafficDistribution=PreferClose`. This will be fixed in the next release. -{{% /alert %}} - - -## Prerequisites -* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. -* There must be at least two valid topology zones for scheduling. -* {{< boilerplate prerequisites >}} - -## Configuration - -Apply the example manifests with zonal based routing enabled: -```shell -kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-routing.yaml -n default -``` - -Ensure that both example Deployments are marked as ready and produces the following output: -```shell -kubectl get deployment/zone-routing-backend-local deployment/zone-routing-backend-nonlocal -n default -NAME READY UP-TO-DATE AVAILABLE AGE -zone-routing-backend-local 1/1 1 1 9m1s -zone-routing-backend-nonlocal 1/1 1 1 9m1s - -``` - -An HTTPRoute resource is created for the `/zone-routing` path prefix along with two example Deployment resources that -are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. - -Verify the HTTPRoute configuration and status: - -```shell -kubectl get httproute/zone-routing -o yaml -``` - -## Testing - -Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the -Quickstart instructions to set the variable. - -```shell -echo $GATEWAY_HOST -``` - -### HTTPRoute - -We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. - -```shell -curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-routing" -XPOST -d '{}' -``` - -We will see the following output. The `pod` header identifies which backend received the request and should have -a name prefix of `zone-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should -not receive requests. - -``` -{ - "path": "/zone-routing", - "host": "www.example.com", - "method": "GET", - "proto": "HTTP/1.1", - "headers": { - "Accept": [ - "*/*" - ], - "User-Agent": [ - "curl/8.7.1" - ], - "X-Envoy-External-Address": [ - "127.0.0.1" - ], - "X-Forwarded-For": [ - "10.244.1.5" - ], - "X-Forwarded-Proto": [ - "http" - ], - "X-Request-Id": [ - "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" - ] - }, - "namespace": "default", - "ingress": "", - "service": "", - "pod": "zone-routing-backend-local-5586cd668d-md8sf" -} -``` - - -## Clean-Up - -Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. - -Delete the zone-routing example resources and HTTPRoute: - -```shell -kubectl delete service/zone-routing-backend -kubectl delete deployment/zone-routing-backend-local -kubectl delete deployment/zone-routing-backend-nonlocal -kubectl delete httproute/zone-routing -``` - -[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution -[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ -[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone \ No newline at end of file diff --git a/site/content/en/latest/tasks/traffic/zone-aware-routing.md b/site/content/en/latest/tasks/traffic/zone-aware-routing.md new file mode 100644 index 0000000000..21243547e4 --- /dev/null +++ b/site/content/en/latest/tasks/traffic/zone-aware-routing.md @@ -0,0 +1,219 @@ +--- +title: "Zone Aware Routing" +--- + +EnvoyGateway makes use of [Envoy Zone Aware Routing][Envoy Zone Aware Routing] to support Kubernetes [Traffic Distribution][Traffic Distribution] +and [Topology Aware Routing][Topology Aware Routing] which are useful for keeping network traffic in the originating zone. +Preferring same-zone traffic between Pods in your cluster can help with reliability, performance (network latency and throughput), or cost. + +{{% alert title="Note" color="primary" %}} +The current implementation for Topology Aware Routing support doesn't respect the minimum of 3 endpoints per zone +requirement and applies the same logic as `spec.TrafficDistribution=PreferClose`. This will be fixed in the next release. +{{% /alert %}} + + +## Prerequisites +* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. +* There must be at least two valid topology zones for scheduling. +* {{< boilerplate prerequisites >}} + +## Configuration + +### Kubernetes Service +Create the example Kubernetes Service with either topology aware routing or traffic distribution enabled. + +###### Topology Aware Routing +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +###### Traffic Distribution +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +### Example deployments and HTTPRoute +Next apply the example manifests to create two Deployments and an HTTPRoute. For the test configuration one Deployment +(zone-aware-routing-backend-local) includes affinity for EnvoyProxy Pods to ensure its Pods are scheduled in the same +zone and the second Deployment (zone-aware-routing-backend-nonlocal) uses anti-affinity to ensure its Pods _don't_ +schedule to the same zone in order to demonstrate functionality. +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-aware-routing.yaml -n default +``` + +Ensure that both example Deployments are marked as ready and produces the following output: +```shell +kubectl get deployment/zone-aware-routing-backend-local deployment/zone-aware-routing-backend-nonlocal -n default +NAME READY UP-TO-DATE AVAILABLE AGE +zone-aware-routing-backend-local 1/1 1 1 9m1s +zone-aware-routing-backend-nonlocal 1/1 1 1 9m1s + +``` + +An HTTPRoute resource is created for the `/zone-aware-routing` path prefix along with two example Deployment resources that +are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/zone-aware-routing -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-aware-routing" -XPOST -d '{}' +``` + +We will see the following output. The `pod` header identifies which backend received the request and should have +a name prefix of `zone-aware-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should +not receive requests. + +``` +{ + "path": "/zone-aware-routing", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.1.5" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "zone-aware-routing-backend-local-5586cd668d-md8sf" +} +``` + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the zone-aware-routing example resources and HTTPRoute: + +```shell +kubectl delete service/zone-aware-routing-backend +kubectl delete deployment/zone-aware-routing-backend-local +kubectl delete deployment/zone-aware-routing-backend-nonlocal +kubectl delete httproute/zone-aware-routing +``` + +[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution +[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ +[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone +[Envoy Zone Aware Routing]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/zone_aware \ No newline at end of file diff --git a/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md b/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md deleted file mode 100644 index c02f809424..0000000000 --- a/site/content/en/v1.4/tasks/traffic/kubernetes-traffic-distribution-support.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Kubernetes Traffic Distribution Support" ---- - -EnvoyGateway supports Kubernetes [Traffic Distribution][Traffic Distribution] and [Topology Aware Routing][Topology Aware Routing] -which is useful for keeping network traffic in the originating zone. Preferring same-zone traffic between Pods in your -cluster can help with reliability, performance (network latency and throughput), or cost. - -{{% alert title="Note" color="primary" %}} -The current implementation for Topology Aware Routing support doesn't respect the minimum of 3 endpoints per zone -requirement and applies the same logic as `spec.TrafficDistribution=PreferClose`. This will be fixed in the next release. -{{% /alert %}} - - -## Prerequisites -* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. -* There must be at least two valid topology zones for scheduling. -* {{< boilerplate prerequisites >}} - -## Configuration - -Apply the example manifests with zonal based routing enabled: -```shell -kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-routing.yaml -n default -``` - -Ensure that both example Deployments are marked as ready and produces the following output: -```shell -kubectl get deployment/zone-routing-backend-local deployment/zone-routing-backend-nonlocal -n default -NAME READY UP-TO-DATE AVAILABLE AGE -zone-routing-backend-local 1/1 1 1 9m1s -zone-routing-backend-nonlocal 1/1 1 1 9m1s - -``` - -An HTTPRoute resource is created for the `/zone-routing` path prefix along with two example Deployment resources that -are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. - -Verify the HTTPRoute configuration and status: - -```shell -kubectl get httproute/zone-routing -o yaml -``` - -## Testing - -Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the -Quickstart instructions to set the variable. - -```shell -echo $GATEWAY_HOST -``` - -### HTTPRoute - -We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. - -```shell -curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-routing" -XPOST -d '{}' -``` - -We will see the following output. The `pod` header identifies which backend received the request and should have -a name prefix of `zone-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should -not receive requests. - -``` -{ - "path": "/zone-routing", - "host": "www.example.com", - "method": "GET", - "proto": "HTTP/1.1", - "headers": { - "Accept": [ - "*/*" - ], - "User-Agent": [ - "curl/8.7.1" - ], - "X-Envoy-External-Address": [ - "127.0.0.1" - ], - "X-Forwarded-For": [ - "10.244.1.5" - ], - "X-Forwarded-Proto": [ - "http" - ], - "X-Request-Id": [ - "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" - ] - }, - "namespace": "default", - "ingress": "", - "service": "", - "pod": "zone-routing-backend-local-5586cd668d-md8sf" -} -``` - - -## Clean-Up - -Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. - -Delete the zone-routing example resources and HTTPRoute: - -```shell -kubectl delete service/zone-routing-backend -kubectl delete deployment/zone-routing-backend-local -kubectl delete deployment/zone-routing-backend-nonlocal -kubectl delete httproute/zone-routing -``` - -[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution -[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ -[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone \ No newline at end of file diff --git a/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md b/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md new file mode 100644 index 0000000000..21243547e4 --- /dev/null +++ b/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md @@ -0,0 +1,219 @@ +--- +title: "Zone Aware Routing" +--- + +EnvoyGateway makes use of [Envoy Zone Aware Routing][Envoy Zone Aware Routing] to support Kubernetes [Traffic Distribution][Traffic Distribution] +and [Topology Aware Routing][Topology Aware Routing] which are useful for keeping network traffic in the originating zone. +Preferring same-zone traffic between Pods in your cluster can help with reliability, performance (network latency and throughput), or cost. + +{{% alert title="Note" color="primary" %}} +The current implementation for Topology Aware Routing support doesn't respect the minimum of 3 endpoints per zone +requirement and applies the same logic as `spec.TrafficDistribution=PreferClose`. This will be fixed in the next release. +{{% /alert %}} + + +## Prerequisites +* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. +* There must be at least two valid topology zones for scheduling. +* {{< boilerplate prerequisites >}} + +## Configuration + +### Kubernetes Service +Create the example Kubernetes Service with either topology aware routing or traffic distribution enabled. + +###### Topology Aware Routing +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +###### Traffic Distribution +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +### Example deployments and HTTPRoute +Next apply the example manifests to create two Deployments and an HTTPRoute. For the test configuration one Deployment +(zone-aware-routing-backend-local) includes affinity for EnvoyProxy Pods to ensure its Pods are scheduled in the same +zone and the second Deployment (zone-aware-routing-backend-nonlocal) uses anti-affinity to ensure its Pods _don't_ +schedule to the same zone in order to demonstrate functionality. +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-aware-routing.yaml -n default +``` + +Ensure that both example Deployments are marked as ready and produces the following output: +```shell +kubectl get deployment/zone-aware-routing-backend-local deployment/zone-aware-routing-backend-nonlocal -n default +NAME READY UP-TO-DATE AVAILABLE AGE +zone-aware-routing-backend-local 1/1 1 1 9m1s +zone-aware-routing-backend-nonlocal 1/1 1 1 9m1s + +``` + +An HTTPRoute resource is created for the `/zone-aware-routing` path prefix along with two example Deployment resources that +are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/zone-aware-routing -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-aware-routing" -XPOST -d '{}' +``` + +We will see the following output. The `pod` header identifies which backend received the request and should have +a name prefix of `zone-aware-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should +not receive requests. + +``` +{ + "path": "/zone-aware-routing", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.1.5" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "zone-aware-routing-backend-local-5586cd668d-md8sf" +} +``` + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the zone-aware-routing example resources and HTTPRoute: + +```shell +kubectl delete service/zone-aware-routing-backend +kubectl delete deployment/zone-aware-routing-backend-local +kubectl delete deployment/zone-aware-routing-backend-nonlocal +kubectl delete httproute/zone-aware-routing +``` + +[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution +[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ +[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone +[Envoy Zone Aware Routing]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/zone_aware \ No newline at end of file From 7437de8ddf31861c2571ebf0d0786cc2ada21c50 Mon Sep 17 00:00:00 2001 From: jukie <10012479+Jukie@users.noreply.github.com> Date: Fri, 30 May 2025 19:06:34 -0600 Subject: [PATCH 5/6] linting Signed-off-by: jukie <10012479+Jukie@users.noreply.github.com> --- site/content/en/latest/tasks/traffic/zone-aware-routing.md | 5 ++--- site/content/en/v1.4/tasks/traffic/zone-aware-routing.md | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/site/content/en/latest/tasks/traffic/zone-aware-routing.md b/site/content/en/latest/tasks/traffic/zone-aware-routing.md index 21243547e4..a2aba7ee79 100644 --- a/site/content/en/latest/tasks/traffic/zone-aware-routing.md +++ b/site/content/en/latest/tasks/traffic/zone-aware-routing.md @@ -22,7 +22,7 @@ requirement and applies the same logic as `spec.TrafficDistribution=PreferClose` ### Kubernetes Service Create the example Kubernetes Service with either topology aware routing or traffic distribution enabled. -###### Topology Aware Routing +#### Topology Aware Routing {{< tabpane text=true >}} {{% tab header="Apply from stdin" %}} ```shell @@ -70,8 +70,7 @@ spec: {{% /tab %}} {{< /tabpane >}} - -###### Traffic Distribution +#### Traffic Distribution {{< tabpane text=true >}} {{% tab header="Apply from stdin" %}} ```shell diff --git a/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md b/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md index 21243547e4..a2aba7ee79 100644 --- a/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md +++ b/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md @@ -22,7 +22,7 @@ requirement and applies the same logic as `spec.TrafficDistribution=PreferClose` ### Kubernetes Service Create the example Kubernetes Service with either topology aware routing or traffic distribution enabled. -###### Topology Aware Routing +#### Topology Aware Routing {{< tabpane text=true >}} {{% tab header="Apply from stdin" %}} ```shell @@ -70,8 +70,7 @@ spec: {{% /tab %}} {{< /tabpane >}} - -###### Traffic Distribution +#### Traffic Distribution {{< tabpane text=true >}} {{% tab header="Apply from stdin" %}} ```shell From 048e12c4aba1f026a5e3ec755bff87f5c5686500 Mon Sep 17 00:00:00 2001 From: jukie <10012479+Jukie@users.noreply.github.com> Date: Fri, 30 May 2025 20:45:26 -0600 Subject: [PATCH 6/6] Fix link Signed-off-by: jukie <10012479+Jukie@users.noreply.github.com> --- site/content/en/latest/tasks/traffic/zone-aware-routing.md | 2 +- site/content/en/v1.4/tasks/traffic/zone-aware-routing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/en/latest/tasks/traffic/zone-aware-routing.md b/site/content/en/latest/tasks/traffic/zone-aware-routing.md index a2aba7ee79..415f13e1e2 100644 --- a/site/content/en/latest/tasks/traffic/zone-aware-routing.md +++ b/site/content/en/latest/tasks/traffic/zone-aware-routing.md @@ -123,7 +123,7 @@ Next apply the example manifests to create two Deployments and an HTTPRoute. For zone and the second Deployment (zone-aware-routing-backend-nonlocal) uses anti-affinity to ensure its Pods _don't_ schedule to the same zone in order to demonstrate functionality. ```shell -kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-aware-routing.yaml -n default +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/zone-aware-routing.yaml -n default ``` Ensure that both example Deployments are marked as ready and produces the following output: diff --git a/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md b/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md index a2aba7ee79..415f13e1e2 100644 --- a/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md +++ b/site/content/en/v1.4/tasks/traffic/zone-aware-routing.md @@ -123,7 +123,7 @@ Next apply the example manifests to create two Deployments and an HTTPRoute. For zone and the second Deployment (zone-aware-routing-backend-nonlocal) uses anti-affinity to ensure its Pods _don't_ schedule to the same zone in order to demonstrate functionality. ```shell -kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/zone-aware-routing.yaml -n default +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/zone-aware-routing.yaml -n default ``` Ensure that both example Deployments are marked as ready and produces the following output: