NGF: Update scaling documentation and API (#932)

Updates the NGF scaling doc for new capabilities being added in 2.1. HorizontalPodAutoscaling and updating worker connections. Also added the updated API reference guide for these changes.

Finally, added some missing conditions in the compatibility doc.

Author: sjberman

content/ngf/how-to/scaling.md

@@ -16,36 +16,64 @@ It provides guidance on how to scale each plane effectively, and when you should
 
 The data plane is the NGINX deployment that handles user traffic to backend applications. Every Gateway object created provisions its own NGINX deployment and configuration.
 
-You have two options for scaling the data plane:
+You have multiple options for scaling the data plane:
 
+- Increasing the number of [worker connections](https://nginx.org/en/docs/ngx_core_module.html#worker_connections) for an existing deployment
 - Increasing the number of replicas for an existing deployment
 - Creating a new Gateway for a new data plane
 
-#### When to increase replicas or create a new Gateway
+#### When to increase worker connections, replicas, or create a new Gateway
 
-Understanding when to increase replicas or create a new Gateway is key to managing traffic effectively.
+Understanding when to increase worker connections, replicas, or create a new Gateway is key to managing traffic effectively.
 
-Increasing data plane replicas is ideal when you need to handle more traffic without changing the configuration.
+Increasing worker connections or replicas is ideal when you need to handle more traffic without changing the overall routing configuration. Setting the worker connections field allows a single NGINX data plane instance to handle more connections without needing to scale the replicas. However, scaling the replicas can be beneficial to reduce single points of failure.
 
-For example, if you're routing traffic to `api.example.com` and notice an increase in load, you can scale the replicas from 1 to 5 to better distribute the traffic and reduce latency.
+Scaling replicas can be done manually or automatically using a [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA).
 
-All replicas will share the same configuration from the Gateway used to set up the data plane, simplifying configuration management.
+To update worker connections (default: 1024), replicas, or enable autoscaling, you can edit the `NginxProxy` resource:
 
-There are two ways to modify the number of replicas for an NGINX deployment:
+```shell
+kubectl edit nginxproxies.gateway.nginx.org ngf-proxy-config -n nginx-gateway
+```
 
-First, at the time of installation you can modify the field `nginx.replicas` in the `values.yaml` or add the `--set nginx.replicas=` flag to the `helm install` command:
+{{< call-out "note" >}}
 
-```shell
-helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginx.replicas=5
+The NginxProxy resource in this example lives in the control plane namespace (default: `nginx-gateway`) and applies to the GatewayClass, but you can also define one per Gateway. See the [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}) document for more information.
+
+{{< /call-out >}}
+
+- Worker connections is set using the `workerConnections` field:
+
+```yaml
+spec:
+  workerConnections: 4096
 ```
 
-Secondly, you can update the `NginxProxy` resource while NGINX is running to modify the `kubernetes.deployment.replicas` field and scale the data plane deployment dynamically:
+- Replicas are set using the `kubernetes.deployment.replicas` field:
 
-```shell
-kubectl edit nginxproxies.gateway.nginx.org ngf-proxy-config -n nginx-gateway
+```yaml
+spec:
+  kubernetes:
+    deployment:
+      replicas: 3
+```
+
+- Autoscaling can be enabled using the `kubernetes.deployment.autoscaling` field. The default `replicas` value will be used until the Horizontal Pod Autoscaler is running.
+
+```yaml
+spec:
+  kubernetes:
+    deployment:
+      autoscaling:
+        enable: true
+        maxReplicas: 10
 ```
 
-The alternate way to scale the data plane is by creating a new Gateway.  This is beneficial when you need distinct configurations, isolation, or separate policies.
+See the `NginxProxy` section of the [API reference]({{< ref "/ngf/reference/api.md" >}}) for the full specification.
+
+All of these fields are also available at installation time by setting them in the [helm values](https://github.com/nginx/nginx-gateway-fabric/blob/main/charts/nginx-gateway-fabric/values.yaml).
+
+An alternate way to scale the data plane is by creating a new Gateway.  This is beneficial when you need distinct configurations, isolation, or separate policies. 
 
 For example, if you're routing traffic to a new domain `admin.example.com` and require a different TLS certificate, stricter rate limits, or separate authentication policies, creating a new Gateway could be a good approach.
 
@@ -60,7 +88,9 @@ Scaling the control plane can be beneficial in the following scenarios:
 1. _Higher availability_ - When a control plane pod crashes, runs out of memory, or goes down during an upgrade, it can interrupt configuration delivery. By scaling to multiple replicas, another pod can quickly step in and take over, keeping things running smoothly with minimal downtime.
 1. _Faster configuration distribution_ - As the number of connected NGINX instances grows, a single control plane pod may become a bottleneck in handling connections or streaming configuration updates. Scaling the control plane improves concurrency and responsiveness when delivering configuration over gRPC.
 
-To scale the control plane, use the `kubectl scale` command on the control plane deployment to increase or decrease the number of replicas. For example, the following command scales the control plane deployment to 3 replicas:
+To automatically scale the control plane, you can create a [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA) in the control plane namespace (default: `nginx-gateway`). At installation time, the [NGINX Gateway Fabric helm chart](https://github.com/nginx/nginx-gateway-fabric/blob/main/charts/nginx-gateway-fabric/values.yaml) allows you to set the HPA configuration in the `nginxGateway.autoscaling` section, which will provision an HPA for you. If NGINX Gateway Fabric is already running, then you can manually define the HPA and deploy it.
+
+To manually scale the control plane, use the `kubectl scale` command on the control plane deployment to increase or decrease the number of replicas. For example, the following command scales the control plane deployment to 3 replicas:
 
   ```shell
   kubectl scale deployment -n nginx-gateway ngf-nginx-gateway-fabric --replicas 3

content/ngf/overview/gateway-api-compatibility.md

@@ -136,9 +136,11 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
       - `ResolvedRefs/True/ResolvedRefs`
       - `ResolvedRefs/False/InvalidCertificateRef`
       - `ResolvedRefs/False/InvalidRouteKinds`
+      - `ResolvedRefs/False/RefNotPermitted`
       - `Conflicted/True/ProtocolConflict`
       - `Conflicted/True/HostnameConflict`
       - `Conflicted/False/NoConflicts`
+      - `OverlappingTLSConfig/True/OverlappingHostnames`
 
 ### HTTPRoute