From 4206afd781c4757cfc8d459186c65f0f2571e484 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Mon, 31 Aug 2026 15:05:28 -0400 Subject: [PATCH] OSDOCS-20546: adds extension SDK docs --- develop/rhcl-develop-extension-sdk.adoc | 20 +++++++++++ modules/con-rhcl-develop-extension-sdk.adoc | 20 +++++++++++ ...n-rhcl-extension-sdk-example-scenario.adoc | 34 +++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 develop/rhcl-develop-extension-sdk.adoc create mode 100644 modules/con-rhcl-develop-extension-sdk.adoc create mode 100644 modules/con-rhcl-extension-sdk-example-scenario.adoc diff --git a/develop/rhcl-develop-extension-sdk.adoc b/develop/rhcl-develop-extension-sdk.adoc new file mode 100644 index 00000000000..07922d751e6 --- /dev/null +++ b/develop/rhcl-develop-extension-sdk.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/attributes.adoc[] +[id="rhcl-develop-extension-sdk"] += Build and integrate custom policy extensions +:context: rhcl-develop-extension-sdk + +toc::[] + +[role="_abstract"] +Build and integrate custom policy extensions by using the gRPC-based SDK. Write controller logic that exchanges topology queries and data bindings directly with the {prodname} Operator. + +:FeatureName: extension SDK + +include::snippets/technology-preview.adoc[] + +include::modules/con-rhcl-develop-extension-sdk.adoc[leveloffset=+1] + +include::modules/con-rhcl-extension-sdk-example-scenario.adoc[leveloffset=+1] + +//Q; are we giving any examples of extensions that might be useful? diff --git a/modules/con-rhcl-develop-extension-sdk.adoc b/modules/con-rhcl-develop-extension-sdk.adoc new file mode 100644 index 00000000000..ed1010c3cc1 --- /dev/null +++ b/modules/con-rhcl-develop-extension-sdk.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * develop/rhcl-develop-extension-sdk.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-rhcl-develop-extension-sdk_{context}"] += Extension SDK with {prodname} + +[role="_abstract"] +An extension is an ordinary workload that you own and deploy yourself. You can build, roll out, and roll back extensions that each add a new policy kind against the {prodname} Operator on your own release cadence as required. + +Your extensions connect to the Operator over a network. Each extension owns a single policy kind that cooperates with the {prodname} Operator, exchanging topology queries and data bindings over gRPC by using the extension SDK. The controller might also read and interact with other resources in the cluster topology. + +Extensions have the following characteristics: + +* The Kubernetes `ServiceAccount` object that the extension workload runs as is the extension identity. The extension presents a token for that `ServiceAccount` object at handshake. The Operator verifies the token and derives the identity from the token. The Operator does not just trust a name that the extension asserts. + +* Ownership with role-based access (RBAC): Which policy kind an extension can claim is an authorization decision. The extension `ServiceAccount` object is granted permission to `register` a specific policy kind through an ordinary `Role` and `ClusterRole` binding. The Operator checks that permission at handshake. There is no separate credential to generate or distribute. + +* Authentication maintained: Extensions hold an authenticated session while connected. All of calls after the first authentication ride on that session. The single gRPC endpoint is a `Service` object that every extension connects to. Built-in extensions and standalone extensions use the same endpoint and the same handshake; they differ only in where their token comes from. diff --git a/modules/con-rhcl-extension-sdk-example-scenario.adoc b/modules/con-rhcl-extension-sdk-example-scenario.adoc new file mode 100644 index 00000000000..a8bebda0524 --- /dev/null +++ b/modules/con-rhcl-extension-sdk-example-scenario.adoc @@ -0,0 +1,34 @@ + +// Module included in the following assemblies: +// +// * develop/rhcl-develop-extension-sdk.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-rhcl-extension-sdk-example-scenario_{context}"] += Extension SDK example scenario + +[role="_abstract"] +You can use an extension SDK for various scenarios that require specific policies. + +For example, your organization operates a global API running across many {ocp} clusters in different regions, such as North America, the European Union (EU) and Asia-Pacific (APAC) nations. You have compliance requirements stating that EU user traffic must strictly go through EU-based infrastructure. Non-EU traffic can route anywhere. + +You can write a `GeoRoutingPolicy` extension by creating a custom resource definition (CRD) called `GeoRoutingPolicy`. + +* You include a rule that specify data residency requirements by defining `allowedRegions: ["eu-central-1"]`. +* Developers attach the `GeoRoutingPolicy` CRD to an `HTTPRoute` or `Gateway` object. + +After you deploy it, the extension binary runs as a standalone pod. Using the SDK, the extension communicates over gRPC with {prodname} and does three main tasks: + +* First, the extension reads the cluster topology. The extension queries {prodname} over gRPC to map out the `Gateway` objects and pods that are currently active in the cluster. +* Next, the extension evaluates the context by fetching real-time cluster health or external IP address location metadata. +* Then the extension exchanges data bindings. It computes where traffic should go and pushes data bindings back to {prodname} through gRPC. + +{prodname} then takes the data bindings generated by your extension and translates them directly into the underlying Envoy Proxy configurations or Authorino or Limitador component Operator rules. + +Other common extension examples include the following types: + +* `TieredBillingPolicy` CRD. Reads customer API usage, dynamically updates user rate limits through gRPC data bindings based on their subscription tier in an external billing system. + +* `WorkloadIdentityPolicy` CRD. Queries dynamic cluster topology to verify that incoming route requests originate from trusted SPIFFE/SPIRE identity tokens before injecting headers into Envoy. + +* `CloudCostPolicy` CRD. Interrogates cluster metrics. If cloud provider egress costs spike in Region A, it tells {prodname} to route lower-priority traffic to Region B.