From 508bd708a20acb40e41b531697f26c799e44ba09 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Thu, 8 Dec 2022 08:56:25 -0800 Subject: [PATCH 01/26] Updatng troubleshooting document --- .../troubleshoot-ingress-controller.md | 218 +++++++++++------- 1 file changed, 131 insertions(+), 87 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 7f425859ae..a8b578f512 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -47,102 +47,146 @@ To check the Ingress Controller logs -- both of the Ingress Controller software $ kubectl logs -n nginx-ingress ``` -Controlling the verbosity and format: -* To control the verbosity of the Ingress Controller software logs (from 1 to 4), use the `-v` [command-line argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). For example, with `-v=3` you will get more information and the content of any new or updated configuration file will be printed in the logs. -* To control the verbosity and the format of the NGINX logs, configure the corresponding [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource). +### Enabling debuging for NGINX Ingress Controller -### Checking the Events of an Ingress Resource +If you need to do additional troubleshooting for NGINX Ingress controller, there are few additional settings you can configure, to add more verbose logging. -After you create or update an Ingress resource, you can immediately check if the NGINX configuration for that Ingress resource was successfully applied by NGINX: -``` -$ kubectl describe ing cafe-ingress -Name: cafe-ingress -Namespace: default -. . . -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal AddedOrUpdated 12s nginx-ingress-controller Configuration for default/cafe-ingress was added or updated -``` -Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the configuration was successfully applied. - -### Checking the Events of a VirtualServer and VirtualServerRoute Resources - -After you create or update a VirtualServer resource, you can immediately check if the NGINX configuration for that resource was successfully applied by NGINX: -``` -$ kubectl describe vs cafe -. . . -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal AddedOrUpdated 16s nginx-ingress-controller Configuration for default/cafe was added or updated -``` -Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the configuration was successfully applied. - -Checking the events of a VirtualServerRoute is similar: -``` -$ kubectl describe vsr coffee -. . . -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal AddedOrUpdated 1m nginx-ingress-controller Configuration for default/coffee was added or updated -``` - -### Checking the Events of a Policy Resource - -After you create or update a Policy resource, you can use `kubectl describe` to check whether or not the Ingress Controller accepted the Policy: -``` -$ kubectl describe pol webapp-policy -. . . -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal AddedOrUpdated 11s nginx-ingress-controller Policy default/webapp-policy was added or updated -``` -Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the policy was successfully accepted. - -However, the fact that a policy was accepted doesn't guarantee that the NGINX configuration was successfully applied. To confirm that, check the events of the VirtualServer and VirtualServerRoute resources that reference that policy. - -### Checking the Events of the ConfigMap Resource - -After you update the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) resource, you can immediately check if the configuration was successfully applied by NGINX: -``` -$ kubectl describe configmap nginx-config -n nginx-ingress -Name: nginx-config -Namespace: nginx-ingress -Labels: -. . . -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Updated 11s (x2 over 26m) nginx-ingress-controller Configuration from nginx-ingress/nginx-config was updated -``` -Note that in the events section, we have a `Normal` event with the `Updated` reason, which informs us that the configuration was successfully applied. +There are two settings that need to be set to enable more debug/verbose logging for NGINX Ingress controller. -### Checking the Generated Config +1. command line arguments +2. configmap settings + +This document will cover how to enable both. + + +You can use NGINX Ingress controller command line arguments. This is a great way to increase debug log levels for both Ingress as well as NGINX. +When using `manifest` for deployment: + +1.) Use the command line argument, `- -nginx-debug` in your deployment/daemonset +2.) If you want to increase the Ingress `Controller` process lets, set the command line argument to `v=3`, which collects more information on Ingress + + ```yaml + -v=3 + ``` + +Here is a small snippet of setting these a command line arguments in the `ARGS` section of a deployment: + +```yaml +args: + - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config + - -enable-cert-manager + - -nginx-debug + - -v=3 +``` + +You can configure `error-log-level` in the NGINX Ingress controller `configMap`: + +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: nginx-config + namespace: nginx-ingress +data: + error-log-level: "debug" + ``` + +## When using `Helm` + +If you are using `helm`, you can look for these two settings: +``` +controller.nginxDebug = true or false +controller.loglevel = 1 to 3 value +``` +For example, if using a `values.yaml` file: + +```yaml + ## Enables debugging for NGINX. Uses the nginx-debug binary. Requires error-log-level: debug in the ConfigMap via `controller.config.entries`. + nginxDebug: true + + ## The log level of the Ingress Controller. + logLevel: 3 +``` +Here is a more complete `values.yaml` file when using `helm`: + +```yaml +controller: + kind: Deployment + nginxDebug: true + logLevel: 3 + annotations: + nginx: ingress-prod + pod: + annotations: + prometheus.io/scrape: "true" + prometheus.io/port: "9113" + prometheus.io/scheme: http + extraLabels: + env: prod-weset + nginxplus: plus + image: + repository: nginx/nginx-ingress + tag: 2.4.1 + # NGINX Configmap + config: + entries: + error-log-level: "debug" + proxy_connet_timeout: "5s" + http-snippets: | + underscores_in_headers on; + ingressClass: nginx +``` + +By enabling the `nginx-debug` CLI argument and changing the `error-log-level` to `debug`, you can capture more output and debug any issues that are going on. +**NOTE**: It is recommended to only use the `nginx-debug` CLI and the `error-log-level` enabled when debugging purposes. + +## Example of debugging output for NGINX Ingress controller pod. + +Once you have debugging enabled, you can see the logs have additional entries when reviewing logs: + +```nginx +I1026 15:39:03.269092 1 manager.go:301] Reloading nginx with configVersion: 1 +I1026 15:39:03.269115 1 utils.go:17] executing /usr/sbin/nginx-debug -s reload -e stderr +2022/10/26 15:39:03 [notice] 19#19: signal 1 (SIGHUP) received from 42, reconfiguring +2022/10/26 15:39:03 [debug] 19#19: wake up, sigio 0 +2022/10/26 15:39:03 [notice] 19#19: reconfiguring +2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF0A420:16384 @16 +2022/10/26 15:39:03 [debug] 19#19: add cleanup: 000056362AF0C318 +2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF48230:16384 @16 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF00DE0:4096 +2022/10/26 15:39:03 [debug] 19#19: read: 46, 000056362AF00DE0, 3090, 0 +2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF58670:16384 @16 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF12440:4280 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF13500:4280 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF145C0:4280 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF5C680:4280 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF5D740:4280 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF5E800:4280 +2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF5F8C0:16384 @16 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF41500:4096 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF638D0:8192 +2022/10/26 15:39:03 [debug] 19#19: include /etc/nginx/mime.types +2022/10/26 15:39:03 [debug] 19#19: include /etc/nginx/mime.types +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF658E0:4096 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF668F0:5349 +2022/10/26 15:39:03 [debug] 19#19: read: 47, 000056362AF658E0, 4096, 0 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF67DE0:4096 +2022/10/26 15:39:03 [debug] 19#19: read: 47, 000056362AF658E1, 1253, 4096 +2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF68DF0:16384 @16 +2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF6CE00:16384 @16 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF70E10:524288 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AFF0E20:524288 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362B070E30:524288 +2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362B0F0E40:400280 +``` + +Once you have completed your debugging process, you can change the values back to the original values. -For each Ingress/VirtualServer resource, the Ingress Controller generates a corresponding NGINX configuration file in the `/etc/nginx/conf.d` folder. Additionally, the Ingress Controller generates the main configuration file `/etc/nginx/nginx.conf`, which includes all the configurations files from `/etc/nginx/conf.d`. The config of a VirtualServerRoute resource is located in the configuration file of the VirtualServer that references the resource. -You can view the content of the main configuration file by running: -``` -$ kubectl exec -n nginx-ingress -- cat /etc/nginx/nginx.conf -``` - -Similarly, you can view the content of any generated configuration file in the `/etc/nginx/conf.d` folder. -You can also print all NGINX configuration files together: -``` -$ kubectl exec -n nginx-ingress -- nginx -T -``` -However, this command will fail if any of the configuration files is not valid. ### Checking the Live Activity Monitoring Dashboard The live activity monitoring dashboard shows the real-time information about NGINX Plus and the applications it is load balancing, which is helpful for troubleshooting. To access the dashboard, follow the steps from [here](/nginx-ingress-controller/logging-and-monitoring/status-page). -### Running NGINX in the Debug Mode - -Running NGINX in the [debug mode](https://docs.nginx.com/nginx/admin-guide/monitoring/debugging/) allows us to enable its debug logs, which can help to troubleshoot problems in NGINX. Note that it is highly unlikely that a problem you encounter with the Ingress Controller is caused by a bug in the NGINX code, but it is rather caused by NGINX misconfiguration. Thus, this method is rarely needed. -To enable the debug mode, set the `error-log-level` to `debug` in the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and use the `-nginx-debug` [command-line argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) when running the Ingress Controller. From bfa460ba796860a39257eb1f78ca7d7911cd6c21 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Dec 2022 17:45:20 +0000 Subject: [PATCH 02/26] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../troubleshoot-ingress-controller.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index a8b578f512..3cf8a842d5 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -51,7 +51,7 @@ $ kubectl logs -n nginx-ingress If you need to do additional troubleshooting for NGINX Ingress controller, there are few additional settings you can configure, to add more verbose logging. -There are two settings that need to be set to enable more debug/verbose logging for NGINX Ingress controller. +There are two settings that need to be set to enable more debug/verbose logging for NGINX Ingress controller. 1. command line arguments 2. configmap settings @@ -62,7 +62,7 @@ This document will cover how to enable both. You can use NGINX Ingress controller command line arguments. This is a great way to increase debug log levels for both Ingress as well as NGINX. When using `manifest` for deployment: -1.) Use the command line argument, `- -nginx-debug` in your deployment/daemonset +1.) Use the command line argument, `- -nginx-debug` in your deployment/daemonset 2.) If you want to increase the Ingress `Controller` process lets, set the command line argument to `v=3`, which collects more information on Ingress ```yaml @@ -91,9 +91,9 @@ data: error-log-level: "debug" ``` -## When using `Helm` +## When using `Helm` -If you are using `helm`, you can look for these two settings: +If you are using `helm`, you can look for these two settings: ``` controller.nginxDebug = true or false controller.loglevel = 1 to 3 value @@ -107,9 +107,9 @@ For example, if using a `values.yaml` file: ## The log level of the Ingress Controller. logLevel: 3 ``` -Here is a more complete `values.yaml` file when using `helm`: +Here is a more complete `values.yaml` file when using `helm`: -```yaml +```yaml controller: kind: Deployment nginxDebug: true @@ -140,7 +140,7 @@ controller: By enabling the `nginx-debug` CLI argument and changing the `error-log-level` to `debug`, you can capture more output and debug any issues that are going on. **NOTE**: It is recommended to only use the `nginx-debug` CLI and the `error-log-level` enabled when debugging purposes. -## Example of debugging output for NGINX Ingress controller pod. +## Example of debugging output for NGINX Ingress controller pod. Once you have debugging enabled, you can see the logs have additional entries when reviewing logs: @@ -188,5 +188,3 @@ Once you have completed your debugging process, you can change the values back t ### Checking the Live Activity Monitoring Dashboard The live activity monitoring dashboard shows the real-time information about NGINX Plus and the applications it is load balancing, which is helpful for troubleshooting. To access the dashboard, follow the steps from [here](/nginx-ingress-controller/logging-and-monitoring/status-page). - - From 3a5480b40e6cf39436b131cc479b3953b509ef2c Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Thu, 5 Jan 2023 16:35:29 -0800 Subject: [PATCH 03/26] Updating troubleshooting section guides --- .../troubleshoot-configmap-policy.md | 26 +++++++++++++++++++ .../troubleshoot-ingress-controller.md | 16 ++++++++++++ .../troubleshooting/troubleshoot-ingress.md | 12 +++++++++ .../troubleshoot-transportserver.md | 0 ...eshoot-virtualserver-virtualserverroute.md | 19 ++++++++++++++ 5 files changed, 73 insertions(+) create mode 100644 docs/content/troubleshooting/troubleshoot-configmap-policy.md create mode 100644 docs/content/troubleshooting/troubleshoot-ingress.md create mode 100644 docs/content/troubleshooting/troubleshoot-transportserver.md create mode 100644 docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md new file mode 100644 index 0000000000..5df0ec8c30 --- /dev/null +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -0,0 +1,26 @@ +Checking the Events of a Policy Resource +After you create or update a Policy resource, you can use kubectl describe to check whether or not the Ingress Controller accepted the Policy: + +$ kubectl describe pol webapp-policy +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 11s nginx-ingress-controller Policy default/webapp-policy was added or updated +Note that in the events section, we have a Normal event with the AddedOrUpdated reason, which informs us that the policy was successfully accepted. + +However, the fact that a policy was accepted doesn’t guarantee that the NGINX configuration was successfully applied. To confirm that, check the events of the VirtualServer and VirtualServerRoute resources that reference that policy. + +Checking the Events of the ConfigMap Resource +After you update the ConfigMap resource, you can immediately check if the configuration was successfully applied by NGINX: + +$ kubectl describe configmap nginx-config -n nginx-ingress +Name: nginx-config +Namespace: nginx-ingress +Labels: +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Updated 11s (x2 over 26m) nginx-ingress-controller Configuration from nginx-ingress/nginx-config was updated +Note that in the events section, we have a Normal event with the Updated reason, which informs us that the configuration was successfully applied. diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 3cf8a842d5..8f20da171e 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -182,7 +182,23 @@ I1026 15:39:03.269115 1 utils.go:17] executing /usr/sbin/nginx-debug -s re Once you have completed your debugging process, you can change the values back to the original values. +Checking the Generated Config +For each Ingress/VirtualServer resource, the Ingress Controller generates a corresponding NGINX configuration file in the /etc/nginx/conf.d folder. Additionally, the Ingress Controller generates the main configuration file /etc/nginx/nginx.conf, which includes all the configurations files from /etc/nginx/conf.d. The config of a VirtualServerRoute resource is located in the configuration file of the VirtualServer that references the resource. +You can view the content of the main configuration file by running: +``` +$ kubectl exec -n nginx-ingress -- cat /etc/nginx/nginx.conf +``` + +Similarly, you can view the content of any generated configuration file in the /etc/nginx/conf.d folder. + +You can also print all NGINX configuration files together: + +``` +$ kubectl exec -n nginx-ingress -- nginx -T +``` + +However, this command will fail if any of the configuration files is not valid. ### Checking the Live Activity Monitoring Dashboard diff --git a/docs/content/troubleshooting/troubleshoot-ingress.md b/docs/content/troubleshooting/troubleshoot-ingress.md new file mode 100644 index 0000000000..e9354ffbbb --- /dev/null +++ b/docs/content/troubleshooting/troubleshoot-ingress.md @@ -0,0 +1,12 @@ +Checking the Events of an Ingress Resource +After you create or update an Ingress resource, you can immediately check if the NGINX configuration for that Ingress resource was successfully applied by NGINX: + +$ kubectl describe ing cafe-ingress +Name: cafe-ingress +Namespace: default +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 12s nginx-ingress-controller Configuration for default/cafe-ingress was added or updated +Note that in the events section, we have a Normal event with the AddedOrUpdated reason, which informs us that the configuration was successfully applied. diff --git a/docs/content/troubleshooting/troubleshoot-transportserver.md b/docs/content/troubleshooting/troubleshoot-transportserver.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md new file mode 100644 index 0000000000..9a781f8162 --- /dev/null +++ b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md @@ -0,0 +1,19 @@ +Checking the Events of a VirtualServer and VirtualServerRoute Resources +After you create or update a VirtualServer resource, you can immediately check if the NGINX configuration for that resource was successfully applied by NGINX: + +$ kubectl describe vs cafe +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 16s nginx-ingress-controller Configuration for default/cafe was added or updated +Note that in the events section, we have a Normal event with the AddedOrUpdated reason, which informs us that the configuration was successfully applied. + +Checking the events of a VirtualServerRoute is similar: + +$ kubectl describe vsr coffee +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 1m nginx-ingress-controller Configuration for default/coffee was added or updated From 7403bcf133b419b2af176a2c20845150df813e55 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 6 Jan 2023 00:35:55 +0000 Subject: [PATCH 04/26] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../troubleshoot-virtualserver-virtualserverroute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md index 9a781f8162..96e3395a49 100644 --- a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md +++ b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md @@ -11,7 +11,7 @@ Note that in the events section, we have a Normal event with the AddedOrUpdated Checking the events of a VirtualServerRoute is similar: -$ kubectl describe vsr coffee +$ kubectl describe vsr coffee . . . Events: Type Reason Age From Message From 701c1724baff4363b67e083cdbbb014c3b0b032b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 5 Jan 2023 16:39:40 -0800 Subject: [PATCH 05/26] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Luca Comellini Signed-off-by: Jason Williams - NGIИX --- .../troubleshooting/troubleshoot-ingress-controller.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 8f20da171e..e843afe093 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -49,9 +49,9 @@ $ kubectl logs -n nginx-ingress ### Enabling debuging for NGINX Ingress Controller -If you need to do additional troubleshooting for NGINX Ingress controller, there are few additional settings you can configure, to add more verbose logging. +If you need to do additional troubleshooting for the Ingress Controller, there are a few additional settings you can configure, to add more verbose logging. -There are two settings that need to be set to enable more debug/verbose logging for NGINX Ingress controller. +There are two settings that need to be set to enable more debug/verbose logging for the Ingress Controller. 1. command line arguments 2. configmap settings From fb4a5150d38681adc2a286c5760fd726aff33dac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Fri, 6 Jan 2023 06:54:19 -0800 Subject: [PATCH 06/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Luca Comellini Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index e843afe093..2a2dfa7d1a 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -59,7 +59,7 @@ There are two settings that need to be set to enable more debug/verbose logging This document will cover how to enable both. -You can use NGINX Ingress controller command line arguments. This is a great way to increase debug log levels for both Ingress as well as NGINX. +You can use the Ingress Controller command line arguments. This is a great way to increase debug log levels for both the Ingress Controller as well as NGINX. When using `manifest` for deployment: 1.) Use the command line argument, `- -nginx-debug` in your deployment/daemonset From 96a8544dbcbf48efa75b85d8195249df2400f61c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Fri, 6 Jan 2023 06:54:27 -0800 Subject: [PATCH 07/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Luca Comellini Signed-off-by: Jason Williams - NGIИX --- .../troubleshooting/troubleshoot-ingress-controller.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 2a2dfa7d1a..992d6686d5 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -62,8 +62,8 @@ This document will cover how to enable both. You can use the Ingress Controller command line arguments. This is a great way to increase debug log levels for both the Ingress Controller as well as NGINX. When using `manifest` for deployment: -1.) Use the command line argument, `- -nginx-debug` in your deployment/daemonset -2.) If you want to increase the Ingress `Controller` process lets, set the command line argument to `v=3`, which collects more information on Ingress +1.) Use the command line argument `- -nginx-debug` in your deployment or daemonset +2.) If you want to increase the verbosity of the Ingress Controller process, set the command line argument to `v=3` ```yaml -v=3 From e6e86506accf33945fb0e9389468aa596086e871 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:40:23 -0800 Subject: [PATCH 08/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Luca Comellini Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 992d6686d5..23dad66b90 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -69,7 +69,7 @@ When using `manifest` for deployment: -v=3 ``` -Here is a small snippet of setting these a command line arguments in the `ARGS` section of a deployment: +Here is a small snippet of setting these command line arguments in the `args` section of a deployment: ```yaml args: From b02b41bd9d648c000f3ee9287c76061f2768a563 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:40:55 -0800 Subject: [PATCH 09/26] Update docs/content/troubleshooting/troubleshoot-configmap-policy.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-configmap-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md index 5df0ec8c30..b70013d352 100644 --- a/docs/content/troubleshooting/troubleshoot-configmap-policy.md +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -1,7 +1,7 @@ Checking the Events of a Policy Resource After you create or update a Policy resource, you can use kubectl describe to check whether or not the Ingress Controller accepted the Policy: -$ kubectl describe pol webapp-policy +`kubectl describe pol webapp-policy` . . . Events: Type Reason Age From Message From cf66958cd8efdf554d7768f94163d3496550b71c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:41:06 -0800 Subject: [PATCH 10/26] Update docs/content/troubleshooting/troubleshoot-configmap-policy.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-configmap-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md index b70013d352..ba5b5e9194 100644 --- a/docs/content/troubleshooting/troubleshoot-configmap-policy.md +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -14,7 +14,7 @@ However, the fact that a policy was accepted doesn’t guarantee that the NGINX Checking the Events of the ConfigMap Resource After you update the ConfigMap resource, you can immediately check if the configuration was successfully applied by NGINX: -$ kubectl describe configmap nginx-config -n nginx-ingress +`kubectl describe configmap nginx-config -n nginx-ingress` Name: nginx-config Namespace: nginx-ingress Labels: From efcf1291f93ab15914fa94af8a1ff920d77639bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:41:17 -0800 Subject: [PATCH 11/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 23dad66b90..c6dfe30d84 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -44,7 +44,7 @@ Note that the commands in the next sections make the following assumptions: To check the Ingress Controller logs -- both of the Ingress Controller software and the NGINX access and error logs -- run: ``` -$ kubectl logs -n nginx-ingress +`kubectl logs -n nginx-ingress` ``` ### Enabling debuging for NGINX Ingress Controller From d407cc372118dfc370c43c058be8bd36be16db93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:43:04 -0800 Subject: [PATCH 12/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index c6dfe30d84..7031e08fd3 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -59,7 +59,7 @@ There are two settings that need to be set to enable more debug/verbose logging This document will cover how to enable both. -You can use the Ingress Controller command line arguments. This is a great way to increase debug log levels for both the Ingress Controller as well as NGINX. +Using the command line arguments can be used to increase debug log levels for both the NGINX Ingress Controller as well as NGINX itself. When using `manifest` for deployment: 1.) Use the command line argument `- -nginx-debug` in your deployment or daemonset From e5fe3f6ad312b4fbf2d6bde7a18cdfe27f5d654a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:43:14 -0800 Subject: [PATCH 13/26] Update docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- .../troubleshoot-virtualserver-virtualserverroute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md index 96e3395a49..8039fc7129 100644 --- a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md +++ b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md @@ -1,7 +1,7 @@ Checking the Events of a VirtualServer and VirtualServerRoute Resources After you create or update a VirtualServer resource, you can immediately check if the NGINX configuration for that resource was successfully applied by NGINX: -$ kubectl describe vs cafe +`kubectl describe vs cafe` . . . Events: Type Reason Age From Message From 7a6b1b3472f52dc8fcd58067c90f2bc19d09c023 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:43:47 -0800 Subject: [PATCH 14/26] Update docs/content/troubleshooting/troubleshoot-configmap-policy.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-configmap-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md index ba5b5e9194..ea6ae989c3 100644 --- a/docs/content/troubleshooting/troubleshoot-configmap-policy.md +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -1,5 +1,5 @@ Checking the Events of a Policy Resource -After you create or update a Policy resource, you can use kubectl describe to check whether or not the Ingress Controller accepted the Policy: +After you create or update a Policy resource, you can use `kubectl describe` to check whether or not the Ingress Controller accepted the Policy: `kubectl describe pol webapp-policy` . . . From a56a8e2ae26ceb20be4ea01b4308acca32772bcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:43:54 -0800 Subject: [PATCH 15/26] Update docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- .../troubleshoot-virtualserver-virtualserverroute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md index 8039fc7129..e05830f5cf 100644 --- a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md +++ b/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md @@ -11,7 +11,7 @@ Note that in the events section, we have a Normal event with the AddedOrUpdated Checking the events of a VirtualServerRoute is similar: -$ kubectl describe vsr coffee +`kubectl describe vsr coffee` . . . Events: Type Reason Age From Message From 8514081232a405ada87fabf53d557a64c1795743 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Thu, 2 Feb 2023 12:45:21 -0800 Subject: [PATCH 16/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 7031e08fd3..35df9ada77 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -195,7 +195,7 @@ Similarly, you can view the content of any generated configuration file in the / You can also print all NGINX configuration files together: ``` -$ kubectl exec -n nginx-ingress -- nginx -T +`kubectl exec -n nginx-ingress -- nginx -T` ``` However, this command will fail if any of the configuration files is not valid. From eadd7bc62dbc582404b1528c795cffa7f8b58439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Mon, 6 Feb 2023 08:09:12 -0800 Subject: [PATCH 17/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index 35df9ada77..bd2d2a4c51 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -53,7 +53,7 @@ If you need to do additional troubleshooting for the Ingress Controller, there a There are two settings that need to be set to enable more debug/verbose logging for the Ingress Controller. -1. command line arguments +1. Command Line Arguments 2. configmap settings This document will cover how to enable both. From 288f478cc691da27de4f4e156c230d7078d755f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Mon, 6 Feb 2023 08:09:21 -0800 Subject: [PATCH 18/26] Update docs/content/troubleshooting/troubleshoot-ingress-controller.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress-controller.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index bd2d2a4c51..ed1047c705 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -54,7 +54,7 @@ If you need to do additional troubleshooting for the Ingress Controller, there a There are two settings that need to be set to enable more debug/verbose logging for the Ingress Controller. 1. Command Line Arguments -2. configmap settings +2. Configmap Settings This document will cover how to enable both. From a674e813c99fcfa06937f29842c69595f8828efa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Mon, 6 Feb 2023 08:09:35 -0800 Subject: [PATCH 19/26] Update docs/content/troubleshooting/troubleshoot-ingress.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/troubleshooting/troubleshoot-ingress.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress.md b/docs/content/troubleshooting/troubleshoot-ingress.md index e9354ffbbb..a5b7a20d7b 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress.md +++ b/docs/content/troubleshooting/troubleshoot-ingress.md @@ -1,7 +1,7 @@ Checking the Events of an Ingress Resource After you create or update an Ingress resource, you can immediately check if the NGINX configuration for that Ingress resource was successfully applied by NGINX: -$ kubectl describe ing cafe-ingress +`kubectl describe ing cafe-ingress` Name: cafe-ingress Namespace: default . . . From 77c06144b58121b0112720274f1b1cd8140b4479 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 21 Jun 2023 17:04:57 +0100 Subject: [PATCH 20/26] Apply suggestions from code review Signed-off-by: Alan Dooley --- .../troubleshooting/troubleshoot-ingress-controller.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-ingress-controller.md index ed1047c705..3a90d1cafe 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-ingress-controller.md @@ -49,7 +49,7 @@ To check the Ingress Controller logs -- both of the Ingress Controller software ### Enabling debuging for NGINX Ingress Controller -If you need to do additional troubleshooting for the Ingress Controller, there are a few additional settings you can configure, to add more verbose logging. +If you need to do additional troubleshooting for the NGINX Ingress Controller, there are a few additional settings for more verbose logging. There are two settings that need to be set to enable more debug/verbose logging for the Ingress Controller. @@ -79,7 +79,7 @@ args: - -v=3 ``` -You can configure `error-log-level` in the NGINX Ingress controller `configMap`: +You can configure `error-log-level` in the NGINX Ingress Controller `configMap`: ```yaml kind: ConfigMap From 241b5e1d31a44403c5fc203c0d73a13dd1cdf0c2 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 26 Jun 2023 11:45:33 +0100 Subject: [PATCH 21/26] Restructure, rename and rewrite various troubleshooting documents This commit adds the changes I have made thus far to the troubleshooting section of NGINX Ingress Controller's documentation: there is more to be done yet, but I am pushing these changes for others to see. The product naming is inconsistent, as is the layout of the pages - often, appropriate markdown is not used where it would make sense to, and formatting is otherwise missing. I will continue to update the documentation to fix these instances. --- ...s-controller.md => troubleshoot-common.md} | 8 +----- .../troubleshoot-configmap-policy.md | 8 ++++++ .../troubleshooting/troubleshoot-ingress.md | 8 ++++++ .../troubleshoot-transportserver.md | 11 ++++++++ ...route.md => troubleshoot-virtualserver.md} | 26 ++++++++++++++----- ....md => troubleshooting-app-protect-dos.md} | 21 +++++++-------- ....md => troubleshooting-app-protect-waf.md} | 15 +++++------ 7 files changed, 62 insertions(+), 35 deletions(-) rename docs/content/troubleshooting/{troubleshoot-ingress-controller.md => troubleshoot-common.md} (96%) rename docs/content/troubleshooting/{troubleshoot-virtualserver-virtualserverroute.md => troubleshoot-virtualserver.md} (50%) rename docs/content/troubleshooting/{troubleshooting-with-app-protect-dos.md => troubleshooting-app-protect-dos.md} (80%) rename docs/content/troubleshooting/{troubleshooting-with-app-protect.md => troubleshooting-app-protect-waf.md} (94%) diff --git a/docs/content/troubleshooting/troubleshoot-ingress-controller.md b/docs/content/troubleshooting/troubleshoot-common.md similarity index 96% rename from docs/content/troubleshooting/troubleshoot-ingress-controller.md rename to docs/content/troubleshooting/troubleshoot-common.md index 3a90d1cafe..e3b2b098d3 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress-controller.md +++ b/docs/content/troubleshooting/troubleshoot-common.md @@ -1,18 +1,12 @@ --- title: "Troubleshooting Common Issues" date: 2021-07-13T21:01:29-06:00 -draft: true -description: "This document describes how to troubleshoot problems with the Ingress Controller." -# Assign weights in increments of 100 +description: "How to troubleshoot common problems with NGINX Ingress Controller." weight: 100 draft: false toc: true tags: [ "docs" ] -# Taxonomies -# These are pre-populated with all available terms for your convenience. -# Remove all terms that do not apply. doctypes: ["troubleshooting"] -docs: "DOCS-619" --- ## Overview diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md index ea6ae989c3..38b27fc1db 100644 --- a/docs/content/troubleshooting/troubleshoot-configmap-policy.md +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -1,3 +1,11 @@ +--- +title: Troubleshooting Policy Resources +description: "." +weight: 200 +doctypes: [""] +toc: true +--- + Checking the Events of a Policy Resource After you create or update a Policy resource, you can use `kubectl describe` to check whether or not the Ingress Controller accepted the Policy: diff --git a/docs/content/troubleshooting/troubleshoot-ingress.md b/docs/content/troubleshooting/troubleshoot-ingress.md index a5b7a20d7b..22ff574320 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress.md +++ b/docs/content/troubleshooting/troubleshoot-ingress.md @@ -1,3 +1,11 @@ +--- +title: Troubleshooting Ingress Resources +description: "" +weight: 300 +doctypes: [""] +toc: true +--- + Checking the Events of an Ingress Resource After you create or update an Ingress resource, you can immediately check if the NGINX configuration for that Ingress resource was successfully applied by NGINX: diff --git a/docs/content/troubleshooting/troubleshoot-transportserver.md b/docs/content/troubleshooting/troubleshoot-transportserver.md index e69de29bb2..8ac5baa462 100644 --- a/docs/content/troubleshooting/troubleshoot-transportserver.md +++ b/docs/content/troubleshooting/troubleshoot-transportserver.md @@ -0,0 +1,11 @@ +--- +title: Troubleshooting TransportServer Resources +description: "." +weight: 400 +doctypes: [""] +draft: true +--- + +# Troubleshooting TransportServer Resources + +test test est \ No newline at end of file diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md b/docs/content/troubleshooting/troubleshoot-virtualserver.md similarity index 50% rename from docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md rename to docs/content/troubleshooting/troubleshoot-virtualserver.md index e05830f5cf..94537af99c 100644 --- a/docs/content/troubleshooting/troubleshoot-virtualserver-virtualserverroute.md +++ b/docs/content/troubleshooting/troubleshoot-virtualserver.md @@ -1,19 +1,31 @@ -Checking the Events of a VirtualServer and VirtualServerRoute Resources -After you create or update a VirtualServer resource, you can immediately check if the NGINX configuration for that resource was successfully applied by NGINX: +--- +title: Troubleshooting VirtualServer Resources +description: "This page describes how to troubleshoot VirtualServer and VirtualServer Resource Events." +weight: 500 +doctypes: [""] +toc: true +--- +## Inspecting VirtualServer and VirtualServerRoute Resource Events +After creating or updating a VirtualServer resource, you can immediately check if the NGINX configuration for that resource was successfully by using `kubectl describe vs `: -`kubectl describe vs cafe` -. . . +``` +kubectl describe vs cafe +# Example Output Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 16s nginx-ingress-controller Configuration for default/cafe was added or updated -Note that in the events section, we have a Normal event with the AddedOrUpdated reason, which informs us that the configuration was successfully applied. +``` + +In the above example, we have a `Normal` event with the `AddedOrUpdate` reason, which informs us that the configuration was successfully applied. Checking the events of a VirtualServerRoute is similar: -`kubectl describe vsr coffee` -. . . +``` +kubectl describe vsr coffee +# Example Output Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 1m nginx-ingress-controller Configuration for default/coffee was added or updated +``` \ No newline at end of file diff --git a/docs/content/troubleshooting/troubleshooting-with-app-protect-dos.md b/docs/content/troubleshooting/troubleshooting-app-protect-dos.md similarity index 80% rename from docs/content/troubleshooting/troubleshooting-with-app-protect-dos.md rename to docs/content/troubleshooting/troubleshooting-app-protect-dos.md index 6ea65ee3d4..a41f6a1d70 100644 --- a/docs/content/troubleshooting/troubleshooting-with-app-protect-dos.md +++ b/docs/content/troubleshooting/troubleshooting-app-protect-dos.md @@ -1,17 +1,14 @@ --- -title: Troubleshooting with NGINX App Protect Dos -description: "This document describes how to troubleshoot problems with the Ingress Controller with the App Protect Dos module enabled." -weight: 2000 +title: Troubleshooting with NGINX App Protect DoS +description: "This document describes how to troubleshoot problems with the Ingress Controller with the App Protect DoS module enabled." +weight: 700 doctypes: [""] -aliases: -- /app-protect/troubleshooting/ toc: true -docs: "DOCS-620" --- -This document describes how to troubleshoot problems with the Ingress Controller with the App Protect DoS module enabled. +This document describes how to troubleshoot problems with the NGINX Ingress Controller with the App Protect DoS module enabled. -For general troubleshooting of the Ingress Controller, check the general [troubleshooting](/nginx-ingress-controller/troubleshooting/) documentation. +To troubleshoot other parts of the NGINX Ingress Controller, check [troubleshooting](/nginx-ingress-controller/troubleshooting/) section of the documentation. ## Potential Problems @@ -26,9 +23,9 @@ The table below categorizes some potential problems with the Ingress Controller ## Troubleshooting Methods -### Check the Ingress Controller and App Protect DoS logs +### Checking NGINX Ingress Controller and App Protect DoS logs -App Protect DoS logs are part of the Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs](/nginx-ingress-controller/troubleshooting/#checking-the-ingress-controller-logs) of the Troubleshooting guide. +App Protect DoS logs are part of the NGINX Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs](/nginx-ingress-controller/troubleshooting/#checking-the-ingress-controller-logs) of the Troubleshooting guide. For App Protect DoS specific logs, look for messages starting with `APP_PROTECT_DOS`, for example: ``` @@ -37,11 +34,11 @@ For App Protect DoS specific logs, look for messages starting with `APP_PROTECT_ ### Check events of an Ingress Resource -Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#checking-the-events-of-an-ingress-resource" >}}). +Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-common#checking-the-events-of-an-ingress-resource" >}}). ### Check events of a VirtualServer Resource -Follow the steps of [Checking the Events of a VirtualServer Resource]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#checking-the-events-of-a-virtualserver-and-virtualserverroute-resources" >}}). +Follow the steps of [Checking the Events of a VirtualServer Resource]({{< relref "troubleshooting/troubleshoot-common#checking-the-events-of-a-virtualserver-and-virtualserverroute-resources" >}}). ### Check events of DosProtectedResource diff --git a/docs/content/troubleshooting/troubleshooting-with-app-protect.md b/docs/content/troubleshooting/troubleshooting-app-protect-waf.md similarity index 94% rename from docs/content/troubleshooting/troubleshooting-with-app-protect.md rename to docs/content/troubleshooting/troubleshooting-app-protect-waf.md index 2bf9fec20f..ee51b477b7 100644 --- a/docs/content/troubleshooting/troubleshooting-with-app-protect.md +++ b/docs/content/troubleshooting/troubleshooting-app-protect-waf.md @@ -1,17 +1,14 @@ --- -title: Troubleshooting with NGINX App Protect +title: Troubleshooting with NGINX App Protect WAF description: "This document describes how to troubleshoot problems when using NGINX Ingress Controller with the NGINX App Protect WAF module enabled." -weight: 2000 +weight: 800 doctypes: [""] -aliases: - - /app-protect/troubleshooting/ toc: true -docs: "DOCS-621" --- This document describes how to troubleshoot problems with the Ingress Controller with the [App Protect](/nginx-app-protect/) module enabled. -For general troubleshooting of the Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-ingress-controller.md" >}}) documentation. +For general troubleshooting of the Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-common." >}}) documentation. {{< see-also >}}You can find more troubleshooting tips in the NGINX App Protect WAF [troubleshooting guide](/nginx-app-protect/troubleshooting/) {{< /see-also >}}. @@ -31,7 +28,7 @@ The table below categorizes some potential problems with the Ingress Controller ### Check the Ingress Controller and App Protect logs -App Protect logs are part of the Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#checking-the-ingress-controller-logs" >}}) of the Troubleshooting guide. +App Protect logs are part of the Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs]({{< relref "troubleshooting/troubleshoot-common#checking-the-ingress-controller-logs" >}}) of the Troubleshooting guide. For App Protect specific logs, look for messages starting with `APP_PROTECT`, for example: ``` @@ -40,7 +37,7 @@ For App Protect specific logs, look for messages starting with `APP_PROTECT`, fo ### Check events of an Ingress Resource -Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#checking-the-events-of-an-ingress-resource" >}}). +Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-common#checking-the-events-of-an-ingress-resource" >}}). ### Check events of APLogConf @@ -100,7 +97,7 @@ curl -w '%{time_total}' http://192.168.100.100/resources/headersettings.txt ## Run App Protect in Debug Mode -When you set the Ingress Controller to use debug mode, the setting also applies to the App Protect WAF module. See [Running NGINX in the Debug Mode]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#running-nginx-in-the-debug-mode" >}}) for instructions. +When you set the Ingress Controller to use debug mode, the setting also applies to the App Protect WAF module. See [Running NGINX in the Debug Mode]({{< relref "troubleshooting/troubleshoot-common.md#running-nginx-in-the-debug-mode" >}}) for instructions. ## Known Issues From 8be78b8e1fae46e3cbb614d5638daa86fba1e4a5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 26 Jun 2023 10:53:23 +0000 Subject: [PATCH 22/26] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/troubleshooting/troubleshoot-transportserver.md | 2 +- docs/content/troubleshooting/troubleshoot-virtualserver.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-transportserver.md b/docs/content/troubleshooting/troubleshoot-transportserver.md index 8ac5baa462..cce6f6305f 100644 --- a/docs/content/troubleshooting/troubleshoot-transportserver.md +++ b/docs/content/troubleshooting/troubleshoot-transportserver.md @@ -8,4 +8,4 @@ draft: true # Troubleshooting TransportServer Resources -test test est \ No newline at end of file +test test est diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver.md b/docs/content/troubleshooting/troubleshoot-virtualserver.md index 94537af99c..99c7741dd8 100644 --- a/docs/content/troubleshooting/troubleshoot-virtualserver.md +++ b/docs/content/troubleshooting/troubleshoot-virtualserver.md @@ -28,4 +28,4 @@ Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 1m nginx-ingress-controller Configuration for default/coffee was added or updated -``` \ No newline at end of file +``` From b209d7b7db3c02800e241c918b7cf909436c7025 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 26 Jun 2023 17:26:15 +0100 Subject: [PATCH 23/26] Change instances of names, improve grammar and phrasing. --- .../troubleshooting/troubleshoot-common.md | 120 +++++++++--------- .../troubleshoot-configmap-policy.md | 31 +++-- .../troubleshooting/troubleshoot-ingress.md | 15 ++- .../troubleshoot-transportserver.md | 1 - .../troubleshoot-virtualserver.md | 10 +- .../troubleshooting-app-protect-dos.md | 60 +++++---- .../troubleshooting-app-protect-waf.md | 59 +++++---- 7 files changed, 161 insertions(+), 135 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-common.md b/docs/content/troubleshooting/troubleshoot-common.md index e3b2b098d3..368f03e5b3 100644 --- a/docs/content/troubleshooting/troubleshoot-common.md +++ b/docs/content/troubleshooting/troubleshoot-common.md @@ -1,26 +1,24 @@ --- title: "Troubleshooting Common Issues" date: 2021-07-13T21:01:29-06:00 -description: "How to troubleshoot common problems with NGINX Ingress Controller." +description: "This page describes how to troubleshoot common problems with NGINX Ingress Controller." weight: 100 draft: false toc: true tags: [ "docs" ] doctypes: ["troubleshooting"] +aliases: + - /content/troubleshooting/troubleshoot-ingress-controller --- -## Overview +## Common Problems -This document describes how to troubleshoot problems with the Ingress Controller. - -## Potential Problems - -The table below categorizes some potential problems with the Ingress Controller you may encounter and suggests how to troubleshoot those problems using one or more methods from the next section. +The table below shows common problems with NGINX Ingress Controller you may encounter and how to address them. The following section explains how to gather additional information, and there is instruction available on fixing specific issues within the troubleshooting section of documentation. {{% table %}} | Problem Area | Symptom | Troubleshooting Method | Common Cause | |-----|-----|-----|-----| -| Start | The Ingress Controller fails to start. | Check the logs. | Misconfigured RBAC, a missing default server TLS Secret.| +| Startup | NGINX Ingress Controller fails to start. | Check the logs. | Misconfigured RBAC, a missing default server TLS Secret.| | Ingress Resource and Annotations | The configuration is not applied | Check the events of the Ingress resource, check the logs, check the generated config. | Invalid values of annotations. | | VirtualServer and VirtualServerRoute Resources | The configuration is not applied. | Check the events of the VirtualServer and VirtualServerRoutes, check the logs, check the generated config. | VirtualServer or VirtualServerRoute is invalid. | | Policy Resource | The configuration is not applied. | Check the events of the Policy resource as well as the events of the VirtualServers that reference that policy, check the logs, check the generated config. | Policy is invalid. | @@ -30,38 +28,59 @@ The table below categorizes some potential problems with the Ingress Controller ## Troubleshooting Methods -Note that the commands in the next sections make the following assumptions: -* The Ingress Controller is deployed in the namespace `nginx-ingress`. -* `` is the name of one of the Ingress Controller pods. +The commands in the next sections make the following assumptions: +* That NGINX Ingress Controller is deployed in the namespace `nginx-ingress`. +* `` is the name of one of the NGINX Ingress Controller pods. + +### Checking NGINX Ingress Controller Logs -### Checking the Ingress Controller Logs +To check NGINX Ingress Controller logs, which include both information from NGINX Ingress Controller and NGINX's access and error logs, run the following command: -To check the Ingress Controller logs -- both of the Ingress Controller software and the NGINX access and error logs -- run: +```shell +kubectl logs -n nginx-ingress ``` -`kubectl logs -n nginx-ingress` + +### Checking the Generated Config +For each Ingress/VirtualServer resource, NGINX Ingress Controller generates a corresponding NGINX configuration file in the `/etc/nginx/conf.d folder`. + + Additionally, NGINX Ingress Controller generates the main configuration file `/etc/nginx/nginx.conf`, which includes all the configurations files from `/etc/nginx/conf.d`. The configuration for a VirtualServerRoute resource is located in the configuration file of the VirtualServer that references the resource. + +You can view the content of the main configuration file by running: + +```shell +kubectl exec -n nginx-ingress -- cat /etc/nginx/nginx.conf ``` -### Enabling debuging for NGINX Ingress Controller +Similarly, you can view the content of any generated configuration file in the `/etc/nginx/conf.d` folder. -If you need to do additional troubleshooting for the NGINX Ingress Controller, there are a few additional settings for more verbose logging. +You can also print all NGINX configuration files together: -There are two settings that need to be set to enable more debug/verbose logging for the Ingress Controller. +```shell +kubectl exec -n nginx-ingress -- nginx -T +``` -1. Command Line Arguments -2. Configmap Settings +However, this command will fail if any of the configuration files is not valid. + +### Checking the Live Activity Monitoring Dashboard -This document will cover how to enable both. +The live activity monitoring dashboard shows the real-time information about NGINX Plus and the applications it is load balancing, which is helpful for troubleshooting. To access the dashboard, follow the steps from [here](/nginx-ingress-controller/logging-and-monitoring/status-page). +### Enabling debugging for NGINX Ingress Controller -Using the command line arguments can be used to increase debug log levels for both the NGINX Ingress Controller as well as NGINX itself. -When using `manifest` for deployment: +For additional NGINX Ingress Controller debugging, you can enable debug settings to get more verbose logging. -1.) Use the command line argument `- -nginx-debug` in your deployment or daemonset -2.) If you want to increase the verbosity of the Ingress Controller process, set the command line argument to `v=3` +Increasing the debug log levels for NGINX Ingress Controller will also apply to NGINX itself. - ```yaml - -v=3 - ``` +There are two settings that need to be set to enable more verbose logging for NGINX Ingress Controller: + +1. Command Line Arguments +2. Configmap Settings + +**Command Line Arguments** + +When using `manifest` for deployment, use the command line argument `-nginx-debug` in your deployment or daemonset. + +If you want to increase the verbosity of the NGINX Ingress Controller process, you can also add the `-v` parameter. Here is a small snippet of setting these command line arguments in the `args` section of a deployment: @@ -73,6 +92,7 @@ args: - -v=3 ``` +**ConfigMap Settings** You can configure `error-log-level` in the NGINX Ingress Controller `configMap`: ```yaml @@ -85,23 +105,26 @@ data: error-log-level: "debug" ``` -## When using `Helm` +**Using Helm** + +If you are using `helm`, you can adjust these two settings: -If you are using `helm`, you can look for these two settings: ``` controller.nginxDebug = true or false controller.loglevel = 1 to 3 value ``` + For example, if using a `values.yaml` file: ```yaml - ## Enables debugging for NGINX. Uses the nginx-debug binary. Requires error-log-level: debug in the ConfigMap via `controller.config.entries`. + ## Enables debugging for NGINX. Uses the nginx-debug binary. Requires error-log-level: debug in ConfigMap via `controller.config.entries`. nginxDebug: true ## The log level of the Ingress Controller. logLevel: 3 ``` -Here is a more complete `values.yaml` file when using `helm`: + +This is a more complete `values.yaml` file when using `helm`: ```yaml controller: @@ -131,14 +154,14 @@ controller: ingressClass: nginx ``` -By enabling the `nginx-debug` CLI argument and changing the `error-log-level` to `debug`, you can capture more output and debug any issues that are going on. -**NOTE**: It is recommended to only use the `nginx-debug` CLI and the `error-log-level` enabled when debugging purposes. +By enabling the `nginx-debug` CLI argument and changing the `error-log-level` to `debug`, you can capture more output to use for debugging. -## Example of debugging output for NGINX Ingress controller pod. +**NOTE**: It is recommended to only enable `nginx-debug` CLI and the `error-log-level` for debugging purposes. -Once you have debugging enabled, you can see the logs have additional entries when reviewing logs: +#### Example debug NGINX Ingress Controller Output +These logs show some of the additional entries when debugging is enabled for NGINX Ingress Controller. -```nginx +```shell I1026 15:39:03.269092 1 manager.go:301] Reloading nginx with configVersion: 1 I1026 15:39:03.269115 1 utils.go:17] executing /usr/sbin/nginx-debug -s reload -e stderr 2022/10/26 15:39:03 [notice] 19#19: signal 1 (SIGHUP) received from 42, reconfiguring @@ -174,27 +197,4 @@ I1026 15:39:03.269115 1 utils.go:17] executing /usr/sbin/nginx-debug -s re 2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362B0F0E40:400280 ``` -Once you have completed your debugging process, you can change the values back to the original values. - -Checking the Generated Config -For each Ingress/VirtualServer resource, the Ingress Controller generates a corresponding NGINX configuration file in the /etc/nginx/conf.d folder. Additionally, the Ingress Controller generates the main configuration file /etc/nginx/nginx.conf, which includes all the configurations files from /etc/nginx/conf.d. The config of a VirtualServerRoute resource is located in the configuration file of the VirtualServer that references the resource. - -You can view the content of the main configuration file by running: -``` -$ kubectl exec -n nginx-ingress -- cat /etc/nginx/nginx.conf -``` - -Similarly, you can view the content of any generated configuration file in the /etc/nginx/conf.d folder. - -You can also print all NGINX configuration files together: - -``` -`kubectl exec -n nginx-ingress -- nginx -T` -``` - -However, this command will fail if any of the configuration files is not valid. - - -### Checking the Live Activity Monitoring Dashboard - -The live activity monitoring dashboard shows the real-time information about NGINX Plus and the applications it is load balancing, which is helpful for troubleshooting. To access the dashboard, follow the steps from [here](/nginx-ingress-controller/logging-and-monitoring/status-page). +Once you have completed your debugging process, you can change the values back to the original values. \ No newline at end of file diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md index 38b27fc1db..c478a739ac 100644 --- a/docs/content/troubleshooting/troubleshoot-configmap-policy.md +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -1,34 +1,43 @@ --- title: Troubleshooting Policy Resources -description: "." +description: "This page describes how to troubleshoot NGINX Ingress Controller Policy Resources." weight: 200 doctypes: [""] toc: true --- -Checking the Events of a Policy Resource -After you create or update a Policy resource, you can use `kubectl describe` to check whether or not the Ingress Controller accepted the Policy: +## Policy Resources + +After you create or update a Policy resource, you can use `kubectl describe` to check whether or not NGINX Ingress Controller accepted the policy: + +```shell +kubectl describe pol webapp-policy -`kubectl describe pol webapp-policy` -. . . Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 11s nginx-ingress-controller Policy default/webapp-policy was added or updated -Note that in the events section, we have a Normal event with the AddedOrUpdated reason, which informs us that the policy was successfully accepted. +``` + +The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. -However, the fact that a policy was accepted doesn’t guarantee that the NGINX configuration was successfully applied. To confirm that, check the events of the VirtualServer and VirtualServerRoute resources that reference that policy. +However, the fact that a policy was accepted doesn’t guarantee that the NGINX configuration was successfully applied. -Checking the Events of the ConfigMap Resource +To verify the configuration applied, check the events of the [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/troubleshooting/troubleshoot-virtualserver) that reference the policy. + +## ConfigMap Resources After you update the ConfigMap resource, you can immediately check if the configuration was successfully applied by NGINX: -`kubectl describe configmap nginx-config -n nginx-ingress` +```shell +kubectl describe configmap nginx-config -n nginx-ingress Name: nginx-config Namespace: nginx-ingress Labels: -. . . + Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Updated 11s (x2 over 26m) nginx-ingress-controller Configuration from nginx-ingress/nginx-config was updated -Note that in the events section, we have a Normal event with the Updated reason, which informs us that the configuration was successfully applied. +``` + +Similar to *Policies*, the events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. \ No newline at end of file diff --git a/docs/content/troubleshooting/troubleshoot-ingress.md b/docs/content/troubleshooting/troubleshoot-ingress.md index 22ff574320..7dd88b8da6 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress.md +++ b/docs/content/troubleshooting/troubleshoot-ingress.md @@ -1,20 +1,23 @@ --- title: Troubleshooting Ingress Resources -description: "" +description: "This page describes how to troubleshoot NGINX Ingress Controller Policy Resources." weight: 300 doctypes: [""] toc: true --- -Checking the Events of an Ingress Resource +## Ingress Resources After you create or update an Ingress resource, you can immediately check if the NGINX configuration for that Ingress resource was successfully applied by NGINX: -`kubectl describe ing cafe-ingress` +```shell +kubectl describe ing cafe-ingress Name: cafe-ingress Namespace: default -. . . -Events: + +Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 12s nginx-ingress-controller Configuration for default/cafe-ingress was added or updated -Note that in the events section, we have a Normal event with the AddedOrUpdated reason, which informs us that the configuration was successfully applied. +``` + +The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. \ No newline at end of file diff --git a/docs/content/troubleshooting/troubleshoot-transportserver.md b/docs/content/troubleshooting/troubleshoot-transportserver.md index 8ac5baa462..0c3555e9b8 100644 --- a/docs/content/troubleshooting/troubleshoot-transportserver.md +++ b/docs/content/troubleshooting/troubleshoot-transportserver.md @@ -8,4 +8,3 @@ draft: true # Troubleshooting TransportServer Resources -test test est \ No newline at end of file diff --git a/docs/content/troubleshooting/troubleshoot-virtualserver.md b/docs/content/troubleshooting/troubleshoot-virtualserver.md index 94537af99c..c5099c75f1 100644 --- a/docs/content/troubleshooting/troubleshoot-virtualserver.md +++ b/docs/content/troubleshooting/troubleshoot-virtualserver.md @@ -4,13 +4,15 @@ description: "This page describes how to troubleshoot VirtualServer and VirtualS weight: 500 doctypes: [""] toc: true +aliases: + - /content/troubleshooting/virtualserver-virtualserverroute --- ## Inspecting VirtualServer and VirtualServerRoute Resource Events After creating or updating a VirtualServer resource, you can immediately check if the NGINX configuration for that resource was successfully by using `kubectl describe vs `: -``` +```shell kubectl describe vs cafe -# Example Output + Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -21,9 +23,9 @@ In the above example, we have a `Normal` event with the `AddedOrUpdate` reason, Checking the events of a VirtualServerRoute is similar: -``` +```shell kubectl describe vsr coffee -# Example Output + Events: Type Reason Age From Message ---- ------ ---- ---- ------- diff --git a/docs/content/troubleshooting/troubleshooting-app-protect-dos.md b/docs/content/troubleshooting/troubleshooting-app-protect-dos.md index a41f6a1d70..ab8bd9a278 100644 --- a/docs/content/troubleshooting/troubleshooting-app-protect-dos.md +++ b/docs/content/troubleshooting/troubleshooting-app-protect-dos.md @@ -1,23 +1,23 @@ --- title: Troubleshooting with NGINX App Protect DoS -description: "This document describes how to troubleshoot problems with the Ingress Controller with the App Protect DoS module enabled." -weight: 700 +description: "This document describes how to troubleshoot problems when using NGINX Ingress Controller and the App Protect DoS module." +weight: 600 doctypes: [""] toc: true +aliases: + - /content/troubleshooting/troubleshooting-with-app-protect-dos --- -This document describes how to troubleshoot problems with the NGINX Ingress Controller with the App Protect DoS module enabled. - -To troubleshoot other parts of the NGINX Ingress Controller, check [troubleshooting](/nginx-ingress-controller/troubleshooting/) section of the documentation. +To troubleshoot other parts of NGINX Ingress Controller, check the [troubleshooting]({{< relref "troubleshooting/troubleshoot-common" >}}) section of the documentation. ## Potential Problems -The table below categorizes some potential problems with the Ingress Controller when App Protect DoS module is enabled. It suggests how to troubleshoot those problems, using one or more methods from the next section. +The table below categorizes some potential problems with NGINX Ingress Controller when the App Protect DoS module is enabled. It suggests how to troubleshoot those problems, using one or more methods from the next section. {{% table %}} |Problem area | Symptom | Troubleshooting method | Common cause | | ---| ---| ---| --- | -|Start | The Ingress Controller fails to start. | Check the Ingress Controller logs. | Misconfigured DosProtectedResource, APDosLogConf or APDosPolicy. | +|Start | NGINX Ingress Controller fails to start. | Check the NGINX Ingress Controller logs. | Misconfigured DosProtectedResource, APDosLogConf or APDosPolicy. | |DosProtectedResource, APDosLogConf, APDosPolicy or Ingress Resource. | The configuration is not applied. | Check the events of the DosProtectedResource, APDosLogConf, APDosPolicy and Ingress Resource, check the Ingress Controller logs. | DosProtectedResource, APDosLogConf or APDosPolicy is invalid. | {{% /table %}} @@ -25,53 +25,59 @@ The table below categorizes some potential problems with the Ingress Controller ### Checking NGINX Ingress Controller and App Protect DoS logs -App Protect DoS logs are part of the NGINX Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs](/nginx-ingress-controller/troubleshooting/#checking-the-ingress-controller-logs) of the Troubleshooting guide. +App Protect DoS logs are part of the NGINX Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs]({{< relref "troubleshooting/troubleshoot-common#checking-nginx-ingress-controller-logs" >}}s) of the Troubleshooting guide. -For App Protect DoS specific logs, look for messages starting with `APP_PROTECT_DOS`, for example: -``` +For App Protect DoS specific logs, look for messages starting with `APP_PROTECT_DOS`, such as: + +```shell 2021/06/14 08:17:50 [notice] 242#242: APP_PROTECT_DOS { "event": "shared_memory_connected", "worker_pid": 242, "mode": "operational", "mode_changed": true } ``` -### Check events of an Ingress Resource +### Checking Ingress Resource Events -Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-common#checking-the-events-of-an-ingress-resource" >}}). +Follow the steps of [Troubleshooting Ingress Resources]({{< relref "troubleshooting/troubleshoot-ingress" >}}). -### Check events of a VirtualServer Resource +### Checking VirtualServer Resource Events -Follow the steps of [Checking the Events of a VirtualServer Resource]({{< relref "troubleshooting/troubleshoot-common#checking-the-events-of-a-virtualserver-and-virtualserverroute-resources" >}}). +Follow the steps of [Troubleshooting VirtualServer Resources]({{< relref "troubleshooting/troubleshoot-virtualserver" >}}). -### Check events of DosProtectedResource +### Checking for DoSProtectedResource Events After you create or update an DosProtectedResource, you can immediately check if the NGINX configuration was successfully applied by NGINX: -``` -$ kubectl describe dosprotectedresource dos-protected + +```shell +kubectl describe dosprotectedresource dos-protected Name: dos-protected Namespace: default -. . . + Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 2s nginx-ingress-controller Configuration for default/dos-protected was added or updated ``` + Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the configuration was successfully applied. If the DosProtectedResource refers to a missing resource, you should see a message like the following: -``` + +```shell Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning Rejected 8s nginx-ingress-controller dos protected refers (default/dospolicy) to an invalid DosPolicy: DosPolicy default/dospolicy not found ``` + This can be fixed by adding the missing resource. -### Check events of APDosLogConf +### Checking for APDosLogConf Events After you create or update an APDosLogConf, you can immediately check if the NGINX configuration was successfully applied by NGINX: -``` -$ kubectl describe apdoslogconf logconf + +```shell +kubectl describe apdoslogconf logconf Name: logconf Namespace: default -. . . + Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -82,8 +88,9 @@ Note that in the events section, we have a `Normal` event with the `AddedOrUpdat ### Check events of APDosPolicy After you create or update an APDosPolicy, you can immediately check if the NGINX configuration was successfully applied by NGINX: -``` -$ kubectl describe apdospolicy dospolicy + +```shell +kubectl describe apdospolicy dospolicy Name: dospolicy Namespace: default . . . @@ -92,7 +99,8 @@ Events: ---- ------ ---- ---- ------- Normal AddedOrUpdated 2m25s nginx-ingress-controller AppProtectDosPolicy default/dospolicy was added or updated ``` -Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the configuration was successfully applied. + +The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. ## Run App Protect DoS in Debug log Mode diff --git a/docs/content/troubleshooting/troubleshooting-app-protect-waf.md b/docs/content/troubleshooting/troubleshooting-app-protect-waf.md index ee51b477b7..5cec4f6480 100644 --- a/docs/content/troubleshooting/troubleshooting-app-protect-waf.md +++ b/docs/content/troubleshooting/troubleshooting-app-protect-waf.md @@ -1,16 +1,18 @@ --- title: Troubleshooting with NGINX App Protect WAF -description: "This document describes how to troubleshoot problems when using NGINX Ingress Controller with the NGINX App Protect WAF module enabled." -weight: 800 +description: "This document describes how to troubleshoot problems when using NGINX Ingress Controller and the NGINX App Protect WAF module." +weight: 700 doctypes: [""] toc: true +aliases: + - /content/troubleshooting/troubleshooting-with-app-protect --- -This document describes how to troubleshoot problems with the Ingress Controller with the [App Protect](/nginx-app-protect/) module enabled. +This document describes how to troubleshoot problems with NGINX Ingress Controller with the [App Protect](/nginx-app-protect/) module enabled. -For general troubleshooting of the Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-common." >}}) documentation. +For general troubleshooting of NGINX Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-common" >}}) documentation. -{{< see-also >}}You can find more troubleshooting tips in the NGINX App Protect WAF [troubleshooting guide](/nginx-app-protect/troubleshooting/) {{< /see-also >}}. +{{< see-also >}} You can find more troubleshooting tips in the NGINX App Protect WAF [troubleshooting guide](/nginx-app-protect/troubleshooting/) {{< /see-also >}}. ## Potential Problems @@ -26,9 +28,9 @@ The table below categorizes some potential problems with the Ingress Controller ## Troubleshooting Methods -### Check the Ingress Controller and App Protect logs +### Check NGINX Ingress Controller and App Protect logs -App Protect logs are part of the Ingress Controller logs when the module is enabled. To check the Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs]({{< relref "troubleshooting/troubleshoot-common#checking-the-ingress-controller-logs" >}}) of the Troubleshooting guide. +App Protect logs are part of NGINX Ingress Controller logs when the module is enabled. To check NGINX Ingress Controller logs, follow the steps of [Checking the Ingress Controller Logs]({{< relref "troubleshooting/troubleshoot-common#checking-the-ingress-controller-logs" >}}) of the Troubleshooting guide. For App Protect specific logs, look for messages starting with `APP_PROTECT`, for example: ``` @@ -37,16 +39,17 @@ For App Protect specific logs, look for messages starting with `APP_PROTECT`, fo ### Check events of an Ingress Resource -Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-common#checking-the-events-of-an-ingress-resource" >}}). +Follow the steps of [Checking the Events of an Ingress Resource]({{< relref "troubleshooting/troubleshoot-ingress" >}}). ### Check events of APLogConf After you create or update an APLogConf, you can immediately check if the NGINX configuration was successfully applied by NGINX: -``` -$ kubectl describe aplogconf logconf + +```shell +kubectl describe aplogconf logconf Name: logconf Namespace: default -. . . + Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -57,25 +60,26 @@ Note that in the events section, we have a `Normal` event with the `AddedOrUpdat ### Check events of APPolicy After you create or update an APPolicy, you can immediately check if the NGINX configuration was successfully applied by NGINX: -``` -$ kubectl describe appolicy dataguard-alarm + +```shell +kubectl describe appolicy dataguard-alarm Name: dataguard-alarm Namespace: default -. . . + Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 2m25s nginx-ingress-controller AppProtectPolicy default/dataguard-alarm was added or updated ``` -Note that in the events section, we have a `Normal` event with the `AddedOrUpdated` reason, which informs us that the configuration was successfully applied. +The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. -### Replace the policy +### Replace the Policy NOTE: This method only applies if using [external references](/nginx-app-protect/configuration/#external-references) -If items on the external reference change but the spec of the APPolicy remains unchanged (even when re-applying the policy), kubernetes will not detect the update. +If items on the external reference change but the spec of the APPolicy remains unchanged (even when re-applying the policy), Kubernetes will not detect the update. In this case you can force-replace the resource. This will remove the resource and add it again, triggering a reload. For example: -``` +```shell kubectl replace appolicy -f your-policy-manifest.yaml --force ``` @@ -84,24 +88,25 @@ kubectl replace appolicy -f your-policy-manifest.yaml --force NOTE: This method only applies if you're using [external references](/nginx-app-protect/configuration/#external-references) in NGINX App Protect policies. To check what servers host the external references of a policy: -``` -kubectl get appolicy mypolicy -o jsonpath='{.items[*].spec.policy.*.link}' | tr ' ' '\n' +```shell +kubectl get appolicy mypolicy -o jsonpath='{.items[*].spec.policy.*.link}' | tr ' ' '\n' http://192.168.100.100/resources/headersettings.txt ``` You can check the total time a http request takes, in multiple ways eg. using curl: -``` + +```shell curl -w '%{time_total}' http://192.168.100.100/resources/headersettings.txt ``` ## Run App Protect in Debug Mode -When you set the Ingress Controller to use debug mode, the setting also applies to the App Protect WAF module. See [Running NGINX in the Debug Mode]({{< relref "troubleshooting/troubleshoot-common.md#running-nginx-in-the-debug-mode" >}}) for instructions. +When you set NGINX Ingress Controller to use debug mode, the setting also applies to the App Protect WAF module. See [Running NGINX in the Debug Mode]({{< relref "troubleshooting/troubleshoot-common.md#running-nginx-in-the-debug-mode" >}}) for instructions. ## Known Issues -When using the Ingress Controller with the App Protect WAF module, the following issues have been reported. The occurrence of these issues is commonly related to a higher number of Ingress Resources with App Protect being enabled in a cluster. +When using NGINX Ingress Controller with the App Protect WAF module, the following issues have been reported. The occurrence of these issues is commonly related to a higher number of Ingress Resources with App Protect being enabled in a cluster. When you make a change that requires NGINX to apply a new configuration, the Ingress Controller reloads NGINX automatically. Without the App Protect WAF module enabled, usual reload times are around 150ms. If App Protect WAF module is enabled and is being used by any number of Ingress Resources, these reloads might take a few seconds instead. @@ -113,15 +118,15 @@ In order to reduce these inconsistencies, we advise that you do not apply change ### NGINX Fails to Start or Reload -The first time the Ingress Controller starts, or whenever there is a change that requires reloading NGINX, the Ingress Controller will verify if the reload was successful. The timeout for this verification is normally 4 seconds. When App Protect is enabled, this timeout is 20 seconds. +The first time NGINX Ingress Controller starts, or whenever there is a change that requires reloading NGINX, NGINX Ingress Controller will verify if the reload was successful. The timeout for this verification is normally 4 seconds. When App Protect is enabled, this timeout increases to 20 seconds. -This timeout should be more than enough to verify configurations. However, when numerous Ingress Resources with App Protect enabled are handled by the Ingress Controller at the same time, you may find that you need to extend the timeout further. Examples of when this might be necessary include: +This timeout should be more than enough to verify configurations. However, when numerous Ingress resources with App Protect enabled are handled by NGINX Ingress Controller at the same time, you may find that you need to extend the timeout further. Examples of when this might be necessary include: - You need to apply a large amount of Ingress Resources at once. -- You are running the Ingress Controller for the first time in a cluster where the Ingress Resources with App Protect enabled are already present. +- You are running NGINX Ingress Controller for the first time in a cluster where the Ingress resources with App Protect enabled are already present. You can increase this timeout by setting the `nginx-reload-timeout` [cli-argument]({{< relref "configuration/global-configuration/command-line-arguments.md#cmdoption-nginx-reload-timeout" >}}). When using the User Defined Signature feature, an update to an `APUserSig` requires more reload time from NGINX Plus compared with the other AppProtect resources. As a consequence, we recommend increasing the `nginx-reload-timeout` to 30 seconds if you're planning to use this feature. -If you are using external references in your Nginx App Protect policies, verify if the servers hosting the referenced resources are available and that their response time is as short as possible (see the Check the Availability of APPolicy External References section). If the references are not available during the Ingress Controller startup, the pod will fail to start. In case the resources are not available during a reload, the reload will fail, and NGINX Plus will use the previous correct configuration. +If you are using external references in your NGINX App Protect policies, verify if the servers hosting the referenced resources are available and that their response time is as short as possible (see the Check the Availability of APPolicy External References section). If the references are not available during NGINX Ingress Controller startup, the pod will fail to start. In case the resources are not available during a reload, the reload will fail, and NGINX Plus will use the previous correct configuration. From 3da7a53e5d7f6c7dc5dbf4698476189ef45d1dca Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 26 Jun 2023 16:31:56 +0000 Subject: [PATCH 24/26] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/troubleshooting/troubleshoot-common.md | 8 ++++---- .../troubleshooting/troubleshoot-configmap-policy.md | 4 ++-- docs/content/troubleshooting/troubleshoot-ingress.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-common.md b/docs/content/troubleshooting/troubleshoot-common.md index 368f03e5b3..a192b9fa71 100644 --- a/docs/content/troubleshooting/troubleshoot-common.md +++ b/docs/content/troubleshooting/troubleshoot-common.md @@ -40,7 +40,7 @@ To check NGINX Ingress Controller logs, which include both information from NGIN kubectl logs -n nginx-ingress ``` -### Checking the Generated Config +### Checking the Generated Config For each Ingress/VirtualServer resource, NGINX Ingress Controller generates a corresponding NGINX configuration file in the `/etc/nginx/conf.d folder`. Additionally, NGINX Ingress Controller generates the main configuration file `/etc/nginx/nginx.conf`, which includes all the configurations files from `/etc/nginx/conf.d`. The configuration for a VirtualServerRoute resource is located in the configuration file of the VirtualServer that references the resource. @@ -76,7 +76,7 @@ There are two settings that need to be set to enable more verbose logging for NG 1. Command Line Arguments 2. Configmap Settings -**Command Line Arguments** +**Command Line Arguments** When using `manifest` for deployment, use the command line argument `-nginx-debug` in your deployment or daemonset. @@ -92,7 +92,7 @@ args: - -v=3 ``` -**ConfigMap Settings** +**ConfigMap Settings** You can configure `error-log-level` in the NGINX Ingress Controller `configMap`: ```yaml @@ -197,4 +197,4 @@ I1026 15:39:03.269115 1 utils.go:17] executing /usr/sbin/nginx-debug -s re 2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362B0F0E40:400280 ``` -Once you have completed your debugging process, you can change the values back to the original values. \ No newline at end of file +Once you have completed your debugging process, you can change the values back to the original values. diff --git a/docs/content/troubleshooting/troubleshoot-configmap-policy.md b/docs/content/troubleshooting/troubleshoot-configmap-policy.md index c478a739ac..315a3fc37c 100644 --- a/docs/content/troubleshooting/troubleshoot-configmap-policy.md +++ b/docs/content/troubleshooting/troubleshoot-configmap-policy.md @@ -21,7 +21,7 @@ Events: The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. -However, the fact that a policy was accepted doesn’t guarantee that the NGINX configuration was successfully applied. +However, the fact that a policy was accepted doesn’t guarantee that the NGINX configuration was successfully applied. To verify the configuration applied, check the events of the [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/troubleshooting/troubleshoot-virtualserver) that reference the policy. @@ -40,4 +40,4 @@ Events: Normal Updated 11s (x2 over 26m) nginx-ingress-controller Configuration from nginx-ingress/nginx-config was updated ``` -Similar to *Policies*, the events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. \ No newline at end of file +Similar to *Policies*, the events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. diff --git a/docs/content/troubleshooting/troubleshoot-ingress.md b/docs/content/troubleshooting/troubleshoot-ingress.md index 7dd88b8da6..c31b473027 100644 --- a/docs/content/troubleshooting/troubleshoot-ingress.md +++ b/docs/content/troubleshooting/troubleshoot-ingress.md @@ -14,10 +14,10 @@ kubectl describe ing cafe-ingress Name: cafe-ingress Namespace: default -Events: +Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 12s nginx-ingress-controller Configuration for default/cafe-ingress was added or updated ``` -The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. \ No newline at end of file +The events section has a *Normal* event with the *AddedOrUpdated reason*, indicating the policy was successfully accepted. From c2cfbb863cd1b608dc6665e6d1de60a59c9b6b4e Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 27 Jun 2023 14:11:46 +0100 Subject: [PATCH 25/26] Remove test content from draft TransportServer document --- docs/content/troubleshooting/troubleshoot-transportserver.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/content/troubleshooting/troubleshoot-transportserver.md b/docs/content/troubleshooting/troubleshoot-transportserver.md index c7a2eab9aa..0c3555e9b8 100644 --- a/docs/content/troubleshooting/troubleshoot-transportserver.md +++ b/docs/content/troubleshooting/troubleshoot-transportserver.md @@ -8,7 +8,3 @@ draft: true # Troubleshooting TransportServer Resources -<<<<<<< HEAD -======= -test test est ->>>>>>> 8be78b8e1fae46e3cbb614d5638daa86fba1e4a5 From 850b3729fc0f656bfa014ce619d5e9a7a5f1a492 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 27 Jun 2023 13:14:32 +0000 Subject: [PATCH 26/26] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/troubleshooting/troubleshoot-transportserver.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/troubleshooting/troubleshoot-transportserver.md b/docs/content/troubleshooting/troubleshoot-transportserver.md index 0c3555e9b8..1ed7e07b1d 100644 --- a/docs/content/troubleshooting/troubleshoot-transportserver.md +++ b/docs/content/troubleshooting/troubleshoot-transportserver.md @@ -7,4 +7,3 @@ draft: true --- # Troubleshooting TransportServer Resources -