Documentation for jwt claim based tiered rate limit (#7419)

* update docs and crd descriptions

Signed-off-by: Haywood Shannon <[email protected]>

* update descriptons of fields.

Signed-off-by: Haywood Shannon <[email protected]>

* fix rebase error

Signed-off-by: Haywood Shannon <[email protected]>

* update crd

Signed-off-by: Haywood Shannon <[email protected]>

---------

Signed-off-by: Haywood Shannon <[email protected]>
Co-authored-by: Alan Dooley <[email protected]>
Co-authored-by: Paul Abel <[email protected]>

Author: 3 people

config/crd/bases/k8s.nginx.org_policies.yaml

@@ -184,15 +184,21 @@ spec:
                       limit policy.
                     properties:
                       default:
+                        description: sets the rate limit in this policy to be the
+                          default if no conditions are met. In a group of policies
+                          with the same JWT condition, only one policy can be the
+                          default.
                         type: boolean
                       jwt:
-                        description: JWTCondition defines a condition for a rate limit
-                          by JWT claim.
+                        description: defines a JWT condition to rate limit against.
                         properties:
                           claim:
+                            description: the JWT claim to be rate limit by. Nested
+                              claims should be separated by "."
                             pattern: ^([^$\s"'])*$
                             type: string
                           match:
+                            description: the value of the claim to match against.
                             pattern: ^([^$\s."'])*$
                             type: string
                         required:

deploy/crds.yaml

@@ -346,15 +346,21 @@ spec:
                       limit policy.
                     properties:
                       default:
+                        description: sets the rate limit in this policy to be the
+                          default if no conditions are met.   In a group of policies
+                          with the same JWT condition, only one policy can be the
+                          default.
                         type: boolean
                       jwt:
-                        description: JWTCondition defines a condition for a rate limit
-                          by JWT claim.
+                        description: defines a JWT condition to rate limit against.
                         properties:
                           claim:
+                            description: the JWT claim to be rate limit by. Nested
+                              claims should be separated by "."
                             pattern: ^([^$\s"'])*$
                             type: string
                           match:
+                            description: the value of the claim to match against.
                             pattern: ^([^$\s."'])*$
                             type: string
                         required:

examples/custom-resources/rate-limit-tiered-jwt-claim/README.md

@@ -1,4 +1,4 @@
-# Rate Limit JWT claim
+# Tiered Rate Limits with JWT Claim
 
 In this example, we deploy a web application, configure load balancing for it via a VirtualServer, and apply two rate
 limit Policies, grouped in a tier, using a JWT claim `sub` as the key to the rate limit and using another JWT claim

pkg/apis/configuration/v1/types.go

@@ -616,18 +616,22 @@ type RateLimit struct {
 
 // RateLimitCondition defines a condition for a rate limit policy.
 type RateLimitCondition struct {
+	// defines a JWT condition to rate limit against.
 	JWT *JWTCondition `json:"jwt"`
 	// +kubebuilder:validation:Optional
+	// sets the rate limit in this policy to be the default if no conditions are met. In a group of policies with the same JWT condition, only one policy can be the default.
 	Default bool `json:"default"`
 }
 
 // JWTCondition defines a condition for a rate limit by JWT claim.
 type JWTCondition struct {
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:Pattern=`^([^$\s"'])*$`
+	// the JWT claim to be rate limit by. Nested claims should be separated by "."
 	Claim string `json:"claim"`
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:Pattern=`^([^$\s."'])*$`
+	// the value of the claim to match against.
 	Match string `json:"match"`
 }
 

site/content/configuration/policy-resource.md

@@ -132,6 +132,7 @@ The feature is implemented using the NGINX [ngx_http_limit_req_module](https://n
 |``logLevel`` | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are ``info``, ``notice``, ``warn`` or ``error``. Default is ``error``. | ``string`` | No |
 |``rejectCode`` | Sets the status code to return in response to rejected requests. Must fall into the range ``400..599``. Default is ``503``. | ``int`` | No |
 |``scale`` | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. **This will not work properly if requests from a client are not evenly distributed across all ingress pods** (Such as with sticky sessions, long lived TCP Connections with many requests, and so forth). In such cases using [zone-sync]({{< ref "/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) instead would give better results. | ``bool`` | No |
+|``condition`` | Add a condition to a rate-limit policy. | [ratelimit.condition](#ratelimitcondition) | No |
 {{% /table %}}
 
 {{< note >}}
@@ -152,6 +153,59 @@ policies:
 
 When you reference more than one rate limit policy, NGINX Ingress Controller will configure NGINX to use all referenced rate limits. When you define multiple policies, each additional policy inherits the `dryRun`, `logLevel`, and `rejectCode` parameters from the first policy referenced (`rate-limit-policy-one`, in the example above).
 
+### RateLimit.Condition
+
+RateLimit.Condition defines a condition for a rate limit policy. For example:
+
+```yaml
+condition:
+  jwt:
+    claim: user_details.level
+    match: premium
+  default: true
+```
+
+{{% table %}}
+|Field | Description | Type | Required |
+| ---| ---| ---| --- |
+|``jwt`` | defines a JWT condition to rate limit against. | [ratelimit.condition.jwt](#ratelimitconditionjwt) | No |
+|``default`` | sets the rate limit in this policy to be the default if no conditions are met. In a group of policies with the same JWT condition, only one policy can be the default. | ``bool`` | No |
+{{% /table %}}
+
+The rate limit policy with condition is designed to be used in combination with one or more rate limit policies. For example, multiple rate limit policies with [RateLimit.Condition.JWT](#ratelimitconditionjwt) can be used to apply different tiers of rate limit based on the value of a JWT claim. For a practical example of tiered rate limiting by the value of a JWT claim, see the example in our [GitHub repository](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/rate-limit-tiered-jwt-claim/README.md).
+
+### RateLimit.Condition.JWT
+{{< note >}}
+
+This feature is only available with NGINX Plus.
+
+{{< /note >}}
+
+RateLimit.Condition.JWT defines a condition for a rate limit by JWT claim. For example, here we define a condition for a rate limit policy that only applies to requests with a JWT claim `user_details.level` with a value `premium`:
+
+```yaml
+jwt:
+  claim: user_details.level
+  match: premium
+```
+
+The rate limit policy will only apply to requests that contain a JWT with the specified claim and value. For example, the following JWT payload will match the JWT condition:
+
+```json
+{
+  "user_details": {
+    "level": "premium"
+  }, 
+  "sub": "client1"
+}
+```
+
+{{% table %}}
+|Field | Description | Type | Required |
+| ---| ---| ---| --- |
+|``claim`` | Claim is the JWT claim to be rate limit by. Nested claims should be separated by ".". | ``string`` | Yes |
+|``match`` | the value of the claim to match against. | ``string`` | Yes |
+{{% /table %}}
 
 ### APIKey