From 1bef1aa7ae6b48da2bfd9279176d6e3ef85cd074 Mon Sep 17 00:00:00 2001 From: tedaveryredhat Date: Mon, 8 Jun 2026 13:35:43 -0400 Subject: [PATCH] OSDOCS-20040:Document PlanPolicy feature --- _topic_maps/_topic_map.yml | 2 + deployment/rhcl-planpolicy.adoc | 40 ++++++++ modules/con-rhcl-planpolicy-overview.adoc | 21 +++++ modules/proc-rhcl-authpolicy-verify.adoc | 60 ++++++++++++ ...configuring-authentication-planpolicy.adoc | 60 ++++++++++++ modules/proc-rhcl-create-secrets.adoc | 67 ++++++++++++++ ...cl-deploying-planpolicy-rate-limiting.adoc | 91 +++++++++++++++++++ ...c-rhcl-planpolicy-ratelimiting-verify.adoc | 69 ++++++++++++++ modules/proc-rhcl-planpolicy-verify.adoc | 63 +++++++++++++ modules/proc-rhcl-secrets-verify.adoc | 59 ++++++++++++ ...cl-planpolicy-custom-resources-params.adoc | 32 +++++++ ...ref-rhcl-planpolicy-known-limitations.adoc | 12 +++ modules/ref-rhcl-planpolicy-plan-limits.adoc | 36 ++++++++ .../ref-rhcl-planpolicy-plan-predicates.adoc | 40 ++++++++ .../ref-rhcl-planpolicy-target-gateway.adoc | 31 +++++++ .../ref-rhcl-planpolicy-targeting-routes.adoc | 53 +++++++++++ 16 files changed, 736 insertions(+) create mode 100644 deployment/rhcl-planpolicy.adoc create mode 100644 modules/con-rhcl-planpolicy-overview.adoc create mode 100644 modules/proc-rhcl-authpolicy-verify.adoc create mode 100644 modules/proc-rhcl-configuring-authentication-planpolicy.adoc create mode 100644 modules/proc-rhcl-create-secrets.adoc create mode 100644 modules/proc-rhcl-deploying-planpolicy-rate-limiting.adoc create mode 100644 modules/proc-rhcl-planpolicy-ratelimiting-verify.adoc create mode 100644 modules/proc-rhcl-planpolicy-verify.adoc create mode 100644 modules/proc-rhcl-secrets-verify.adoc create mode 100644 modules/ref-rhcl-planpolicy-custom-resources-params.adoc create mode 100644 modules/ref-rhcl-planpolicy-known-limitations.adoc create mode 100644 modules/ref-rhcl-planpolicy-plan-limits.adoc create mode 100644 modules/ref-rhcl-planpolicy-plan-predicates.adoc create mode 100644 modules/ref-rhcl-planpolicy-target-gateway.adoc create mode 100644 modules/ref-rhcl-planpolicy-targeting-routes.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 747a4cad6b64..12d9fd8ddc71 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -72,6 +72,8 @@ Topics: File: rhcl-using-x509-crypt-id-verify - Name: Using OpenID Connect authentication File: rhcl-oidc-authentication +- Name: Configure and deploy a PlanPolicy + File: rhcl-planpolicy --- Name: Registering MCP servers and creating policies Dir: mcp_gateway_config diff --git a/deployment/rhcl-planpolicy.adoc b/deployment/rhcl-planpolicy.adoc new file mode 100644 index 000000000000..4031cee7ec98 --- /dev/null +++ b/deployment/rhcl-planpolicy.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/attributes.adoc[] +[id="rhcl-planpolicy"] += Configure and deploy the PlanPolicy extension +:context: rhcl-planpolicy + +toc::[] + +[role="_abstract"] +With a `PlanPolicy` extension, you can define different service tiers, or plans, with their associated rate limits and automatically categorize authenticated users into these plans. + +include::modules/con-rhcl-planpolicy-overview.adoc[leveloffset=+1] + +include::modules/proc-rhcl-configuring-authentication-planpolicy.adoc[leveloffset=+2] + +include::modules/proc-rhcl-authpolicy-verify.adoc[leveloffset=+2] + +include::modules/proc-rhcl-create-secrets.adoc[leveloffset=+2] + +include::modules/proc-rhcl-secrets-verify.adoc[leveloffset=+2] + +include::modules/proc-rhcl-deploying-planpolicy-rate-limiting.adoc[leveloffset=+2] + +//include::modules/proc-rhcl-planpolicy-ratelimiting-verify.adoc[leveloffset=+2] + +include::modules/ref-rhcl-planpolicy-custom-resources-params.adoc[leveloffset=+1] + +include::modules/ref-rhcl-planpolicy-targeting-routes.adoc[leveloffset=+2] + +include::modules/ref-rhcl-planpolicy-target-gateway.adoc[leveloffset=+2] + +include::modules/ref-rhcl-planpolicy-plan-predicates.adoc[leveloffset=+2] + +include::modules/ref-rhcl-planpolicy-plan-limits.adoc[leveloffset=+2] + +include::modules/ref-rhcl-planpolicy-known-limitations.adoc[leveloffset=+2] + +== Additional resources + +* link:rhcl-ocp-web-console[Using the {product-title} web console] \ No newline at end of file diff --git a/modules/con-rhcl-planpolicy-overview.adoc b/modules/con-rhcl-planpolicy-overview.adoc new file mode 100644 index 000000000000..d7db8ef6beb7 --- /dev/null +++ b/modules/con-rhcl-planpolicy-overview.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-rhcl-planpolicy-overview_{context}"] += PlanPolicy + +[role="_abstract"] +You can use a `PlanPolicy` object to implement tiered service offerings where different users receive different rate limits based on their subscription plan or other attributes. + +[NOTE] +==== +The `PlanPolicy` object uses the `spec.plans.limits` parameter to enforce rate limits at the plan tier level instead of the individual subscriber level. +==== + +A `PlanPolicy` works in conjunction with `AuthPolicy` and `RateLimitPolicy` custom resources (CRs) in the following sequence: + +. An `AuthPolicy` CR authenticates a user request with stored identity metadata, including their plan information. +. The `PlanPolicy` object evaluates CEL predicate expressions against the authenticated identity to determine the user's plan tier. +. {prodname} then enforces the rate limits defined for the user-matched plan tier. \ No newline at end of file diff --git a/modules/proc-rhcl-authpolicy-verify.adoc b/modules/proc-rhcl-authpolicy-verify.adoc new file mode 100644 index 000000000000..f2a11a93e614 --- /dev/null +++ b/modules/proc-rhcl-authpolicy-verify.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-authpolicy-verify_{context}"] += Verifying the acceptance of the 'AuthPolicy' CR + +[role="_abstract"] +You can confirm the acceptance of the `AuthPolicy` custom resource (CR) by running several commands. + +.Procedure + +. Confirm that the `AuthPolicy` CR was accepted by checking its status by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get authpolicy __ -n ${KUADRANT_GATEWAY_NS} -o jsonpath='{.status.conditions}' +---- +* Replace `__` with the name of your application. +* Replace ${KUADRANT_GATEWAY_NS} with the namespace you used for this {prodname} deployment. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +AuthPolicy has been accepted +AuthPolicy has been successfully enforced +---- ++ +. Send a request using the bronze-tier API key and confirm that it succeeds by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Authorization: APIKEY __' http://${KUADRANT_GATEWAY_HOSTNAME}/toy -i +---- +* Replace `__` with the actual API key string you want to assign to each tier. +* KUADRANT_GATEWAY_HOSTNAME: Hostname of your gateway in {prodname}. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +HTTP/1.1 200 OK +---- ++ +. Send a second request using the bronze-tier key and confirm that it is rate limited by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Authorization: APIKEY __' http://${KUADRANT_GATEWAY_HOSTNAME}/toy -i +---- +* Replace `__` with the actual API key string you want to assign to each tier. +* KUADRANT_GATEWAY_HOSTNAME is the host name of your gateway in {prodname}. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +HTTP/1.1 429 Too Many Requests +---- ++ +. Confirm that the gold-tier key allows up to five requests per day before the limit is enforced. \ No newline at end of file diff --git a/modules/proc-rhcl-configuring-authentication-planpolicy.adoc b/modules/proc-rhcl-configuring-authentication-planpolicy.adoc new file mode 100644 index 000000000000..d59aec86fdcd --- /dev/null +++ b/modules/proc-rhcl-configuring-authentication-planpolicy.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-configuring-authentication-planpolicy_{context}"] += Creating an AuthPolicy with API key authentication + +[role="_abstract"] +You can configure API key authentication on a Gateway by deploying an AuthPolicy and creating per-plan API key secrets, so that {prodname} can identify which rate-limiting plan applies to each request. + +.Prerequisites + +* You installed {prodname}. +* You installed {oc-first}. +* You are logged in to your cluster. +* You created the `Gateway` object for your deployment. + +.Procedure + +. Deploy an AuthPolicy that targets the Gateway and enables API key authentication by using the following example: ++ +.Example API key AuthPolicy CR +[source,yaml,subs="+quotes"] +---- +apiVersion: kuadrant.io/v1 +kind: AuthPolicy +metadata: + name: __ + namespace: ${KUADRANT_GATEWAY_NS} +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: ${KUADRANT_GATEWAY_NAME} + rules: + authentication: + "api-key-plan": + apiKey: + selector: + matchLabels: + app: __ + allNamespaces: true + credentials: + authorizationHeader: + prefix: APIKEYapiVersion: kuadrant.io/v1 +---- +* Replace `__ ` with the name of your application. +* Replace 'KUADRANT_GATEWAY_NS' with the namespace for your gateway in {prodname}. +* Replace `KUADRANT_GATEWAY_NAME` with the name of your gateway in {prodname}. ++ +* The `spec.rules.authentication."api-key-plan".apiKey.selector.matchLabels` field value points to the API key `Secrets` objects that carry the `app: __` label. +* Setting `spec.rules.rules.authentication."api-key-plan".apiKey.selector.allNamespaces: true` allows secrets from any namespace to be matched. ++ +. Apply the policy by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f +---- \ No newline at end of file diff --git a/modules/proc-rhcl-create-secrets.adoc b/modules/proc-rhcl-create-secrets.adoc new file mode 100644 index 000000000000..67bc8354cb46 --- /dev/null +++ b/modules/proc-rhcl-create-secrets.adoc @@ -0,0 +1,67 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-create-secrets_{context}"] += Creating API key `Secret` objects + +[role="_abstract"] +You can create API key 'Secret` objects for each plan tier. + +[IMPORTANT] +==== +The following example creates API key `Secret` objects each plan tier that you want to use. The following example uses API keys to authenticate the requests. Other options, such as OpenID Connect, might be more appropriate for production use. Use the "least-access" approach that is best for your use case. +==== + +.Procedure +. Create API key `Secret` objects for each plan tier that you want to use. Each `Secret` must carry the `authorino.kuadrant.io/managed-by: authorino` label and a `secret.kuadrant.io/plan-id` annotation that identifies the plan tier as shown in the following example: ++ +.Example `Secret` object for plan tiers +[source,yaml,subs="+quotes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: gold-key + namespace: ${KUADRANT_DEVELOPER_NS} + labels: + authorino.kuadrant.io/managed-by: authorino + app: __ + annotations: + secret.kuadrant.io/plan-id: gold +stringData: + api_key: __ +type: Opaque +--- +apiVersion: v1 +kind: Secret +metadata:curl + name: silver-key + namespace: ${KUADRANT_GATEWAY_NS} + labels: + authorino.kuadrant.io/managed-by: authorino + app: __ + annotations: + secret.kuadrant.io/plan-id: silver +stringData: + api_key: __ +type: Opaque +--- +apiVersion: v1 +kind: Secret +metadata: + name: bronze-key + namespace: ${KUADRANT_GATEWAY_NS} + labels: + authorino.kuadrant.io/managed-by: authorino + app: __ + annotations: + secret.kuadrant.io/plan-id: bronze +stringData: + api_key: __ +type: Opaque +---- +* Replace 'KUADRANT_GATEWAY_NS' with the namespace for the object. +* Replace `__ ` with the name of your application. +* Replace `__`, `__`, and `__` with the actual API key strings you want to assign to each tier. diff --git a/modules/proc-rhcl-deploying-planpolicy-rate-limiting.adoc b/modules/proc-rhcl-deploying-planpolicy-rate-limiting.adoc new file mode 100644 index 000000000000..946653e73a1b --- /dev/null +++ b/modules/proc-rhcl-deploying-planpolicy-rate-limiting.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-deploying-planpolicy-rate-limiting_{context}"] += Deploying plan-based rate limiting with a PlanPolicy + +[role="_abstract"] +After you create your `AuthPolicy` and secrets, you can create a `PlanPolicy` object to enforce tiered rate limits on specific authenticated users. + +[NOTE] +==== +You can create a `PlanPolicy` object by using the {prodname} web console plugin. +==== + +.Prerequisites + +* You installed {prodname} +* You installed {oc-first}. +* You are logged in to your cluster. +* You created the `Gateway` object for your deployment. +* You configured API key-based authentication. + +[NOTE] +==== +A `PlanPolicy` can target and HTTPRoute, Gateway, or GRPCRoute. +==== + +.Procedure + +. Create a `PlanPolicy` object to enforce plan-based rate limits on the gateway by using the following example. ++ +.Example PlanPolicy object +[source,yaml,subs="+quotes"] +---- +apiVersion: extensions.kuadrant.io/v1alpha1 +kind: PlanPolicy +metadata: + name: + namespace: ${KUADRANT_DEVELOPER_NS} +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: __ + plans: + - tier: gold + predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "gold" + limits: + daily: 5 + - tier: silver + predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "silver" + limits: + daily: 2 + - tier: bronze + predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "bronze" + limits: + daily: 1 +---- ++ +[NOTE] +==== +The `PlanPolicy` object uses the `spec.plans.limits` parameter to enforce rate limits at the plan tier level instead of the individual subscriber level. +==== ++ +* Replace `__` with the name of your application. +* Replace `__ with the `PlanPolicy` object for your application. +* Replace 'KUADRANT_DEVELOPER_NS' with the namespace for your developer in {prodname}. +* Each `predicate` is a CEL expression. The predicates are evaluated in order, and the first matching plan is applied to the authenticated user. ++ +[NOTE] +==== +The CEL expressions can be anything that applies to your use case. You can use an expression different from the `secret.kuadrant.io/plan-id` expression. +==== ++ +* The `limits` field supports the following windows: `daily`, `weekly`, `monthly`, `yearly`, and `custom`. Custom limits take a `limit` value and a `window` duration string, for example: ++ +[source,yaml] +---- +limits: + daily: 100 + weekly: 500 + monthly: 2000 + custom: + - limit: 10 + window: "1m" +---- \ No newline at end of file diff --git a/modules/proc-rhcl-planpolicy-ratelimiting-verify.adoc b/modules/proc-rhcl-planpolicy-ratelimiting-verify.adoc new file mode 100644 index 000000000000..0490cc68edd5 --- /dev/null +++ b/modules/proc-rhcl-planpolicy-ratelimiting-verify.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-planpolicy-ratelimiting-verify_{context}"] += Verifying the PlanPolicy custom resource (CR) + +[role="_abstract"] +You can verify the configuration of the custom resource (CR) for the 'PlanPolicy' object. + +.Procedure +. Confirm that the `AuthConfig` CR was updated with plan data from the `PlanPolicy` object by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get authconfig -n __ -o yaml +---- ++ +Replace __ with the namespace you used for this {prodname} deployment. ++ +The output should include plan information in the response section of the AuthConfig. ++ + +. Send a request without an API key and confirm that it is rejected by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Host: __' http://${KUADRANT_GATEWAY_HOSTNAME}/toy -i ++ +---- +* Replace `__` with the host name for your API. +* KUADRANT_GATEWAY_HOSTNAME: Hostname of your gateway in {prodname}. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- ++ +. Send a request using the bronze-tier API key and confirm that it succeeds by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Authorization: APIKEY __' http://${KUADRANT_GATEWAY_HOSTNAME}/toy -i +---- +* Replace `__` with the actual API key string you want to assign to each tier. +* KUADRANT_GATEWAY_HOSTNAME: Hostname of your gateway in {prodname}. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +HTTP/1.1 200 OK +---- + +. Send a second request using the bronze-tier key and confirm that it is rate limited by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Authorization: APIKEY __' http://${KUADRANT_GATEWAY_HOSTNAME}/toy -i +---- +* Replace `__` with the actual API key string you want to assign to each tier. +* KUADRANT_GATEWAY_HOSTNAME: Host name of your gateway in {prodname}. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +HTTP/1.1 429 Too Many Requests +---- + +. Confirm that the gold-tier key allows up to five requests per day before the limit is enforced. \ No newline at end of file diff --git a/modules/proc-rhcl-planpolicy-verify.adoc b/modules/proc-rhcl-planpolicy-verify.adoc new file mode 100644 index 000000000000..ff5b50d147de --- /dev/null +++ b/modules/proc-rhcl-planpolicy-verify.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-planpolicy-verify_{context}"] += Verifying the acceptance of the 'AuthPolicy' CR + +[role="_abstract"] +You can confirm the acceptance of the `AuthPolicy` custom resource (CR) by running a few commands. + +.Procedure + +. Confirm that the `AuthPolicy` CR was accepted by checking its status by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get authpolicy __ -n ${KUADRANT_GATEWAY_NS} -o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}' +---- +* Replace `__` with the name of your application. +* Replace ${KUADRANT_GATEWAY_NS} with the namespace you used for this Connectivity Link deployment. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +True +---- +. Check that your `AuthPolicy` has `Accepted` and `Enforced` status by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get authpolicy ${KUADRANT_GATEWAY_NAME}-auth -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Enforced")].message}' +---- +* Replace 'KUADRANT_GATEWAY_NAME' with the name for your gateway in {product-title}. +* Replace 'KUADRANT_GATEWAY_NS' with the namespace for your gateway in {product-title}.c +---- +AuthPolicy has been accepted +AuthPolicy has been successfully enforced +---- ++ +. Confirm that all three API key secrets are present in the gateway namespace by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get secrets -n ${KUADRANT_GATEWAY_NS} -l app=__ +bronze-key Opaque 1 2 mins +gold-key Opaque 1 2 mins +---- +* Replace 'KUADRANT_GATEWAY_NS' with the namespace for your gateway in {product-title}. +* Replace `__` with the name of your application. ++ +. Send a request without an API key and confirm that it is rejected by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ $ curl -H 'Authorization: APIKEY __' http://__/toy -i +---- ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +Any message other than `401 Unauthorized` or `403 Forbidden` +---- \ No newline at end of file diff --git a/modules/proc-rhcl-secrets-verify.adoc b/modules/proc-rhcl-secrets-verify.adoc new file mode 100644 index 000000000000..59aed00465e2 --- /dev/null +++ b/modules/proc-rhcl-secrets-verify.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-secrets-verify_{context}"] += Verifying the presence of the API key secrets + +[role="_abstract"] +You can confirm the presence of the API key secrets by running a few commands. + +.Procedure + +. Confirm that all three API key secrets are present in the gateway namespace by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get secrets -n ${KUADRANT_GATEWAY_NS} -l app=__ +---- +* Replace `__` with the name of your application. ++ +.Expected output +---- +bronze-key Opaque 1 2 mins +gold-key Opaque 1 2 mins +silver-key Opaque 1 2 mins +---- ++ +. Send a request without an API key and confirm that it is rejected by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Host: __' http://__/toy -i +---- +* Replace __ with the host name for your API. +* Replace __ with the host name for the gateway. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +HTTP/1.1 401 Unauthorized +---- ++ +. Send a request with a valid API key and confirm that it succeeds by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -H 'Host: __' \ + -H 'Authorization: APIKEY __' \ + http://__/toy -i +---- +* Replace __ with the actual API key string. +* Replace __ with the host name for your API. ++ +.Expected output +[source,terminal,subs="+quotes"] +---- +HTTP/1.1 200 OK +---- \ No newline at end of file diff --git a/modules/ref-rhcl-planpolicy-custom-resources-params.adoc b/modules/ref-rhcl-planpolicy-custom-resources-params.adoc new file mode 100644 index 000000000000..f030298df1a7 --- /dev/null +++ b/modules/ref-rhcl-planpolicy-custom-resources-params.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-rhcl-planpolicy-custom-resources-params_{context}"] += PlanPolicy custom resource parameters + +[role="_abstract"] +This section provides a detailed reference for the configuration parameters available for the `PlanPolicy` custom resource: + +.PlanPolicy custom resource configuration fields definitions table +[cols="1,2"] +|=== +|Parameter|Description + +|`spec.targetRef` +|A reference to an existing Gateway API resource. A `PlanPolicy` object can target a Gateway, HTTPRoute, or GRPCRoute. The target resource must be in the same namespace as the `PlanPolicy` object. + +|`spec.plans` +|An ordered list of plan definitions. Plans are evaluated in sequence and the first plan whose predicate evaluates to `true` is applied. More specific predicates must appear before more general ones. + +|`spec.plans.tier` +|A unique string identifier for the plan tier, for example `gold`, `silver`, or `bronze`. + +|`spec.plans.predicate` +|Specifies a CEL expression evaluated against the authenticated request context. + +|`spec.plans.limits` +|Specifies the rate limiting configuration for the tier. + +|=== \ No newline at end of file diff --git a/modules/ref-rhcl-planpolicy-known-limitations.adoc b/modules/ref-rhcl-planpolicy-known-limitations.adoc new file mode 100644 index 000000000000..01cd037dec7d --- /dev/null +++ b/modules/ref-rhcl-planpolicy-known-limitations.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-rhcl-planpolicy-known-limitations_{context}"] += Known limitations + +[role="_abstract"] +* A `PlanPolicy` object can only target HTTPRoutes, GRPCRoutes, and Gateways defined in the same namespace as the `PlanPolicy` object. +* Plan predicates are evaluated in order. More specific predicates must appear before more general ones to ensure correct plan assignment. +* Plan identification requires authentication to be configured through an AuthPolicy. \ No newline at end of file diff --git a/modules/ref-rhcl-planpolicy-plan-limits.adoc b/modules/ref-rhcl-planpolicy-plan-limits.adoc new file mode 100644 index 000000000000..e13e2ce5d8ce --- /dev/null +++ b/modules/ref-rhcl-planpolicy-plan-limits.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-rhcl-planpolicy-plan-limits_{context}"] += Plan limits + +[role="_abstract"] +The `limits` field in each plan definition sets the maximum number of requests allowed within each time window. All fields are optional; specify only the windows relevant to your use case. + +[cols="1,2",options="header"] +|=== +|Field |Description + +|`daily` +|Maximum requests per calendar day. + +|`weekly` +|Maximum requests per calendar week. +|`custom` +|One or more custom windows. Each entry requires a `limit` (integer) and a `window` (duration string, for example `"1h"` or `"1m"`). +|=== + +The following example shows a plan using all available limit types: + +[source,yaml] +---- +limits: + daily: 1000 + weekly: 5000 + monthly: 20000 + yearly: 200000 + custom: + - limit: 100 +---- diff --git a/modules/ref-rhcl-planpolicy-plan-predicates.adoc b/modules/ref-rhcl-planpolicy-plan-predicates.adoc new file mode 100644 index 000000000000..e4bb29b1fcfb --- /dev/null +++ b/modules/ref-rhcl-planpolicy-plan-predicates.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-rhcl-planpolicy-plan-predicates_{context}"] += Plan predicates + +[role="_abstract"] +Plan predicates are CEL expressions that determine which plan tier applies to a request. {prodname} evaluates predicates in the order they appear in `spec.plans` and selects the first plan whose predicate returns `true`. + +The following patterns are supported: + +Plan identified by an annotation on the API key Secret::: ++ +[source,yaml] +---- +predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "gold" +---- + +Plan identified by a JWT claim::: ++ +[source,yaml] +---- +predicate: | + has(auth.identity) && auth.identity.sub == "premium-user" +---- + +Plan identified by multiple conditions::: ++ +[source,yaml] +---- +predicate: | + has(auth.identity) && + auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "gold" && + auth.identity.metadata.labels["app"] == "my-app" +---- + +The `has(auth.identity)` check at the start of each predicate confirms that the request is authenticated before evaluating plan-specific conditions. \ No newline at end of file diff --git a/modules/ref-rhcl-planpolicy-target-gateway.adoc b/modules/ref-rhcl-planpolicy-target-gateway.adoc new file mode 100644 index 000000000000..e16a737243bc --- /dev/null +++ b/modules/ref-rhcl-planpolicy-target-gateway.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-rhcl-planpolicy-target-gateway_{context}"] += Targeting a Gateway + +[role="_abstract"] +When a `PlanPolicy` object targets a Gateway, {prodname} enforces the plan-based rate limits on all routes attached to that Gateway, as shown in the following example. + +.Example enforcement of plan-based rate limits on a Gateway + +[source,yaml] +---- +apiVersion: extensions.kuadrant.io/v1alpha1 +kind: PlanPolicy +metadata: + name: __ + namespace: __ +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: __ + plans: + # ... +---- +* Replace __ with the name of your gateway plan. +* Replace __ with your namespace.__ +* Replace __ with the name of the Gateway. \ No newline at end of file diff --git a/modules/ref-rhcl-planpolicy-targeting-routes.adoc b/modules/ref-rhcl-planpolicy-targeting-routes.adoc new file mode 100644 index 000000000000..6f2526f83d5e --- /dev/null +++ b/modules/ref-rhcl-planpolicy-targeting-routes.adoc @@ -0,0 +1,53 @@ +// Module included in the following assemblies: +// +// *deployment/rhcl-planpolicy.adoc + +:_mod-docs-content-type: REFERENCE +[id="proc-rhcl-deploying-authpolicy-targeting-routes_{context}"] += Targeting an HTTPRoute or GRPCRoute + +[role="_abstract"] +. When a `PlanPolicy` object targets an HTTPRoute or GRPCRoute, you can use the following example to enforce the plan-based rate limits on all traffic flowing through that specific route: ++ +.Example enforcement of plan-based rate limits on route traffic + +[source,yaml] +---- +apiVersion: extensions.kuadrant.io/v1alpha1 +kind: PlanPolicy +metadata: + name: __ + namespace: __ +spec: + targetRef: + group: gateway.networking.k8s.io + kind: HTTPRoute + name: __ + plans: + - tier: gold + predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "gold" + limits: + daily: 500 + weekly: 2000 + - tier: silver + predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "silver" + limits: + daily: 500 + weekly: 2000 + - tier: bronze + predicate: | + has(auth.identity) && auth.identity.metadata.annotations["secret.kuadrant.io/plan-id"] == "bronze" + limits: + daily: 100 + weekly: 500 +---- +* Replace __ with the name of your route plan. +* Replace __ with your namespace. +* Replace __ with the name of the HTTProute or GRPCRoute. + +[NOTE] +==== +The CEL expressions can be anything that applies to your use case. You can use an expression different from the `secret.kuadrant.io/plan-id` expression. +====