Add how-to for ClientSettingsPolicy (nginx#2071)

Problem: As a user, I want a how-to guide to explain how to use the ClientSettingsPolicy API. Solution: Add a how-to guide that explains how to use ClientSettingsPolicy to configure client max body size.
lucacome · Jun 7, 2024 · 127c0ed · 127c0ed
1 parent 7c9bf23
commit 127c0ed
Show file tree

Hide file tree

Showing 12 changed files with 335 additions and 67 deletions.
diff --git a/examples/client-settings-policy/README.md b/examples/client-settings-policy/README.md
@@ -1,3 +1,3 @@
 # Client Settings Policy
 
-This directory contains YAML files of ClientSettingsPolicies.
+This directory contains the YAML files used in the [ClientSettingsPolicy](https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/client-settings/) guide.
diff --git a/examples/client-settings-policy/cafe.yaml → examples/client-settings-policy/app.yaml b/examples/client-settings-policy/cafe.yaml → examples/client-settings-policy/app.yaml
diff --git a/examples/client-settings-policy/csp-grpcroute.yaml b/examples/client-settings-policy/csp-grpcroute.yaml
diff --git a/examples/client-settings-policy/csp-httproutes.yaml b/examples/client-settings-policy/csp-httproutes.yaml
diff --git a/...s/client-settings-policy/csp-gateway.yaml → ...tings-policy/gateway-client-settings.yaml b/...s/client-settings-policy/csp-gateway.yaml → ...tings-policy/gateway-client-settings.yaml
@@ -1,19 +1,11 @@
 apiVersion: gateway.nginx.org/v1alpha1
 kind: ClientSettingsPolicy
 metadata:
-  name: gw
-  namespace: default
+  name: gateway-client-settings
 spec:
   targetRef:
     group: gateway.networking.k8s.io
     kind: Gateway
     name: gateway
   body:
-    maxSize: 10m
-    timeout: 30s
-  keepAlive:
-    requests: 100
-    time: 5s
-    timeout:
-      server: 2s
-      header: 1s
+    maxSize: "50" # sizes without a unit are bytes.
diff --git a/examples/client-settings-policy/gateway.yaml b/examples/client-settings-policy/gateway.yaml
@@ -9,7 +9,3 @@ spec:
     port: 80
     protocol: HTTP
     hostname: "*.example.com"
-  - name: http2
-    port: 8080
-    protocol: HTTP
-    hostname: "*.example.org"
diff --git a/examples/client-settings-policy/grpc-client-settings.yaml b/examples/client-settings-policy/grpc-client-settings.yaml
@@ -0,0 +1,11 @@
+apiVersion: gateway.nginx.org/v1alpha1
+kind: ClientSettingsPolicy
+metadata:
+  name: grpc-client-settings
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: GRPCRoute
+    name: my-grpc-route
+  body:
+    maxSize: "75" # sizes without a unit are bytes.
diff --git a/...s/client-settings-policy/cafe-routes.yaml → ...es/client-settings-policy/httproutes.yaml b/...s/client-settings-policy/cafe-routes.yaml → ...es/client-settings-policy/httproutes.yaml
diff --git a/examples/client-settings-policy/tea-client-settings.yaml b/examples/client-settings-policy/tea-client-settings.yaml
@@ -0,0 +1,11 @@
+apiVersion: gateway.nginx.org/v1alpha1
+kind: ClientSettingsPolicy
+metadata:
+  name: tea-client-settings
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: tea
+  body:
+    maxSize: "75" # sizes without a unit are bytes.
diff --git a/site/content/how-to/monitoring/tracing.md b/site/content/how-to/monitoring/tracing.md
@@ -13,6 +13,10 @@ NGINX Gateway Fabric supports tracing using [OpenTelemetry](https://opentelemetr
 
 This guide explains how to enable tracing on HTTPRoutes using NGINX Gateway Fabric. It uses the OpenTelemetry Collector and Jaeger to process and collect the traces.
 
+{{< important >}}
+Tracing cannot be enabled for [HTTPRoute matches](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteMatch) with `headers`, `params`, or `method` matchers defined. It will be added in a future release.
+{{< /important >}}
+
 ## Install the Collectors
 
 The first step is to install the collectors. NGINX Gateway Fabric will be configured to export to the OpenTelemetry Collector, which is configured to export to Jaeger. This model allows the visualization collector (Jaeger) to be swapped with something else, or to add more collectors without needing to reconfigure NGINX Gateway Fabric. It is also possible to configure NGINX Gateway Fabric to export directly to Jaeger.

diff --git a/site/content/how-to/monitoring/troubleshooting.md b/site/content/how-to/monitoring/troubleshooting.md
@@ -109,3 +109,31 @@ If using NGINX Gateway Fabric with NGINX Plus as the data plane, you will see th
 #### Resolution
 
 To resolve this issue, enable Usage Reporting by following the [Usage Reporting]({{< relref "installation/usage-reporting.md" >}}) guide.
+
+### 413 Request Entity Too Large
+
+#### Description
+
+If you receive the following error:
+
+```text
+<html>
+<head><title>413 Request Entity Too Large</title></head>
+<body>
+<center><h1>413 Request Entity Too Large</h1></center>
+<hr><center>nginx/1.25.5</center>
+</body>
+</html>
+```
+
+Or view the following error message in the NGINX logs:
+
+```text
+2024/05/30 21:48:22 [error] 138#138: *43 client intended to send too large body: 112 bytes, client: 127.0.0.1, server: cafe.example.com, request: "POST /coffee HTTP/1.1", host: "cafe.example.com:8080"
+```
+
+The request body exceeds the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size).
+
+#### Resolution
+
+You can configure the `client_max_body_size` using the `ClientSettingsPolicy` API. Read the [Client Settings Policy]({{< relref "how-to/traffic-management/client-settings.md" >}}) documentation for more information.