Add Envoy Proxy integration documentation for Permit.io

[omer9564]

Adds a guide for integrating Envoy's External Authorization (ext_authz) filter with a Permit PDP, using a GitOps-managed custom Rego entrypoint, and registers it in the Proxies & API Gateways sidebar alongside the AWS API Gateway, Kong and NGINX guides.

What the guide covers

1. Prerequisites — Envoy with the ext_authz filter, a running PDP on 0.9.10 or higher, and GitOps configured for the environment.
2. GitOps setup — pointing at the CLI flow (/how-to/permit-cli/permit-cli-gitops) and the manual flow (/integrations/gitops/github).
3. Envoy entrypoint policy — a custom/envoy_entrypoint.rego example that reads the request from input.attributes.request.http, builds a check input, and delegates to data.permit.root.allow.
4. PDP OPA plugin config — enabling envoy_ext_authz_grpc via PDP_OPA_PLUGINS, with addr (gRPC listen address) and path (the OPA data path of the entrypoint), alongside the required permit_graph plugin.
5. Envoy config — an ext_authz HTTP filter plus the matching cluster definition pointing at the PDP's gRPC port.
6. URL Mapping — how URL Mapping relates to the Envoy flow, with links to the simple and regex URL-mapping guides.
7. Audit Log ingestion — returning an object result with a permitio_metadata field so Envoy decisions populate the Audit Log's user, action, resource, tenant and decision columns. Includes the full field-to-column table, the precedence rule (input fields win; permitio_metadata is a fallback), the requirement that the OPA path stay under the permit/ prefix, and a note that these rows only show up under the All query type rather than the Check filter.
8. Example repository — placeholder for a future end-to-end sample.

Files changed

• docs/integrations/gateways/envoy.mdx — new guide (257 lines).
• sidebars.js — adds integrations/gateways/envoy to the Proxies & API Gateways category.

Notes

Documentation only — no code, config or build changes. Nothing outside the new page and its sidebar entry is touched.

[linear]

PER-13495 Envoy Filter PDP Integration

[netlify]

✅ Deploy Preview for permitio-docs ready!

Name	Link
🔨 Latest commit	e508d96
🔍 Latest deploy log	https://app.netlify.com/projects/permitio-docs/deploys/6a83078b7028340008aa7396
😎 Deploy Preview	https://deploy-preview-599--permitio-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[zeevmoney]

Re-open when relevant.

[Copilot]

Pull request overview

Adds a new “Envoy Proxy x Permit” integration guide to the Proxies & API Gateways documentation section, and exposes it in the Docusaurus sidebar so it’s discoverable alongside the existing AWS API Gateway / Kong / NGINX guides.

Changes:

• Add a new MDX guide describing Envoy ext_authz → Permit PDP integration, including GitOps-managed Rego entrypoint examples.
• Document PDP OPA plugin configuration (PDP_OPA_PLUGINS) and a minimal Envoy config snippet.
• Register the new guide in the “Proxies & API Gateways” sidebar category.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
sidebars.js	Adds the Envoy doc to the “Proxies & API Gateways” navigation list.
docs/integrations/gateways/envoy.mdx	New Envoy integration guide covering GitOps custom policies, PDP plugin config, and Envoy ext_authz setup.

Suppressed comments (1)

docs/integrations/gateways/envoy.mdx:257

• The “Example repository” section is currently a placeholder (“will be added here”). If there isn’t a repo link yet, it’s better to state that no example is available (or omit the section) rather than shipping a TODO in published docs.

## 7. Example repository

An example repository demonstrating this integration (including a complete `envoy_entrypoint.rego`, Envoy configuration, and GitOps layout) will be added here when it is available.

---

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

[zeevmoney]

Changes requested — 3 HIGH, 3 MEDIUM, 1 LOW.

Every factual claim in the guide was checked against the PDP, permit-opa, opa-envoy-plugin and permit-backend sources. Most hold up: the PDP_OPA_PLUGINS / permit_graph requirement, the 0.9.10 minimum, the envoy_ext_authz_grpc plugin name, the path to data.permit.* mapping, the permit/ prefix ingestion filter, all seven permitio_metadata field-to-column mappings, the input-wins precedence rule, and the Rego v0 syntax. The findings below are the claims that do not.

Blocking:

• HIGH docs/integrations/gateways/envoy.mdx:171 — regex URL mapping does not use the first captured group as the resource key; named groups become resource attributes and the resource comes from the mapping rule, per horizon/enforcer/api.py and the existing regex-url-mapping-check.mdx
• HIGH docs/integrations/gateways/envoy.mdx:158 — URL Mapping resolution is implemented only in the PDP's Python API (/allowed_url), which the ext_authz gRPC path never reaches; the section describes a flow that is not achievable today
• HIGH docs/integrations/gateways/envoy.mdx:75 — resource.type is set to the raw URL path, which cannot match any Permit resource key under KEY_REGEX, so the guide's only complete example always denies

Non-blocking:

• MEDIUM docs/integrations/gateways/envoy.mdx:187 — the Decision column is populated for the boolean entrypoint; get_decision() returns raw boolean results directly
• MEDIUM docs/integrations/gateways/envoy.mdx:199 — the default result carries no permitio_metadata, so is_empty() drops default-denied requests from the Audit Log entirely
• MEDIUM docs/integrations/gateways/envoy.mdx:147 — port 9191 is not in the PDP image's EXPOSE and needs pdp.additionalPorts on Helm; the guide never says to publish it
• LOW docs/integrations/gateways/envoy.mdx:52 — bare package permit diverges from the permit.custom convention documented for the custom/ folder

Details are in the inline comments on each line.

Two open threads from an earlier review are still valid and unaddressed: the missing http2_protocol_options on the gRPC cluster (line 138) and the placeholder content (lines 164 and 255). Not duplicated here.

[omer9564]

@zeevmoney Addressed the requested changes in e508d96 — dropped the unreachable URL Mapping section, fixed resource-key / package / audit-log claims, and documented HTTP/2 plus publishing port 9191. Replies are on the inline threads.