envoyproxy / envoyproxy/gateway
Support backend dependencies for EnvoyExtensionPolicy Dynamic Modules
- Dominant language
- Go
- Stars
- 3k
- Forks
- 864
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 140
Description
*Description*:
Envoy HTTP Dynamic Modules can make HTTP callouts through named Envoy clusters. In Envoy Gateway, module specific configuration supplied through `EnvoyExtensionPolicy` is opaque to Envoy Gateway.
`EnvoyExtensionPolicy` has no supported way for a Dynamic Module to declare the backend it calls. The policy author and infrastructure operator must coordinate a cluster name in the opaque configuration and provision the corresponding cluster separately.
This works today, but Envoy Gateway cannot associate the backend with the policy. It therefore cannot resolve or validate the dependency, generate the required cluster, or report a missing or invalid dependency through policy status.
## Use case
I encountered this while developing [envoy-web-bot-auth](https://github.com/michalskalski/envoy-web-bot-auth). The module makes an HTTP callout to a resolver, and its opaque configuration contains the Envoy cluster name:
```yaml
dynamicModule:
- name: envoy-web-bot-auth
filterName: web-bot-auth
config:
resolver:
cluster: web-bot-auth-key-resolver
```
The module passes that value to Envoy's HTTP callout API:
https://github.com/michalskalski/envoy-web-bot-auth/blob/f446a83663af32a18c50d29b4bac14dae0a23057/crates/module/src/filter.rs#L218-L223
The resolver is deployed behind a Kubernetes Service, while the corresponding cluster is added separately through `EnvoyProxy.spec.bootstrap`:
https://github.com/michalskalski/envoy-web-bot-auth/blob/f446a83663af32a18c50d29b4bac14dae0a23057/examples/kind/overlays/external-resolver/kustomization.yaml#L7-L27
This is the only concrete use case I can currently provide, so I do not yet have evidence about how frequently other Dynamic Modules need similar backend dependencies.
However, the same issue may affect other HTTP Dynamic Modules. Any module that uses Envoy's callout API to contact a cluster not otherwise created by Envoy Gateway requires the operator to provision that cluster separately. Because Dynamic Module support in Envoy Gateway is relatively new, there may not yet be many public examples. This issue asks whether backend dependencies should become part of the supported integration model or remain operator managed.
## Existing mechanisms
`EnvoyProxy.spec.bootstrap` can create the required cluster, but this requires writing low-level Envoy configuration and manually keeping its name consistent with opaque module configuration. Envoy Gateway documents that backward compatibility of this field [not guaranteed across minor versions](https://github.com/envoyproxy/gateway/blob/v1.9.0/api/v1alpha1/envoyproxy_types.go#L63-L68).
`EnvoyPatchPolicy` can add the same cluster to generated xDS, as demonstrated by #9711. It still relies on manual name coordination and is [documented as unstable, with behavior that may change across versions](https://gateway.envoyproxy.io/v1.9/tasks/extensibility/envoy-patch-policy/)
Envoy Gateway already uses backend references for features such as [ExtProc](https://gateway.envoyproxy.io/v1.9/api/extension_types/#extproc). The [`BackendEndpoint` API](https://gateway.envoyproxy.io/v1.9/api/extension_types/#backendendpoint) supports FQDN, IP, and Unix-domain-socket endpoints. However, Dynamic Module configuration has no equivalent way to reference one of these backends.
## API considerations
Because `DynamicModule.config` is opaque to Envoy Gateway, a backend reference alone may not define the complete integration. Any API would also need to define how the module refers to the generated Envoy cluster without requiring Envoy Gateway to interpret module specific configuration or requiring users to depend on Envoy Gateway's internal cluster naming.
Questions for discussion may include:
- where the dependency should be declared: `EnvoyExtensionPolicy`, `EnvoyProxy`, or another resource
- how the module should identify the resulting cluster
- which backend types, reference authorization rules, and backend policies should apply.
## Desired behavior
Provide a supported way to associate an `EnvoyExtensionPolicy` Dynamic Module instance with one or more backend dependencies.
Envoy Gateway should be able to resolve and validate those dependencies, generate the required Envoy clusters, and make them usable by the module through a documented contract. Module specific configuration should remain opaque, and generated xDS cluster names should remain an implementation detail.
This issue can be considered complete when Envoy Gateway provides a supported and documented contract through which Dynamic Modules can declare and use backend dependencies, including appropriate validation, status reporting, and test coverage.
## Relevant links
- [Developer Slack discussion](https://envoyproxy.slack.com/archives/C07N7CYQT50/p1788447057449229)
- [Dynamic Modules documentation](https://gateway.envoyproxy.io/latest/tasks/extensibility/dynamic-modules/)
- [`DynamicModule` API reference](https://gateway.envoyproxy.io/latest/api/extension_types/#dynamicmodule)
- [Backend API documentation](https://gateway.envoyproxy.io/latest/tasks/traffic/backend/)
- [Previous `BackendRef` discussion for ExtAuth](https://github.com/envoyproxy/gateway/issues/2551)
- [HTTP callout support for Dynamic Modules (Envoy PR #39151)](https://github.com/envoyproxy/envoy/pull/39151)
- [`EnvoyPatchPolicy` cluster example (PR #9711)](https://github.com/envoyproxy/gateway/pull/9711)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the EnvoyExtensionPolicy DynamicModule API reference and the existing BackendEndpoint and ExtProc mechanisms. Compare those entry points with the Dynamic Modules documentation and EnvoyPatchPolicy example to define how dependencies and cluster references should work. Done means a documented contract with dependency validation, status reporting, and test coverage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- backend-api-design, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100