ko: describe how cross namespace references work

Author: pmalek

app/_indices/operator.yaml

@@ -91,6 +91,7 @@ groups:
           - path: /operator/konnect/reconciliation-loop/
           - path: /operator/konnect/labelling/
           - path: /operator/konnect/kongpluginbinding/
+          - path: /operator/konnect/cross-namespace-references/
       - title: "Konnect CRDs: Control Planes"
         items:
           - path: /operator/konnect/crd/control-planes/**/*

app/operator/konnect/cross-namespace-references.md

@@ -0,0 +1,87 @@
+---
+title: "Cross namespace references"
+description: "How do I use cross namespace references with {{ site.operator_product_name }}?"
+content_type: reference
+layout: reference
+products:
+  - operator
+breadcrumbs:
+  - /operator/
+  - index: operator
+    group: Konnect
+  - index: operator
+    group: Konnect
+    section: Key Concepts
+
+min_version:
+  operator: '2.1'
+
+---
+
+{{ site.operator_product_name }} supports cross namespace references for certain resources.
+This allows you to reference resources that are located in different namespaces than the resource that is referencing them.
+
+## ControlPlane configuration {% new_in 2.1 %}
+
+When configuring a `KonnectGatewayControlPlane`, you can reference it from entities defined ain a different namespace.
+
+This reference can be done via the `spec.controlPlaneRef.konnectNamespacedRef.namespace` field, by specifying the `namespace` of the `KonnectGatewayControlPlane` resource.
+
+```yaml
+apiVersion: configuration.konghq.com/{{ site.operator_kongservice_api_version }}
+kind: KongService
+metadata:
+  name: my-service
+  namespace: default
+spec:
+  name: service-1
+  host: example.com
+  controlPlaneRef:
+    type: konnectNamespacedRef
+    konnectNamespacedRef:
+      name: my-control-plane
+      namespace: kong
+```
+
+In order to protect cross namespace references, the `KonnectGatewayControlPlane` resource must explicitly allow references from other namespaces by specifying `KongReferenceGrant` resources.
+
+```yaml
+apiVersion: configuration.konghq.com/{{ site.operator_kongreferencegrant_api_version }}
+kind: KongReferenceGrant
+metadata:
+  name: allow-kongservice-to-konnectgatewaycontrolplane
+  namespace: kong
+spec:
+  from:
+    - group: configuration.konghq.com
+      kind: KongService
+      namespace: default
+  to:
+    - group: konnect.konghq.com
+      kind: KonnectGatewayControlPlane
+      # Optionally specify a specific KonnectGatewayControlPlane name to allow
+      # only this specific resource to be referenced.
+      # name: my-control-plane
+```
+
+## Troubleshooting
+
+If you're having issues with cross namespace references, you can always check your
+object's status conditions - specifically the `ResolvedRefs` condition - for more information:
+
+```bash
+kg kongservice -n kong service-1 -o jsonpath-as-json="{ .status.conditions[?(@.type=='ResolvedRefs')]}"
+```
+
+```json
+[
+    {
+        "lastTransitionTime": "2025-12-19T15:18:07Z",
+        "message": "KongReferenceGrant default/my-control-plane does not allow access to KonnectGatewayControlPlane <konnectNamespacedRef:default/my-control-plane>",
+        "observedGeneration": 2,
+        "reason": "RefNotPermitted",
+        "status": "False",
+        "type": "ResolvedRefs"
+    }
+]
+```

jekyll.yml

@@ -158,4 +158,6 @@ latest_gateway_oss_version: "3.9.1"
 operator_gatewayconfiguration_api_version: "v2beta1"
 operator_konnectgatewaycontrolplane_api_version: "v1alpha2"
 operator_konnectextension_api_version: "v1alpha2"
+operator_kongservice_api_version: "v1alpha1"
+operator_kongreferencegrant_api_version: "v1alpha1"
 render_banner: false