docs: improve the document of filter_chain filter

[wbpcode]

Commit Message: docs: improve the document of filter_chain filter
Additional Description:
Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Fixes commit #PR or SHA]
[Optional Deprecated:]
[Optional API Considerations:]

[repokitteh-read-only]

Docs for this Pull Request will be rendered here:

https://storage.googleapis.com/envoy-cncf-pr/47496/docs/index.html

The docs are (re-)rendered each time the CI Envoy/Prechecks (docs) job completes.

🐱

Caused by: #47496 was opened by wbpcode.

see: more, trace.

[Copilot]

🟢 Approval recommended

Only minor documentation wording and clarification nits remain.

Pull request overview

Improves documentation for the filter_chain HTTP filter, covering route-level usage, global filter interaction, and ordering behavior.

Changes:

• Adds design rationale and behavior details.
• Documents hybrid global and route-level configurations.
• Expands examples and ordering guidance.

File summaries

File	Summary
docs/root/configuration/http/http_filters/filter_chain_filter.rst	Expanded filter-chain documentation, examples, and behavior notes.

Review details

Suppressed comments (3)

docs/root/configuration/http/http_filters/filter_chain_filter.rst:250

• The prose says the global header mutation filter “always runs last,” but this example places the router after it in http_filters, so the documented order contradicts the configuration and the later explicit order on lines 308-309. Please describe it as running after the route-level chain (or otherwise account for the router).

The platform team owns the global ``http_filters`` list and pins the order: the RBAC filter always
runs first, the application's own filters run next, and the global header mutation filter always
runs last. The application team only fills in the ``filter_chain`` slot in the middle and cannot
change the surrounding order:

docs/root/configuration/http/http_filters/filter_chain_filter.rst:17

• The new sentence uses “hybrid” as a verb (“hybrid route level filters”), which is grammatically unclear. Please use “combine” (or “combine ... with ...”) so the documentation clearly describes the relationship between the two filter sets.

list, it can flexibly hybrid route level filters with global ``http_filters`` and control their
relative order.

docs/root/configuration/http/http_filters/filter_chain_filter.rst:54

• The API explicitly warns that not all HTTP filters are currently compatible with route-level filter chains (api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto:57-61). This broad statement makes the feature sound universally applicable and should call out that compatibility limitation so users do not move unsupported filters out of http_filters and get configuration failures.

The filter chain filter takes a different approach: it inserts a single entry in ``http_filters``
that acts as a placeholder, and then lets users configure a complete route level filter chain in
the route through :ref:`FilterChainConfigPerRoute
<envoy_v3_api_msg_extensions.filters.http.filter_chain.v3.FilterChainConfigPerRoute>`. Each route
decides which filters it needs and in which order without any of them appearing in
``http_filters``, so adding a filter to one route never requires touching the listener-wide list.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.