Skip to content

Commit 1496eb6

Browse files
committed
docs: add EnvoyPatchPolicy cluster patching example
Document how to patch Cluster resources with EnvoyPatchPolicy, including cluster name format and a working load balancing policy example using replace instead of add. Fixes #7306 Signed-off-by: amarkdotdev <amark@g.jct.ac.il> Signed-off-by: Aaron <amark@g.jct.ac.il>
1 parent fc28561 commit 1496eb6

1 file changed

Lines changed: 100 additions & 0 deletions

File tree

site/content/en/latest/tasks/extensibility/envoy-patch-policy.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,8 @@ Because [EnvoyPatchPolicy][] relies on specific xDS resource names, it’s impor
121121
| **HCM StatPrefix** | Old | `<ApplicationProtocol>/<ContainerPort>` | `http-10080`, `https-10443` |
122122
| | V2 (HTTP) | `http-<Port>` | `http-80` |
123123
| | V2 (HTTPS) | `https-<Port>` | `https-443` |
124+
| **Cluster name** | Old | `httproute/<HTTPRouteNamespace>/<HTTPRouteName>/rule/<RuleIndex>` | `default/backend/rule/0` |
125+
| | V2 | `httproute/<HTTPRouteNamespace>/<HTTPRouteName>/rule/<RuleIndex>` | `default/backend/rule/0` |
124126

125127

126128
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.
@@ -451,6 +453,104 @@ $ curl -v --header "Host: www.example.com" http://localhost:8888/
451453
...
452454
```
453455
456+
### Patch Cluster Configuration
457+
458+
* Use [EnvoyPatchPolicy][] to modify an upstream cluster generated for an HTTPRoute rule.
459+
This example replaces the default load balancing policy with client-side weighted round robin.
460+
461+
* Cluster names follow the format `httproute/<HTTPRouteNamespace>/<HTTPRouteName>/rule/<RuleIndex>`.
462+
For an HTTPRoute named `server-route` in namespace `envoy-poc` with a single rule, the cluster name is
463+
`httproute/envoy-poc/server-route/rule/0`.
464+
465+
* Use [egctl x translate][] to confirm the exact cluster name in your environment before applying a patch.
466+
467+
* Envoy Gateway already sets `load_balancing_policy` on generated clusters, so use `replace` instead of `add`
468+
when modifying that field.
469+
470+
* Apply the configuration
471+
472+
{{< tabpane text=true >}}
473+
{{% tab header="Apply from stdin" %}}
474+
475+
```shell
476+
cat <<EOF | kubectl apply -f -
477+
apiVersion: gateway.envoyproxy.io/v1alpha1
478+
kind: EnvoyPatchPolicy
479+
metadata:
480+
name: server-route-client-wrr
481+
namespace: envoy-poc
482+
spec:
483+
type: JSONPatch
484+
targetRef:
485+
group: gateway.networking.k8s.io
486+
kind: Gateway
487+
name: eg
488+
namespace: envoy-poc
489+
jsonPatches:
490+
- type: type.googleapis.com/envoy.config.cluster.v3.Cluster
491+
# Cluster name for HTTPRoute rule 0 in namespace envoy-poc
492+
name: httproute/envoy-poc/server-route/rule/0
493+
operation:
494+
op: replace
495+
path: /load_balancing_policy
496+
value:
497+
policies:
498+
- typed_extension_config:
499+
name: envoy.load_balancing_policies.client_side_weighted_round_robin
500+
typed_config:
501+
"@type": type.googleapis.com/envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin
502+
EOF
503+
```
504+
505+
{{% /tab %}}
506+
{{% tab header="Apply from file" %}}
507+
Save and apply the following resource to your cluster:
508+
509+
```yaml
510+
---
511+
apiVersion: gateway.envoyproxy.io/v1alpha1
512+
kind: EnvoyPatchPolicy
513+
metadata:
514+
name: server-route-client-wrr
515+
namespace: envoy-poc
516+
spec:
517+
type: JSONPatch
518+
targetRef:
519+
group: gateway.networking.k8s.io
520+
kind: Gateway
521+
name: eg
522+
namespace: envoy-poc
523+
jsonPatches:
524+
- type: type.googleapis.com/envoy.config.cluster.v3.Cluster
525+
# Cluster name for HTTPRoute rule 0 in namespace envoy-poc
526+
name: httproute/envoy-poc/server-route/rule/0
527+
operation:
528+
op: replace
529+
path: /load_balancing_policy
530+
value:
531+
policies:
532+
- typed_extension_config:
533+
name: envoy.load_balancing_policies.client_side_weighted_round_robin
534+
typed_config:
535+
"@type": type.googleapis.com/envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin
536+
```
537+
538+
{{% /tab %}}
539+
{{< /tabpane >}}
540+
541+
* Verify the patch was applied by checking the EnvoyPatchPolicy status
542+
543+
```shell
544+
kubectl get envoypatchpolicy server-route-client-wrr -n envoy-poc -o yaml
545+
```
546+
547+
The `Programmed=True` condition confirms the patch was applied. You can also inspect the generated
548+
cluster configuration with [egctl x translate][]:
549+
550+
```shell
551+
egctl x translate --from gateway-api -o yaml | yq '.clusters.dynamicActiveClusters[] | select(.cluster.name == "httproute/envoy-poc/server-route/rule/0")'
552+
```
553+
454554
## Debugging
455555

456556
### Runtime

0 commit comments

Comments
 (0)