From 2ca026e3f344cb4929f7abe6022dffdb14e684df Mon Sep 17 00:00:00 2001
From: Saylor Berman <s.berman@f5.com>
Date: Mon, 18 Sep 2023 11:24:32 -0600
Subject: [PATCH] Allow for configurable securityContext (#1063)

Problem: In at least one environment it has been found that the control plane does not have permissions to reload nginx, requiring allowPrivilegeEscalation to be true.

Solution: Keep the same default, but allow this field to be configurable. Added a troubleshooting guide for this issue.
---
 README.md                                   |  4 ++++
 deploy/helm-chart/templates/deployment.yaml |  2 +-
 deploy/helm-chart/values.yaml               |  4 ++++
 docs/README.md                              |  1 +
 docs/troubleshooting.md                     | 11 +++++++++++
 5 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 docs/troubleshooting.md

diff --git a/README.md b/README.md
index ea18a1f0ba..35151724ae 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,10 @@ can run the following command:
 docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
 ```
 
+## Troubleshooting
+
+For troubleshooting help, see the [Troubleshooting](/docs/troubleshooting.md) document.
+
 ## Contacts
 
 We’d like to hear your feedback! If you experience issues with our Gateway Controller, please [open a bug][bug] in
diff --git a/deploy/helm-chart/templates/deployment.yaml b/deploy/helm-chart/templates/deployment.yaml
index 3e062d903f..6bd2536008 100644
--- a/deploy/helm-chart/templates/deployment.yaml
+++ b/deploy/helm-chart/templates/deployment.yaml
@@ -72,7 +72,7 @@ spec:
           periodSeconds: 1
         {{- end }}
         securityContext:
-          allowPrivilegeEscalation: false
+          allowPrivilegeEscalation: {{ .Values.nginxGateway.securityContext.allowPrivilegeEscalation }}
           capabilities:
             add:
             - KILL
diff --git a/deploy/helm-chart/values.yaml b/deploy/helm-chart/values.yaml
index 7d5134d124..613c6d27f4 100644
--- a/deploy/helm-chart/values.yaml
+++ b/deploy/helm-chart/values.yaml
@@ -30,6 +30,10 @@ nginxGateway:
     tag: edge
     pullPolicy: Always
 
+  securityContext:
+    ## Some environments may need this set to true in order for the control plane to successfully reload NGINX.
+    allowPrivilegeEscalation: false
+
 nginx:
   ## The NGINX image to use
   image:
diff --git a/docs/README.md b/docs/README.md
index 117b03b833..f1903ffaaf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,7 @@ yourself.
 - [CLI Help](cli-help.md): Describes the commands available in the `gateway` binary of `nginx-kubernetes-gateway`
 container.
 - [Monitoring](monitoring.md): Information on monitoring NGINX Kubernetes Gateway using Prometheus metrics.
+- [Troubleshooting](troubleshooting.md): Troubleshooting guide for common or known issues.
 
 ### Directories
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000000..4c97cd4ec3
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,11 @@
+# Troubleshooting
+
+This document contains common or known issues and how to troubleshoot them.
+
+## failed to reload NGINX: failed to send the HUP signal to NGINX main: operation not permitted
+
+Depending on your environment's configuration, the control plane may not have the proper permissions to reload
+NGINX. If NGINX configuration is not applied and you see the above error in the `nginx-gateway` logs, you will need
+to set `allowPrivilegeEscalation` to `true`. If using Helm, you can set the
+`nginxGateway.securityContext.allowPrivilegeEscalation` value.
+If using the manifests directly, you can update this field under the `nginx-gateway` container's `securityContext`.