Update NGF docs to use kubectl server side apply (#787)

Switch to using kubectl server side apply for NGF CRDs and add a troubleshooting section addressing the problem and solution.

Problem: We were running into issues using the standard kubectl client side apply on our growing CRDs

Solution: Switched to using kubectl server side apply.

Co-authored-by: Alan Dooley <[email protected]>

Author: 2 people

content/ngf/install/manifests.md

@@ -54,13 +54,13 @@ Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps.
 #### Stable release
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
 ```
 
 #### Edge version
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/crds.yaml
+kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/crds.yaml
 ```
 
 ### Deploy NGINX Gateway Fabric

content/ngf/install/upgrade-version.md

@@ -53,7 +53,7 @@ kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gate
 Run the following command to upgrade the CRDs:
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
 ```
 
 {{< note >}}
@@ -157,7 +157,7 @@ For customization options during the Helm installation process, view the [Instal
 Apply the new CRDs with the following command:
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
 ```
 
 Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace with the following command:

content/ngf/troubleshooting.md

@@ -512,6 +512,21 @@ It indicates that `proxy_protocol` is enabled for the gateway listeners, but the
 
 - Send valid proxy information with requests being handled by your application.
 
+#### Custom Resource Definition is invalid due to being too large 
+
+If you apply the NGINX Gateway Fabric CRDs and see the following error:
+
+```text
+The CustomResourceDefinition "nginxproxies.gateway.nginx.org" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes
+```
+
+This is a known issue with Kubernetes, more specifically the client-side-apply annotation limit with kubectl, and our recommended workaround 
+is to use kubectl's server-side apply when installing the NGINX Gateway Fabric CRDs. To do this, you can use the `--server-side` flag when applying the CRDs:
+
+```shell
+kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+```
+
 ### See also
 
 You can view the [Kubernetes Troubleshooting Guide](https://kubernetes.io/docs/tasks/debug/debug-application/) for more debugging guidance.