Skip to content

docs: add EnvoyPatchPolicy cluster patching example #9949

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
amarkdotdev wants to merge 1 commit into
base: main
Choose a base branch
from
+100 −0
Open

docs: add EnvoyPatchPolicy cluster patching example #9949

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions site/content/en/latest/tasks/extensibility/envoy-patch-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ Because [EnvoyPatchPolicy][] relies on specific xDS resource names, it’s impor
| **HCM StatPrefix** | Old | `<ApplicationProtocol>/<ContainerPort>` | `http-10080`, `https-10443` |
| | V2 (HTTP) | `http-<Port>` | `http-80` |
| | V2 (HTTPS) | `https-<Port>` | `https-443` |
| **Cluster name** | Old | `httproute/<HTTPRouteNamespace>/<HTTPRouteName>/rule/<RuleIndex>` | `default/backend/rule/0` |
| | V2 | `httproute/<HTTPRouteNamespace>/<HTTPRouteName>/rule/<RuleIndex>` | `default/backend/rule/0` |
Comment on lines +124 to +125

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include the httproute prefix in cluster examples

The example contradicts the format in the same row: generated HTTPRoute cluster names include the leading httproute/ segment, as confirmed throughout the translation fixtures (for example internal/cmd/egctl/testdata/translate/out/from-gateway-api-to-xds.cluster.yaml:34). Readers copying default/backend/rule/0 will therefore target no xDS resource. Change both Old and V2 examples to httproute/default/backend/rule/0.

Useful? React with 👍 / 👎.



This change is gated by the XDSNameSchemeV2 runtime flag. The flag is disabled by default in v1.5 and will be enabled by default starting in v1.10.
Expand Down Expand Up @@ -451,6 +453,104 @@ $ curl -v --header "Host: www.example.com" http://localhost:8888/
...
```

### Patch Cluster Configuration

* Use [EnvoyPatchPolicy][] to modify an upstream cluster generated for an HTTPRoute rule.
This example replaces the default load balancing policy with client-side weighted round robin.

* Cluster names follow the format `httproute/<HTTPRouteNamespace>/<HTTPRouteName>/rule/<RuleIndex>`.
For an HTTPRoute named `server-route` in namespace `envoy-poc` with a single rule, the cluster name is
`httproute/envoy-poc/server-route/rule/0`.

* Use [egctl x translate][] to confirm the exact cluster name in your environment before applying a patch.

* Envoy Gateway already sets `load_balancing_policy` on generated clusters, so use `replace` instead of `add`
when modifying that field.

* Apply the configuration

{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}

```shell
cat <<EOF | kubectl apply -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyPatchPolicy
metadata:
name: server-route-client-wrr
namespace: envoy-poc

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Use resources created by the documented prerequisites

When a reader follows this page from the prerequisites, the quickstart creates the eg Gateway and backend HTTPRoute in default (examples/kubernetes/quickstart.yaml:8-17,72-91), but it never creates the envoy-poc namespace or server-route. Consequently this supposedly applicable example fails immediately because the namespace is absent, or cannot find the target cluster if the reader happens to have created that namespace. Reuse default/backend or add the missing namespace, Gateway, and HTTPRoute manifests.

Useful? React with 👍 / 👎.

spec:
type: JSONPatch
targetRef:
group: gateway.networking.k8s.io
kind: Gateway
name: eg
namespace: envoy-poc

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove the unsupported targetRef namespace

EnvoyPatchPolicy.spec.targetRef is a LocalPolicyTargetReference, and the generated CRD permits only group, kind, and name under this field (charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoypatchpolicies.yaml:135-165). Thus namespace is rejected by strict field validation or pruned with a warning rather than selecting the target namespace; attachment is already scoped by the policy's own namespace. Remove this field from both copies of the example.

Useful? React with 👍 / 👎.

jsonPatches:
- type: type.googleapis.com/envoy.config.cluster.v3.Cluster
# Cluster name for HTTPRoute rule 0 in namespace envoy-poc
name: httproute/envoy-poc/server-route/rule/0
operation:
op: replace
path: /load_balancing_policy
value:
policies:
- typed_extension_config:
name: envoy.load_balancing_policies.client_side_weighted_round_robin
typed_config:
"@type": type.googleapis.com/envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin
EOF
```

{{% /tab %}}
{{% tab header="Apply from file" %}}
Save and apply the following resource to your cluster:

```yaml
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyPatchPolicy
metadata:
name: server-route-client-wrr
namespace: envoy-poc
spec:
type: JSONPatch
targetRef:
group: gateway.networking.k8s.io
kind: Gateway
name: eg
namespace: envoy-poc
jsonPatches:
- type: type.googleapis.com/envoy.config.cluster.v3.Cluster
# Cluster name for HTTPRoute rule 0 in namespace envoy-poc
name: httproute/envoy-poc/server-route/rule/0
operation:
op: replace
path: /load_balancing_policy
value:
policies:
- typed_extension_config:
name: envoy.load_balancing_policies.client_side_weighted_round_robin
typed_config:
"@type": type.googleapis.com/envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin
```

{{% /tab %}}
{{< /tabpane >}}

* Verify the patch was applied by checking the EnvoyPatchPolicy status

```shell
kubectl get envoypatchpolicy server-route-client-wrr -n envoy-poc -o yaml
```

The `Programmed=True` condition confirms the patch was applied. You can also inspect the generated
cluster configuration with [egctl x translate][]:

```shell
egctl x translate --from gateway-api -o yaml | yq '.clusters.dynamicActiveClusters[] | select(.cluster.name == "httproute/envoy-poc/server-route/rule/0")'

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Provide the required input to the translate command

This verification command cannot execute as shown: egctl x translate --help defines --file/-f as required (also visible in internal/cmd/egctl/translate.go:92-113), while this invocation supplies neither a file nor stdin. Moreover, translated cluster output is nested below .xds.<config-key>.dynamicActiveClusters, not .clusters (internal/cmd/egctl/testdata/translate/out/from-gateway-api-to-xds.cluster.yaml:1-5). Supply the relevant Gateway API input and correct the query, or use egctl config envoy-proxy cluster to inspect the live patched proxy.

Useful? React with 👍 / 👎.

```

## Debugging

### Runtime
Expand Down