You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: site/content/how-to/traffic-management/routing-traffic-to-your-app.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -132,7 +132,7 @@ spec:
132
132
EOF
133
133
```
134
134
135
-
This gateway is associated with the NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a GatewayClass with the name **nginx**. NGINX Gateway Fabric will only configure gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass`[command-line flag](/docs/cli-help.md#static-mode).
135
+
This gateway is associated with the NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a GatewayClass with the name **nginx**. NGINX Gateway Fabric will only configure gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass`[command-line flag]({{< relref "/reference/cli-help.md#static-mode" >}}).
136
136
137
137
We specify a [listener](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Listener) on the gateway to open an entry point on the cluster. In this case, since the coffee application accepts HTTP requests, we create an HTTP listener, named **http**, that listens on port 80.
description: "Learn how NGINX Gateway Fabric validates Gateway API resources."
4
3
weight: 800
5
4
toc: true
6
5
docs: "DOCS-000"
7
6
---
8
7
9
8
## Overview
10
9
11
-
There are several reasons why NGF validates Gateway API resources:
10
+
NGINX Gateway Fabric validates Gateway API resources for several reasons:
12
11
13
-
-*Robustness*: to gracefully handle invalid resources.
14
-
-*Security*: to prevent malicious input from propagating to the NGINX configuration.
15
-
-*Correctness*: to conform to the Gateway API specification for handling invalid resources.
12
+
-_Robustness_: to gracefully handle invalid resources.
13
+
-_Security_: to prevent malicious input from propagating to the NGINX configuration.
14
+
-_Correctness_: to conform to the Gateway API specification for handling invalid resources.
16
15
17
-
Ultimately, the goal is to ensure that NGINX continues to handle traffic even if invalid Gateway API resources were
18
-
created.
16
+
The process involves four different steps, explained in detail in this document, with the goal of making sure that NGINX continues to handle traffic even if invalid Gateway API resources were created.
19
17
20
-
A Gateway API resource (a new resource or an update for the existing one) is validated by the following steps:
18
+
## Step 1 - OpenAPI Scheme validation by Kubernetes API Server
21
19
22
-
### For Kubernetes 1.25+
23
-
24
-
1. OpenAPI schema validation by the Kubernetes API server.
25
-
2. CEL validation by the Kubernetes API server.
26
-
3. Webhook validation by NGF.
27
-
4. Validation by NGF.
28
-
29
-
### For Kubernetes 1.23 and 1.24
30
-
31
-
1. OpenAPI schema validation by the Kubernetes API server.
32
-
2. Webhook validation by the Gateway API webhook.
33
-
3. Webhook validation by NGF.
34
-
4. Validation by NGF.
35
-
36
-
To confirm that a resource is valid and accepted by NGF, check that the `Accepted` condition in the resource status
37
-
has the Status field set to `True`. For example, in a status of a valid HTTPRoute, if NGF accepts a parentRef,
> Make sure the reported observed generation is the same as the resource generation.
60
-
61
-
The remaining part of this document describes each step in detail with examples of how validation errors are reported.
62
-
63
-
### Step 1 - OpenAPI Scheme Validation by Kubernetes API Server
64
-
65
-
The Kubernetes API server validates Gateway API resources against the OpenAPI schema embedded in the Gateway API CRDs.
66
-
For example, if you create an HTTPRoute with an invalid hostname `cafe.!@#$%example.com`, the API server will reject it
67
-
with the following error:
20
+
The Kubernetes API server validates Gateway API resources against the OpenAPI schema embedded in the Gateway API CRDs. For example, if you create an HTTPRoute with an invalid hostname "cafe.!@#$%example.com", the API server will reject it with the following error:
The HTTPRoute "coffee" is invalid: spec.hostnames[0]: Invalid value: "cafe.!@#$%example.com": spec.hostnames[0] in body should match '^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
75
28
```
76
29
77
-
> While unlikely, bypassing this validation step is possible if the Gateway API CRDs are modified to remove the validation.
78
-
> If this happens, Step 4 will reject any invalid values (from NGINX perspective).
30
+
{{< note >}}While unlikely, bypassing this validation step is possible if the Gateway API CRDs are modified to remove the validation. If this happens, Step 4 will reject any invalid values (from NGINX perspective).{{< /note >}}
79
31
80
-
###Step 2 - For Kubernetes 1.25+ - CEL Validation by Kubernetes API Server
32
+
## Step 2 - CEL or Webhook validation by Kubernetes
81
33
82
-
The Kubernetes API server validates Gateway API resources using CEL validation embedded in the Gateway API CRDs.
83
-
It validates Gateway API resources using advanced rules unavailable in the OpenAPI schema validation.
84
-
For example, if you create a Gateway resource with a TCP listener that configures a hostname, the CEL validation will
85
-
reject it with the following error:
34
+
-**Kubernetes 1.25 and later - CEL validation by Kubernetes API Server**
86
35
36
+
The Kubernetes API server validates Gateway API resources using CEL validation embedded in the Gateway API CRDs. It validates Gateway API resources using advanced rules unavailable in the OpenAPI schema validation. For example, if you create a Gateway resource with a TCP listener that configures a hostname, the CEL validation will reject it with the following error:
87
37
88
-
```shell
89
-
kubectl apply -f some-gateway.yaml
90
-
```
38
+
```shell
39
+
kubectl apply -f some-gateway.yaml
40
+
```
91
41
92
-
```text
93
-
The Gateway "some-gateway" is invalid: spec.listeners: Invalid value: "array": hostname must not be specified for protocols ['TCP', 'UDP']
94
-
```
42
+
```text
43
+
The Gateway "some-gateway" is invalid: spec.listeners: Invalid value: "array": hostname must not be specified for protocols ['TCP', 'UDP']
44
+
```
95
45
96
-
More information on CEL in Kubernetes can be found [here](https://kubernetes.io/docs/reference/using-api/cel/).
46
+
More information on CEL in Kubernetes can be found [here](https://kubernetes.io/docs/reference/using-api/cel/).
97
47
98
-
### Step 2 - For Kubernetes 1.23 and 1.24 - Webhook Validation by Gateway API Webhook
99
48
100
-
The Gateway API comes with a validating webhook which is enabled by default in the Gateway API installation manifests.
101
-
It validates Gateway API resources using advanced rules unavailable in the OpenAPI schema validation. For example, if
102
-
you create a Gateway resource with a TCP listener that configures a hostname, the webhook will reject it with the
103
-
following error:
49
+
-**Kubernetes 1.23 and 1.24 - Webhook validation by Gateway API Webhook**
104
50
105
-
```shell
106
-
kubectl apply -f some-gateway.yaml
107
-
```
51
+
The validating webhook must be [installed for these Kubernetes versions]({{< relref "installation/installing-ngf/helm.md#installing-the-gateway-api-resources" >}}). It validates Gateway API resources using advanced rules unavailable in the OpenAPI schema validation. For example, if you create a Gateway resource with a TCP listener that configures a hostname, the webhook will reject it with the following error:
108
52
109
-
```text
110
-
Error from server: error when creating "some-gateway.yaml": admission webhook "validate.gateway.networking.k8s.io" denied the request: spec.listeners[1].hostname: Forbidden: should be empty for protocol TCP
111
-
```
53
+
```shell
54
+
kubectl apply -f some-gateway.yaml
55
+
```
112
56
113
-
> Bypassing this validation step is possible if the webhook is not running in the cluster.
114
-
> If this happens, Step 3 will reject the invalid values.
57
+
```text
58
+
Error from server: error when creating "some-gateway.yaml": admission webhook "validate.gateway.networking.k8s.io" denied the request: spec.listeners[1].hostname: Forbidden: should be empty for protocol TCP
59
+
```
115
60
116
-
### Step 3 - Webhook validation by NGF
61
+
{{< note >}}Bypassing this validation step is possible if the webhook is not running in the cluster. If this happens, Step 3 will reject the invalid values.{{< /note >}}
117
62
118
-
To ensure that the resources are validated with the webhook validation rules, even if the webhook is not running,
119
-
NGF performs the same validation. However, NGF performs the validation *after* the Kubernetes API server accepts
120
-
the resource.
63
+
## Step 3 - Webhook validation by NGINX Gateway Fabric
121
64
122
-
Below is an example of how NGF rejects an invalid resource (a Gateway resource with a TCP listener that configures a
123
-
hostname) with a Kubernetes event:
65
+
To ensure that the resources are validated with the webhook validation rules, even if the webhook is not running, NGINX Gateway Fabric performs the same validation. However, NGINX Gateway Fabric performs the validation _after_ the Kubernetes API server accepts the resource.
66
+
67
+
Below is an example of how NGINX Gateway Fabric rejects an invalid resource (a Gateway resource with a TCP listener that configures a hostname) with a Kubernetes event:
Warning Rejected 6s nginx-gateway-fabric-nginx the resource failed webhook validation, however the Gateway API webhook failed to reject it with the error; make sure the webhook is installed and running correctly; validation error: spec.listeners[1].hostname: Forbidden: should be empty for protocol TCP; NGF will delete any existing NGINX configuration that corresponds to the resource
78
+
Warning Rejected 6s nginx-gateway-fabric-nginx the resource failed webhook validation, however the Gateway API webhook failed to reject it with the error; make sure the webhook is installed and running correctly; validation error: spec.listeners[1].hostname: Forbidden: should be empty for protocol TCP; NGINX Gateway Fabric will delete any existing NGINX configuration that corresponds to the resource
135
79
```
136
80
137
-
> This validation step always runs and cannot be bypassed.
138
-
> NGF will ignore any resources that fail the webhook validation, like in the example above.
139
-
> If the resource previously existed, NGF will remove any existing NGINX configuration for that resource.
81
+
{{< note >}}This validation step always runs and cannot be bypassed. NGINX Gateway Fabric will ignore any resources that fail the webhook validation, like in the example above. If the resource previously existed, NGINX Gateway Fabric will remove any existing NGINX configuration for that resource.{{< /note >}}
140
82
141
-
###Step 4 - Validation by NGF
83
+
## Step 4 - Validation by NGINX Gateway Fabric
142
84
143
85
This step catches the following cases of invalid values:
144
86
145
-
- Valid values from the Gateway API perspective but not supported by NGF yet. For example, a feature in an
146
-
HTTPRoute routing rule. Note: for the list of supported features,
147
-
see [Gateway API Compatibility](gateway-api-compatibility.md) doc.
148
-
- Valid values from the Gateway API perspective, but invalid for NGINX, because NGINX has stricter validation
149
-
requirements for certain fields. Such values will cause NGINX to fail to reload or operate erroneously.
150
-
- Invalid values (both from the Gateway API and NGINX perspectives) that were not rejected because Step 1 was bypassed.
151
-
Similarly to the previous case, such values will cause NGINX to fail to reload or operate erroneously.
152
-
- Malicious values that inject unrestricted NGINX config into the NGINX configuration (similar to an SQL injection
153
-
attack).
87
+
- Valid values from the Gateway API perspective but not supported by NGINX Gateway Fabric yet. For example, a feature in an HTTPRoute routing rule. For the list of supported features see [Gateway API Compatibility](gateway-api-compatibility.md) doc.
88
+
- Valid values from the Gateway API perspective, but invalid for NGINX, because NGINX has stricter validation requirements for certain fields. These values will cause NGINX to fail to reload or operate erroneously.
89
+
- Invalid values (both from the Gateway API and NGINX perspectives) that were not rejected because Step 1 was bypassed. Similar to the previous case, these values will cause NGINX to fail to reload or operate erroneously.
90
+
- Malicious values that inject unrestricted NGINX config into the NGINX configuration (similar to an SQL injection attack).
154
91
155
-
Below is an example of how NGF rejects an invalid resource. The validation error is reported via the status:
92
+
Below is an example of how NGINX Gateway Fabric rejects an invalid resource. The validation error is reported via the status:
> This validation step always runs and cannot be bypassed.
118
+
{{< note >}}This validation step always runs and cannot be bypassed.{{< /note >}}
119
+
120
+
## Confirm validation
121
+
122
+
To confirm that a resource is valid and accepted by NGINX Gateway Fabric, check that the **Accepted** condition in the resource status has the Status field set to **True**. For example, in a status of a valid HTTPRoute, if NGINX Gateway Fabric accepts a parentRef, the status of that parentRef will look like this:
0 commit comments