update based on reviews

salonichf5 · salonichf5 · commit ab2b7dc8dbda · 2024-06-26T15:15:10.000-06:00
diff --git a/site/content/how-to/monitoring/troubleshooting.md b/site/content/how-to/monitoring/troubleshooting.md
@@ -9,6 +9,18 @@ docs: "DOCS-1419"
 
 This topic describes possible issues users might encounter when using NGINX Gateway Fabric. When possible, suggested workarounds are provided.
 
+
+### Common Issues
+
+{{< bootstrap-table "table table-striped table-bordered" >}}
+| Problem Area                 | Symptom                                | Troubleshooting Method                                | Common Cause                                           |
+|------------------------------|----------------------------------------|------------------------------------------------------ |--------------------------------------------------------|
+| Startup                      | NGINX Gateway Fabric fails to start.   | Check logs for _nginx_ and _nginx-gateway_ container. | Missing default server TLS secret.                     |
+| Resources not configured     | Status missing on resources.           | Check referenced resources.                           | Referenced resources not belong to Gateway Fabric.     |
+| NGINX errors                 | Reload failures on NGINX               | Fix permissions for control plane                     | Security context not configured.                       |
+| Usage reporting              | Errors logs related to usage reporting | Enable usage reporting                                | Usage reporting disabled.                              |
+{{< /bootstrap-table >}}
+
 ### General troubleshooting
 
 When investigating a problem or requesting help, there are important data points that can be collected to help understand what issues may exist.
@@ -18,7 +30,7 @@ When investigating a problem or requesting help, there are important data points
 To check the status of a resource, use `kubectl describe`. This example checks the status of the `coffee` HTTPRoute, which has an error:
 
 ```shell
-kubectl describe httproutes.gateway.networking.k8s.io coffee [-n namespace]
+kubectl describe httproutes.gateway.networking.k8s.io coffee -n nginx-gateway
 ```
 
 ```text
@@ -49,12 +61,14 @@ Status:
 
 If a resource has errors relating to its configuration or relationship to other resources, they can likely be read in the status. The `ObservedGeneration` in the status should match the `ObservedGeneration` of the resource. Otherwise, this could mean that the resource hasn't been processed yet or that the status failed to update.
 
+If no `Status` is written on the resource, further debug by checking if the referenced resources exists and belong to NGINX Gateway Fabric.
+
 ##### Events
 
 Events created by NGINX Gateway Fabric or other Kubernetes components could indicate system or configuration issues. To see events:
 
 ```shell
-kubectl get events [-n namespace]
+kubectl get events -n nginx-gateway
 ```
 
 For example, a warning event when the NginxGateway configuration CRD is deleted:
@@ -70,31 +84,33 @@ LAST SEEN   TYPE      REASON              OBJECT
 Getting shell access to containers allows developers and operators to view the environment of a running container, see its logs or diagnose any problems. To get shell access to the NGINX container, use `kubectl exec`:
 
 ```shell
-kubectl exec -it [-n namespace] <ngf-pod-name> -c nginx /bin/sh
+kubectl exec -it -n nginx-gateway  <ngf-pod-name> -c nginx /bin/sh
 ```
 
 ##### Logs
 
 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 see logs for the control plane container:
+1. To see logs for the:
+
+- Control plane container
 
 ```shell
-kubectl [-n namespace] logs <ngf-pod-name> -c nginx-gateway
+kubectl -n nginx-gateway  logs <ngf-pod-name> -c nginx-gateway
 ```
 
-To see logs for the data plane container:
+- Data plane container
 
 ```shell
-kubectl [-n namespace] logs <ngf-pod-name> -c nginx
+kubectl -n nginx-gateway  logs <ngf-pod-name> -c nginx
 ```
 
 1. To only see error logs for control plane and data plane containers:
 
-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).
+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.
 
 ```shell
-kubectl [-n namespace] logs <ngf-pod-name> -c nginx-gateway | grep error
+kubectl -n nginx-gateway  logs <ngf-pod-name> -c nginx-gateway | grep error
 ```
 
 For example, an error message when telemetry is not enabled for NGINX Plus installations:
@@ -105,10 +121,10 @@ Defaulted container "nginx-gateway" out of: nginx-gateway, nginx
 {"level":"error","ts":"2024-06-13T18:22:16Z","logger":"usageReporter","msg":"Usage reporting must be enabled when using NGINX Plus; redeploy with usage reporting enabled","error":"usage reporting not enabled","stacktrace":"github.com/nginxinc/nginx-gateway-fabric/internal/mode/static.createUsageWarningJob.func1\n\tgithub.com/nginxinc/nginx-gateway-fabric/internal/mode/static/manager.go:616\nk8s.io/apimachinery/pkg/util/wait.JitterUntilWithContext.func1\n\tk8s.io/apimachinery@v0.30.1/pkg/util/wait/backoff.go:259\nk8s.io/apimachinery/pkg/util/wait.BackoffUntil.func1\n\tk8s.io/apimachinery@v0.30.1/pkg/util/wait/backoff.go:226\nk8s.io/apimachinery/pkg/util/wait.BackoffUntil\n\tk8s.io/apimachinery@v0.30.1/pkg/util/wait/backoff.go:227\nk8s.io/apimachinery/pkg/util/wait.JitterUntil\n\tk8s.io/apimachinery@v0.30.1/pkg/util/wait/backoff.go:204\nk8s.io/apimachinery/pkg/util/wait.JitterUntilWithContext\n\tk8s.io/apimachinery@v0.30.1/pkg/util/wait/backoff.go:259\ngithub.com/nginxinc/nginx-gateway-fabric/internal/framework/runnables.(*CronJob).Start\n\tgithub.com/nginxinc/nginx-gateway-fabric/internal/framework/runnables/cronjob.go:53\nsigs.k8s.io/controller-runtime/pkg/manager.(*runnableGroup).reconcile.func1\n\tsigs.k8s.io/controller-runtime@v0.18.4/pkg/manager/runnable_group.go:226"}
 ```
 
-For _nginx_ container:
+For _nginx_ container you can `grep` for various [error](https://nginx.org/en/docs/ngx_core_module.html#error_log) log levels and they are all logged in brackets `[emerg]`:
 
 ```shell
-kubectl [-n namespace] logs <ngf-pod-name> -c nginx-gateway | grep emerg
+kubectl -n nginx-gateway  logs <ngf-pod-name> -c nginx | grep emerg
 ```
 
 For example, if a variable is too long, NGINX may display such an error message:
@@ -119,7 +135,12 @@ kubectl logs -n nginx-gateway ngf-nginx-gateway-fabric-bb8598998-jwk2m -c nginx
 ```
 
 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.
-To view the access logs, get shell access to your NGINX container using the [steps](#get-shell-access-to-containers). The access logs are located in the file `/var/log/nginx/access.log` in the NGINX container.
+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.
+Another method to check access logs is by reviewing the container logs for _nginx_ using:
+
+```shell
+kubectl logs -n nginx-gateway <ngf-pod-name> -c nginx
+```
 
 You can see logs for a crashed or killed container by adding the `-p` flag to the above commands.
 
@@ -128,7 +149,7 @@ You can see logs for a crashed or killed container by adding the `-p` flag to th
 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`:
 
 ```shell
-kubectl describe pod <ngf-pod-name> [-n namespace]
+kubectl describe pod <ngf-pod-name> -n nginx-gateway
 ```
 
 The Pod description includes details about the image name, tags, current status, and environment variables. Please 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.
@@ -185,13 +206,14 @@ To debug NGINX Gateway Fabric, enable verbose logging by editing the `NginxGatew
 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.
 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.
 
-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-containers) and running `nginx -T`. If there are errors in your configuration file, the reload will fail and specify why it has failed.
+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.
 
 ### Understanding the generated NGINX config
 
-Understanding the NGINX configuration is key for fixing issues because it shows how NGINX handles requests. This helps tweak settings to make sure NGINX behaves the way you want it to for your application. The configuration file is found at /etc/nginx/nginx.conf within your NGINX container. To understand the usage of NGINX directives in the configuration file, consult this list of [NGINX directives](https://nginx.org/en/docs/dirindex.html).
+Understanding the NGINX configuration is key for fixing issues because it shows how NGINX handles requests. This helps tweak settings to make sure NGINX behaves the way you want it to for your application. To see your current configuration, you can open a shell in the _nginx_ container by following these [steps](#get-shell-access-to-nginx-container) and run `nginx -T`. To understand the usage of NGINX directives in the configuration file, consult this list of [NGINX directives](https://nginx.org/en/docs/dirindex.html).
 
-In this section, we will see how the `nginx.conf` gets updated as we configure different services, deployments and routes with NGINX Gateway Fabric. In the configuration file, you'll often find several server blocks, each assigned to specific ports and server names. NGINX selects the appropriate server for a request and evaluates the URI against the location directives within that block. In cases, where no resources are defined, NGINX Gateway Fabric generates a basic configuration with a default server listening on port 80 for all requests and additional blocks to manage errors with status codes 500 or 502.
+In this section, we will see how the configuration gets updated as we configure different Services, Deployments and HTTPRoutes with NGINX Gateway Fabric. In the configuration file, you'll often find several server blocks, each assigned to specific ports and server names. NGINX selects the appropriate server for a request and evaluates the URI against the location directives within that block.
+When only a Gateway resource is defined, but no Services or HTTPRoutes are configured, NGINX generates a basic configuration. This includes a default server listening on the ports specified in the Gateway listeners, handling all incoming requests. Additionally, there are blocks to manage errors with status codes 500 or 502.
 
 This is a default `server` block listening on port 80:
 
@@ -204,7 +226,7 @@ server {
 }
 ```
 
-Once routes with path matches and rules are defined, the nginx.conf is updated accordingly to determine which location block will manage incoming requests. To demonstrate how `nginx.conf` is changed, let's create some resources:
+Once HTTPRoute with path matches and rules are defined, the nginx.conf is updated accordingly to determine which location block will manage incoming requests. To demonstrate how `nginx.conf` is changed, let's create some resources:
 
 1. A Gateway with single listener on port 80. The hostname specified is `*.example.com`, so all incoming requests matching that wildcard is accepted by this Gateway.
 2. A simple `coffee` application with hostname `cafe.example.com` and referenced to the Gateway we created.
@@ -326,6 +348,8 @@ Handling connection for 8080
 </body>
 ```
 
+**Warning** The configuration may change in future releases.
+
 #### Metrics for Troubleshooting
 
 Metrics can be useful to identify performance bottlenecks and pinpoint areas of high resource consumption within NGINX Gateway Fabric. To setup metrics collection, refer to this [guide]({{< relref "prometheus.md" >}}). The metrics dashboard will help you understand problems with the way NGINX Gateway Fabric is setup or potential issues that could show up with time.
@@ -334,6 +358,11 @@ For example, metrics `nginx_reloads_total` and `nginx_reload_errors_total` offer
 
 In such situations, it's advisable to review the logs of both NGINX and NGINX Gateway containers for any potential error messages. Additionally, verify the configured resources to ensure they are in a valid state.
 
+#### Access the N+ Dashboard
+
+If you have NGINX Gateway Fabric installed with NGINX Plus, you can access the N+ dashboard at `http://localhost:8080/dashboard.html`.
+Please note that, the port number i.e `8080` needs to be the set to the port number you have port-forward your NGINX Gateway Fabric Pod. For further [details]({{< relref "dashboard.md" >}})
+
 ### Common Errors
 
 ##### Insufficient Privileges errors
