Skip to content

Commit ebe3381

Browse files
fabian4fabian4
committed
Add SnippetsPolicy support and examples to documentation
1 parent c117100 commit ebe3381

File tree

9 files changed

+422
-1
lines changed

9 files changed

+422
-1
lines changed

‎charts/nginx-gateway-fabric/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,7 @@ The following table lists the configurable parameters of the NGINX Gateway Fabri
246246
| `nginx.usage.resolver` | The nameserver used to resolve the NGINX Plus usage reporting endpoint. Used with NGINX Instance Manager. | string | `""` |
247247
| `nginx.usage.secretName` | The name of the Secret containing the JWT for NGINX Plus usage reporting. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). | string | `"nplus-license"` |
248248
| `nginx.usage.skipVerify` | Disable client verification of the NGINX Plus usage reporting server certificate. | bool | `false` |
249-
| `nginxGateway` | The nginxGateway section contains configuration for the NGINX Gateway Fabric control plane deployment. | object | `{"affinity":{},"autoscaling":{"enable":false},"config":{"logging":{"level":"info"}},"configAnnotations":{},"extraVolumeMounts":[],"extraVolumes":[],"gatewayClassAnnotations":{},"gatewayClassName":"nginx","gatewayControllerName":"gateway.nginx.org/nginx-gateway-controller","gwAPIExperimentalFeatures":{"enable":false},"gwAPIInferenceExtension":{"enable":false,"endpointPicker":{"disableTLS":false,"skipVerify":true}},"image":{"pullPolicy":"Always","repository":"ghcr.io/nginx/nginx-gateway-fabric","tag":"edge"},"kind":"deployment","labels":{},"leaderElection":{"enable":true,"lockName":""},"lifecycle":{},"metrics":{"enable":true,"port":9113,"secure":false},"name":"","nodeSelector":{},"podAnnotations":{},"productTelemetry":{"enable":true},"readinessProbe":{"enable":true,"initialDelaySeconds":3,"port":8081},"replicas":1,"resources":{},"service":{"annotations":{},"labels":{}},"serviceAccount":{"annotations":{},"imagePullSecret":"","imagePullSecrets":[],"name":""},"snippetsFilters":{"enable":false},"terminationGracePeriodSeconds":30,"tolerations":[],"topologySpreadConstraints":[]}` |
249+
| `nginxGateway` | The nginxGateway section contains configuration for the NGINX Gateway Fabric control plane deployment. | object | `{"affinity":{},"autoscaling":{"enable":false},"config":{"logging":{"level":"info"}},"configAnnotations":{},"extraVolumeMounts":[],"extraVolumes":[],"gatewayClassAnnotations":{},"gatewayClassName":"nginx","gatewayControllerName":"gateway.nginx.org/nginx-gateway-controller","gwAPIExperimentalFeatures":{"enable":false},"gwAPIInferenceExtension":{"enable":false,"endpointPicker":{"disableTLS":false,"skipVerify":true}},"image":{"pullPolicy":"Always","repository":"ghcr.io/nginx/nginx-gateway-fabric","tag":"edge"},"kind":"deployment","labels":{},"leaderElection":{"enable":true,"lockName":""},"lifecycle":{},"metrics":{"enable":true,"port":9113,"secure":false},"name":"","nodeSelector":{},"podAnnotations":{},"productTelemetry":{"enable":true},"readinessProbe":{"enable":true,"initialDelaySeconds":3,"port":8081},"replicas":1,"resources":{},"service":{"annotations":{},"labels":{}},"serviceAccount":{"annotations":{},"imagePullSecret":"","imagePullSecrets":[],"name":""},"snippetsFilters":{"enable":false},"snippetsPolicies":{"enable":false},"terminationGracePeriodSeconds":30,"tolerations":[],"topologySpreadConstraints":[]}` |
250250
| `nginxGateway.affinity` | The affinity of the NGINX Gateway Fabric control plane pod. | object | `{}` |
251251
| `nginxGateway.autoscaling` | Autoscaling configuration for the NGINX Gateway Fabric control plane. | object | `{"enable":false}` |
252252
| `nginxGateway.autoscaling.enable` | Enable or disable Horizontal Pod Autoscaler for the control plane. | bool | `false` |
@@ -290,6 +290,7 @@ The following table lists the configurable parameters of the NGINX Gateway Fabri
290290
| `nginxGateway.serviceAccount.imagePullSecrets` | A list of secret names containing docker registry credentials for the control plane. Secrets must exist in the same namespace as the helm release. | list | `[]` |
291291
| `nginxGateway.serviceAccount.name` | The name of the service account of the NGINX Gateway Fabric control plane pods. Used for RBAC. | string | Autogenerated if not set or set to "" |
292292
| `nginxGateway.snippetsFilters.enable` | Enable SnippetsFilters feature. SnippetsFilters allow inserting NGINX configuration into the generated NGINX config for HTTPRoute and GRPCRoute resources. | bool | `false` |
293+
| `nginxGateway.snippetsPolicies.enable` | Enable SnippetsPolicies feature. SnippetsPolicies allow inserting NGINX configuration into the generated NGINX config for Gateway, HTTPRoute and GRPCRoute resources. | bool | `false` |
293294
| `nginxGateway.terminationGracePeriodSeconds` | The termination grace period of the NGINX Gateway Fabric control plane pod. | int | `30` |
294295
| `nginxGateway.tolerations` | Tolerations for the NGINX Gateway Fabric control plane pod. | list | `[]` |
295296
| `nginxGateway.topologySpreadConstraints` | The topology spread constraints for the NGINX Gateway Fabric control plane pod. | list | `[]` |

‎charts/nginx-gateway-fabric/values.schema.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1148,6 +1148,20 @@
11481148
"title": "snippetsFilters",
11491149
"type": "object"
11501150
},
1151+
"snippetsPolicies": {
1152+
"properties": {
1153+
"enable": {
1154+
"default": false,
1155+
"description": "Enable SnippetsPolicies feature. SnippetsPolicies allow inserting NGINX configuration into the generated NGINX\nconfig for Gateway, HTTPRoute and GRPCRoute resources.",
1156+
"required": [],
1157+
"title": "enable",
1158+
"type": "boolean"
1159+
}
1160+
},
1161+
"required": [],
1162+
"title": "snippetsPolicies",
1163+
"type": "object"
1164+
},
11511165
"terminationGracePeriodSeconds": {
11521166
"default": 30,
11531167
"description": "The termination grace period of the NGINX Gateway Fabric control plane pod.",

‎docs/snippets-policy.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# SnippetsPolicy
2+
3+
The `SnippetsPolicy` Custom Resource Definition (CRD) allows you to inject NGINX snippets into the configuration generated by NGINX Gateway Fabric. This is useful for advanced use cases where you need to configure NGINX directives that are not exposed through the Gateway API or other NGINX Gateway Fabric policies.
4+
5+
## Overview
6+
7+
`SnippetsPolicy` is an Attached Policy that targets a `Gateway` resource. It allows you to define snippets for specific NGINX contexts: `main`, `http`, and `http.server`.
8+
9+
> **Warning**: Using snippets can be dangerous. Incorrect snippets can cause NGINX to fail to reload or behave unexpectedly. Use with caution.
10+
11+
## Configuration
12+
13+
### SnippetsPolicy Spec
14+
15+
The `SnippetsPolicy` spec consists of a `targetRef` and a list of `snippets`.
16+
17+
- `targetRef`: Specifies the `Gateway` resource to attach the policy to.
18+
- `snippets`: A list of snippets to inject. Each snippet consists of:
19+
- `context`: The NGINX context to inject the snippet into. Supported values: `main`, `http`, `http.server`.
20+
- `value`: The NGINX configuration snippet string.
21+
22+
### Validation
23+
24+
NGINX Gateway Fabric validates the `SnippetsPolicy` to ensure:
25+
- Only one snippet is defined per context.
26+
- The context is one of the supported values.
27+
- The snippet size does not exceed the limit (4KB).
28+
29+
If a snippet is invalid (e.g., contains syntax errors), NGINX might fail to reload. NGINX Gateway Fabric attempts to validate the configuration using `nginx -t` before applying it. If validation fails, the configuration is not applied, and the `SnippetsPolicy` status is updated.
30+
31+
## Examples
32+
33+
### Basic Usage
34+
35+
The following example injects snippets into the `main`, `http`, and `http.server` contexts.
36+
37+
```yaml
38+
apiVersion: gateway.nginx.org/v1alpha1
39+
kind: SnippetsPolicy
40+
metadata:
41+
name: example-snippets-policy
42+
spec:
43+
targetRef:
44+
group: gateway.networking.k8s.io
45+
kind: Gateway
46+
name: my-gateway
47+
snippets:
48+
- context: main
49+
value: |
50+
worker_priority -5;
51+
- context: http
52+
value: |
53+
keepalive_timeout 65;
54+
- context: http.server
55+
value: |
56+
gzip on;
57+
gzip_types text/plain application/xml;
58+
```
59+
60+
### Enabling the Feature
61+
62+
To use `SnippetsPolicy`, you must enable the `snippetsPolicies` feature flag in the NGINX Gateway Fabric configuration.
63+
64+
If using Helm:
65+
66+
```yaml
67+
nginxGateway:
68+
snippetsPolicies: true
69+
```
70+
71+
If using the command line:
72+
73+
```bash
74+
--snippets-policies=true
75+
```

‎tests/suite/manifests/snippets-policy/cafe.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
apiVersion: gateway.networking.k8s.io/v1
2+
kind: HTTPRoute
3+
metadata:
4+
name: cafe
5+
spec:
6+
parentRefs:
7+
- name: gateway
8+
hostnames:
9+
- "cafe.example.com"
10+
rules:
11+
- matches:
12+
- path:
13+
type: PathPrefix
14+
value: /coffee
15+
backendRefs:
16+
- name: coffee
17+
port: 80
18+
---
19+
apiVersion: v1
20+
kind: Service
21+
metadata:
22+
name: coffee
23+
spec:
24+
ports:
25+
- port: 80
26+
targetPort: 80
27+
protocol: TCP
28+
name: http
29+
selector:
30+
app: coffee
31+
---
32+
apiVersion: apps/v1
33+
kind: Deployment
34+
metadata:
35+
name: coffee
36+
spec:
37+
replicas: 1
38+
selector:
39+
matchLabels:
40+
app: coffee
41+
template:
42+
metadata:
43+
labels:
44+
app: coffee
45+
spec:
46+
containers:
47+
- name: coffee
48+
image: nginxdemos/nginx-hello:plain-text
49+
ports:
50+
- containerPort: 80

‎tests/suite/manifests/snippets-policy/gateway.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
apiVersion: gateway.networking.k8s.io/v1
2+
kind: Gateway
3+
metadata:
4+
name: gateway
5+
spec:
6+
gatewayClassName: nginx
7+
listeners:
8+
- name: http
9+
port: 80
10+
protocol: HTTP

‎tests/suite/manifests/snippets-policy/invalid-context-sp.yaml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
apiVersion: gateway.nginx.org/v1alpha1
2+
kind: SnippetsPolicy
3+
metadata:
4+
name: invalid-context-sp
5+
spec:
6+
targetRef:
7+
group: gateway.networking.k8s.io
8+
kind: Gateway
9+
name: gateway
10+
snippets:
11+
- context: http
12+
value: "worker_priority 0;"

‎tests/suite/manifests/snippets-policy/invalid-duplicate-sp.yaml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
apiVersion: gateway.nginx.org/v1alpha1
2+
kind: SnippetsPolicy
3+
metadata:
4+
name: invalid-duplicate-sp
5+
spec:
6+
targetRef:
7+
group: gateway.networking.k8s.io
8+
kind: Gateway
9+
name: gateway
10+
snippets:
11+
- context: main
12+
value: "worker_processes 1;"

‎tests/suite/manifests/snippets-policy/valid-sp.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
apiVersion: gateway.nginx.org/v1alpha1
2+
kind: SnippetsPolicy
3+
metadata:
4+
name: valid-sp
5+
spec:
6+
targetRef:
7+
group: gateway.networking.k8s.io
8+
kind: Gateway
9+
name: gateway
10+
snippets:
11+
- context: main
12+
value: "worker_priority 0;"
13+
- context: http
14+
value: "aio off;"
15+
- context: http.server
16+
value: "auth_delay 0s;"

0 commit comments

Comments
 (0)