Clarify the interaction between EnvoyExtensionPolicy and recomputeRoute in ext-auth

[shulima]

Description:

We've encountered a non-obvious issue with EnvoyExtensionPolicy and route recomputation post-ext-auth.

The setup:

• Route A matches PathPrefix /
• Route B matches PathPrefix / and an x-custom-header
• SecurityPolicy attached to A sends requests to an ext-auth service, with recomputeRoute: true
• ext-auth service sets x-custom-header
• EnvoyExtensionPolicy attached to Route B contains a Lua script that rewrites path based on the contents of x-custom-header

The behavior we expected was that the Lua path rewrite in Route B would happen based on the header set by the ext-auth service. That, however, did not work. After much head scratching, we finally found this note at the bottom of config.route.v3.FilterConfig documentation:

This field will take effect when the request arrive and filter chain is created for the request. If initial route is selected for the request and a filter is disabled in the initial route, then the filter will not be added to the filter chain. And if the request is mutated later and re-match to another route, the disabled filter by the initial route will not be added back to the filter chain because the filter chain is already created and it is too late to change the chain.

The solution was to attach the EnvoyExtensionPolicy to the entire gateway listener, not just to Route B.

Assuming that this behavior can't be changed, I believe that this is a limitation worth mentioning explicitly in the documentation for either ext-auth or EnvoyExtensionPolicy, or possibly both.