[WIP] OSDOCS-20546: adds extension SDK docs

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?

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.

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.