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
Logs from the NGINX Gateway Fabric control plane and data plane can contain information that isn't available to status or events. These can include errors in processing or passing traffic.
1. To only see error logs for control plane and data plane containers:
97
+
##### Error Logs
109
98
110
-
For _nginx-gateway_ container, you can `grep` for the word `error` or change the log level to `error` by following steps in [Modify logging levels](#modify-logging-levels). Once you have modified log levels, you can `grep` for the word `debug` to check debug logs for further investigation.
99
+
To see error logs for control plane and data plane containers:
100
+
101
+
For _nginx-gateway_ container, you can `grep` for the word `error` or change the log level to `error` by following steps in [Modify log levels](#modify-log-levels). Once you have modified log levels, you can `grep` for the word `debug` to check debug logs for further investigation.
2024/06/13 20:04:17 [emerg] 27#27: too long parameter, probably missing terminating """ character in /etc/nginx/conf.d/http.conf:78
135
126
```
136
127
137
-
1. NGINX access logs are files that record all requests processed by the NGINX server. These logs provide detailed information about each request, which can be useful for troubleshooting, and analyzing web traffic.
138
-
To view the access logs, get shell access to your NGINX container using the [steps](#get-shell-access-to-nginx-container). The access logs are located in the file `/var/log/nginx/access.log` in the NGINX container.
139
-
Another method to check access logs is by reviewing the container logs for _nginx_ using:
NGINX access logs are files that record all requests processed by the NGINX server. These logs provide detailed information about each request, which can be useful for troubleshooting, and analyzing web traffic.
131
+
To view the access logs, get shell access to your NGINX container using the [steps](#get-shell-access-to-nginx-container). The access logs are located in the file `/var/log/nginx/access.log` in the NGINX container and present in logs for _nginx_ container.
144
132
145
133
You can see logs for a crashed or killed container by adding the `-p` flag to the above commands.
146
134
147
-
##### NGINX Gateway Fabric Pod is not running or ready
148
-
149
-
To understand why the NGINX Gateway Fabric Pod has not started running or is not ready, the first step is to check the state of the Pod to get detailed information about the current status and events happening in the Pod. To do this, use `kubectl describe`:
150
-
151
-
```shell
152
-
kubectl describe pod <ngf-pod-name> -n nginx-gateway
153
-
```
154
-
155
-
The Pod description includes details about the image name, tags, current status, and environment variables. Verify that these details match your setup and cross-check with the events to ensure everything is functioning as expected. For example, the Pod below has two containers that are running and the events reflect the same.
Normal Scheduled 40s default-scheduler Successfully assigned nginx-gateway/ngf-nginx-gateway-fabric-66dd665756-zh7d7 to kind-control-plane
189
-
Normal Pulled 40s kubelet Container image "nginx-gateway-fabric" already present on machine
190
-
Normal Created 40s kubelet Created container nginx-gateway
191
-
Normal Started 39s kubelet Started container nginx-gateway
192
-
Normal Pulled 39s kubelet Container image "nginx-gateway-fabric/nginx" already present on machine
193
-
Normal Created 39s kubelet Created container nginx
194
-
Normal Started 39s kubelet Started container nginx
195
-
```
196
-
197
-
198
-
### Modify logging levels
199
-
200
-
To debug NGINX Gateway Fabric, enable verbose logging by editing the `NginxGateway` configuration. This can be done either before or after deploying NGINX Gateway Fabric. Refer to this [guide](https://docs.nginx.com/nginx-gateway-fabric/how-to/configuration/control-plane-configuration) to do so.
201
-
202
-
### NGINX fails to reload
203
-
204
-
#### Description
135
+
##### Modify Log Levels
205
136
206
-
NGINX reload errors can occur for various reasons, including syntax errors in configuration files, permission issues, and more. To determine if NGINX has failed to reload, check logs for your _nginx-gateway_ and _nginx_ containers.
207
-
You will see the following error in the _nginx-gateway_ logs `failed to reload NGINX:` followed by the reason for the failure. Similarly, error logs in _nginx_ container start with `emerg`. For example, `2024/06/12 14:25:11 [emerg] 12345#0: open() "/var/run/nginx.pid" failed (13: Permission denied)` shows a critical error, such as a permission problem preventing NGINX from accessing necessary files.
208
-
209
-
To debug why your reload has failed, start with verifying the syntax of your configuration files by opening a shell in the NGINX container following these [steps](#get-shell-access-to-nginx-container) and running `nginx -T`. If there are errors in your configuration file, the reload will fail and specify why it has failed.
137
+
To see debug logs for control plane in NGINX Gateway Fabric, enable verbose logging by editing the `NginxGateway` configuration. This can be done either before or after deploying NGINX Gateway Fabric. Refer to this [guide](https://docs.nginx.com/nginx-gateway-fabric/how-to/configuration/control-plane-configuration) to do so.
210
138
211
139
### Understanding the generated NGINX config
212
140
@@ -348,7 +276,9 @@ Handling connection for 8080
348
276
</body>
349
277
```
350
278
351
-
**Warning** The configuration may change in future releases.
279
+
{{< caution >}}
280
+
The configuration may change in future releases. This configuration is valid for version 1.3.
281
+
{{< /caution >}}
352
282
353
283
#### Metrics for Troubleshooting
354
284
@@ -365,6 +295,72 @@ Note that, the port number i.e `8080` matches the port number you have port-forw
| Startup | NGINX Gateway Fabric fails to start. | Check logs for _nginx_ and _nginx-gateway_ container. | Missing TLS key and cert for SSL servers. |
302
+
| Resources not configured | Status missing on resources. | Check referenced resources. | Referenced resources not belong to Gateway Fabric. |
303
+
| NGINX errors | Reload failures on NGINX | Fix permissions for control plane. | Security context not configured. |
304
+
| Usage reporting | Errors logs related to usage reporting | Enable usage reporting. Refer to this [Usage Reporting]({{< relref "installation/usage-reporting.md" >}}) | Usage reporting disabled. |
305
+
{{< /bootstrap-table >}}
306
+
307
+
##### NGINX fails to reload
308
+
309
+
NGINX reload errors can occur for various reasons, including syntax errors in configuration files, permission issues, and more. To determine if NGINX has failed to reload, check logs for your _nginx-gateway_ and _nginx_ containers.
310
+
You will see the following error in the _nginx-gateway_ logs `failed to reload NGINX:` followed by the reason for the failure. Similarly, error logs in _nginx_ container start with `emerg`. For example, `2024/06/12 14:25:11 [emerg] 12345#0: open() "/var/run/nginx.pid" failed (13: Permission denied)` shows a critical error, such as a permission problem preventing NGINX from accessing necessary files.
311
+
312
+
To debug why your reload has failed, start with verifying the syntax of your configuration files by opening a shell in the NGINX container following these [steps](#get-shell-access-to-nginx-container) and running `nginx -T`. If there are errors in your configuration file, the reload will fail and specify the reason for it.
313
+
314
+
##### NGINX Gateway Fabric Pod is not running or ready
315
+
316
+
To understand why the NGINX Gateway Fabric Pod has not started running or is not ready, the first step is to check the state of the Pod to get detailed information about the current status and events happening in the Pod. To do this, use `kubectl describe`:
317
+
318
+
```shell
319
+
kubectl describe pod <ngf-pod-name> -n nginx-gateway
320
+
```
321
+
322
+
The Pod description includes details about the image name, tags, current status, and environment variables. Verify that these details match your setup and cross-check with the events to ensure everything is functioning as expected. For example, the Pod below has two containers that are running and the events reflect the same.
Normal Scheduled 40s default-scheduler Successfully assigned nginx-gateway/ngf-nginx-gateway-fabric-66dd665756-zh7d7 to kind-control-plane
356
+
Normal Pulled 40s kubelet Container image "nginx-gateway-fabric" already present on machine
357
+
Normal Created 40s kubelet Created container nginx-gateway
358
+
Normal Started 39s kubelet Started container nginx-gateway
359
+
Normal Pulled 39s kubelet Container image "nginx-gateway-fabric/nginx" already present on machine
360
+
Normal Created 39s kubelet Created container nginx
361
+
Normal Started 39s kubelet Started container nginx
362
+
```
363
+
368
364
##### Insufficient Privileges errors
369
365
370
366
Depending on your environment's configuration, the control plane may not have the proper permissions to reload NGINX. The NGINX configuration will not be applied and you will see the following error in the _nginx-gateway_ logs:
0 commit comments