Add support for Snippets at the Gateway level

[bjee19]

There has been some community desire for Snippets to be set at the Gateway level.

See below for some examples:
#4050 (comment)
#1200 (comment)

This could be through a SnippetsPolicy, or some sort of connection of SnippetsFilter on the Gateway.

[nginx-discourse-bot]

This issue has been mentioned on NGINX Community Forum. There might be relevant details there:

https://community.nginx.org/t/nginx-fabric-server-configuration/7760/2

[fabian4]

I think we could introduce SnippetsPolicy to inject reusable NGINX config snippets at the Gateway scope, not only at Route scope (already covered by SnippetsFilter).

SnippetsFilter works well for http.server.location behaviors but is awkward for main/http/http.server behaviors—e.g. proxy_buffer_size, proxy_buffers, log_format, map, ssl_ parameters, shared limit_req_zone, and other per-Gateway defaults.

Gateway-level snippets by SnippetsPolicy would let user define consistent defaults and have them apply to all attached Routes, reducing duplication and misconfiguration risk.

---

Attachment

• Attaches to Gateway only (Optional future: ClusterSnippetsPolicy → GatewayClass).

Supported contexts

• main, http, http.server
• Exactly one snippet per context

Application scope

• HTTP(S) only (TLS-terminating gateways). Excludes TCP/UDP (stream), TLS passthrough, and internal fallback/redirect servers.

• (Optional) Hostname/Listener matching for http.server.

Validation & limits

• Directive allowlist/denylist
• Size/line limits per snippet
• Contexts limited to the three above
• reject structural conflicts (map, log_format, limit_req_zone, …)

Enablement & RBAC

• Behind controller flag / Helm value (disabled by default)
• Write access guarded by RBAC (platform admins only)

Merge & precedence

• Multiple policies at the same level merge by lexicographic (namespace/name) order

Apply workflow (safe rollout)

• Render includes → nginx -t dry-run
• On success: reload; on failure: rollback to last-known-good and surface rejection reasons in status/events

Output layout

//<gw> = <namespace>-<name>
//<server-id> = stable per-server identifier

includes/policy/<gw>/SnippetsPolicy_main_*.conf
includes/policy/<gw>/SnippetsPolicy_http_*.conf
includes/policy/<gw>/<server-id>/SnippetsPolicy_server_*.conf

---

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsPolicy
metadata:
  name: gateway-defaults
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: gw-public
    namespace: infra
  snippets:
    - context: main
      value: |
        worker_rlimit_nofile 65535;
    - context: http
      value: |
        log_format gw '$remote_addr $request $status $request_time';
        limit_req_zone $binary_remote_addr zone=gw_rl:20m rate=10r/s;
    - context: http.server
      value: |
        client_max_body_size 32m;
        add_header X-Frame-Options "SAMEORIGIN" always;

[github-actions]

This issue is stale because it has been open 14 days with no activity. Remove stale label or comment or this will be closed in 14 days.