envoyproxy / envoyproxy/gateway

Support backend dependencies for EnvoyExtensionPolicy Dynamic Modules

Open
#9,952 8 comments 0 reactions 0 assignees View on GitHub
kind/enhancement kind/feature
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.