From 8b4086c3c659f6a592f54ed79ea2611ea7b6c430 Mon Sep 17 00:00:00 2001
From: Lucie Milan <lucie.milan@konghq.com>
Date: Thu, 11 Jun 2026 11:37:12 +0200
Subject: [PATCH 1/6] multi-tenancy draft

---
 app/_data/series.yml                          |   3 +
 .../operator-multi-tenancy-1-setup.md         | 105 ++++++++++
 ...operator-multi-tenancy-2-public-gateway.md | 125 ++++++++++++
 ...perator-multi-tenancy-3-private-gateway.md | 121 +++++++++++
 .../operator-multi-tenancy-4-test-services.md | 147 ++++++++++++++
 app/_indices/operator.yaml                    |   3 +
 .../control-plane-watch-namespaces.md         |   8 +
 app/operator/reference/multi-tenancy.md       | 190 ++++++++++++++++++
 8 files changed, 702 insertions(+)
 create mode 100644 app/_how-tos/operator/operator-multi-tenancy-1-setup.md
 create mode 100644 app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
 create mode 100644 app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
 create mode 100644 app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
 create mode 100644 app/operator/reference/multi-tenancy.md

diff --git a/app/_data/series.yml b/app/_data/series.yml
index f926772d6c..9e18c98eba 100644
--- a/app/_data/series.yml
+++ b/app/_data/series.yml
@@ -41,3 +41,6 @@ mcp-acls:
 mesh-get-started-universal:
   title: Get started with {{site.mesh_product_name}} on Universal
   url: /mesh/get-started/universal/install/
+operator-multi-tenancy:
+  title: Deploy multiple isolated gateways on the same cluster
+  url: /operator/dataplanes/how-to/multi-tenancy/setup/
diff --git a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
new file mode 100644
index 0000000000..489e7f0fbf
--- /dev/null
+++ b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
@@ -0,0 +1,105 @@
+---
+title: Install Kong Operator for multi-tenancy
+description: "Create tenant namespaces, install {{ site.operator_product_name }} scoped to those namespaces, and apply a KongLicense."
+content_type: how_to
+
+permalink: /operator/dataplanes/how-to/multi-tenancy/setup/
+series:
+  id: operator-multi-tenancy
+  position: 1
+
+breadcrumbs:
+  - /operator/
+  - index: operator
+    group: Gateway Deployment
+  - index: operator
+    group: Gateway Deployment
+    section: "How-To"
+
+products:
+  - operator
+
+works_on:
+  - on-prem
+
+min_version:
+  operator: '2.0'
+
+related_resources:
+  - text: "Multi-tenancy reference"
+    url: /operator/reference/multi-tenancy/
+  - text: "Limiting namespaces watched by ControlPlane"
+    url: /operator/reference/control-plane-watch-namespaces/
+
+tldr:
+  q: How do I set up {{ site.operator_product_name }} for multi-tenancy?
+  a: |
+    Install {{ site.operator_product_name }} with `env.watch_namespace` scoped to your
+    tenant namespaces, then apply a single `KongLicense` in `kong-system`.
+
+prereqs:
+  skip_product: true
+---
+
+<!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces,
+     Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5 -->
+
+This guide deploys two independent {{ site.base_gateway }} instances — one public-facing, one private — on the same cluster using a single {{ site.operator_product_name }} installation. Each gateway is scoped to its own namespace so that its in-memory KIC only processes routes from that namespace.
+
+## Create namespaces
+
+Create the operator namespace and the two tenant namespaces:
+
+```bash
+kubectl create namespace kong-system
+kubectl create namespace kong-gw-public
+kubectl create namespace kong-gw-private
+```
+
+## Install {{ site.operator_product_name }}
+
+<!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces -->
+
+Add the Kong Helm chart repository:
+
+```bash
+helm repo add kong https://charts.konghq.com
+helm repo update
+```
+
+Install {{ site.operator_product_name }} scoped to the two tenant namespaces. The `watch_namespace` value prevents the operator from reconciling resources in any other namespace.
+
+```bash
+helm upgrade --install kong-operator kong/kong-operator \
+  -n kong-system \
+  --create-namespace \
+  --set image.tag={{ site.data.operator_latest.release }} \
+  --values - <<EOF
+env:
+  watch_namespace: kong-gw-public,kong-gw-private
+EOF
+```
+
+## Validate
+
+Wait for {{ site.operator_product_name }} to be ready:
+
+{% include prereqs/products/operator-validate-deployment.md %}
+
+## Apply a KongLicense
+
+<!-- SOURCE: Baptiste's gist; KongLicense applied once in kong-system is shared by all Gateways -->
+<!-- GAP: This behaviour is not documented in the product docs. A single KongLicense in
+     kong-system covers all Gateways managed by this operator installation. -->
+
+Apply the license once in `kong-system`. It is shared by all gateways managed by this operator installation. This assumes your license file is at `./license.json`.
+
+```bash
+kubectl -n kong-system apply -f - <<EOF
+apiVersion: configuration.konghq.com/v1alpha1
+kind: KongLicense
+metadata:
+  name: kong-license
+rawLicenseString: '$(cat ./license.json)'
+EOF
+```
diff --git a/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
new file mode 100644
index 0000000000..5137214af7
--- /dev/null
+++ b/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
@@ -0,0 +1,125 @@
+---
+title: Deploy the public gateway
+description: "Create a {{ site.base_gateway }} instance scoped to the public tenant namespace."
+content_type: how_to
+
+permalink: /operator/dataplanes/how-to/multi-tenancy/public-gateway/
+series:
+  id: operator-multi-tenancy
+  position: 2
+
+breadcrumbs:
+  - /operator/
+  - index: operator
+    group: Gateway Deployment
+  - index: operator
+    group: Gateway Deployment
+    section: "How-To"
+
+products:
+  - operator
+
+works_on:
+  - on-prem
+
+min_version:
+  operator: '2.0'
+
+related_resources:
+  - text: "Multi-tenancy reference"
+    url: /operator/reference/multi-tenancy/
+  - text: "Managed Gateways"
+    url: /operator/dataplanes/managed-gateways/
+  - text: "Gateway configuration"
+    url: /operator/dataplanes/gateway-configuration/
+
+tldr:
+  q: How do I deploy an isolated gateway for a single tenant?
+  a: |
+    Create a `GatewayConfiguration` with `controlPlaneOptions.watchNamespaces.type: own`,
+    then create the matching `GatewayClass` and `Gateway` in the tenant namespace.
+
+prereqs:
+  skip_product: true
+---
+
+<!-- SOURCE: Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5,
+     GatewayConfigControlPlaneOptions in custom-resources.md,
+     control-plane-watch-namespaces.md -->
+
+## Create a GatewayConfiguration
+
+The `controlPlaneOptions.watchNamespaces.type: own` field restricts the in-memory KIC for this gateway to watch only the `kong-gw-public` namespace. Without this, it would watch all namespaces and process routes belonging to other tenants.
+
+```bash
+kubectl apply -f - <<EOF
+kind: GatewayConfiguration
+apiVersion: gateway-operator.konghq.com/{{ site.operator_gatewayconfiguration_api_version }}
+metadata:
+  name: gw-public
+  namespace: kong-gw-public
+spec:
+  dataPlaneOptions:
+    deployment:
+      podTemplateSpec:
+        spec:
+          containers:
+          - name: proxy
+            image: kong/kong-gateway:{{ site.data.gateway_latest.release }}
+  controlPlaneOptions:
+    watchNamespaces:
+      type: own
+EOF
+```
+
+## Create a GatewayClass
+
+<!-- SOURCE: operator-get-started-gateway-api-2-create-gateway.md -->
+
+Create a `GatewayClass` that references the `GatewayConfiguration` above:
+
+```bash
+kubectl apply -f - <<EOF
+kind: GatewayClass
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: gw-public
+spec:
+  controllerName: konghq.com/gateway-operator
+  parametersRef:
+    group: gateway-operator.konghq.com
+    kind: GatewayConfiguration
+    name: gw-public
+    namespace: kong-gw-public
+EOF
+```
+
+## Create a Gateway
+
+Create the `Gateway` resource in the `kong-gw-public` namespace, referencing the `GatewayClass` above:
+
+```bash
+kubectl apply -f - <<EOF
+kind: Gateway
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: gw-public
+  namespace: kong-gw-public
+spec:
+  gatewayClassName: gw-public
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+EOF
+```
+
+## Validate
+
+Wait for the public gateway to become ready:
+
+{% validation kubernetes-resource %}
+kind: Gateway
+name: gw-public
+namespace: kong-gw-public
+{% endvalidation %}
diff --git a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
new file mode 100644
index 0000000000..862f6fbf23
--- /dev/null
+++ b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
@@ -0,0 +1,121 @@
+---
+title: Deploy the private gateway
+description: "Create a {{ site.base_gateway }} instance scoped to the private tenant namespace."
+content_type: how_to
+
+permalink: /operator/dataplanes/how-to/multi-tenancy/private-gateway/
+series:
+  id: operator-multi-tenancy
+  position: 3
+
+breadcrumbs:
+  - /operator/
+  - index: operator
+    group: Gateway Deployment
+  - index: operator
+    group: Gateway Deployment
+    section: "How-To"
+
+products:
+  - operator
+
+works_on:
+  - on-prem
+
+min_version:
+  operator: '2.0'
+
+related_resources:
+  - text: "Multi-tenancy reference"
+    url: /operator/reference/multi-tenancy/
+  - text: "Managed Gateways"
+    url: /operator/dataplanes/managed-gateways/
+  - text: "Gateway configuration"
+    url: /operator/dataplanes/gateway-configuration/
+
+tldr:
+  q: How do I add a second isolated gateway to the same cluster?
+  a: |
+    Repeat the `GatewayConfiguration` / `GatewayClass` / `Gateway` triptych in the
+    second tenant namespace with its own `watchNamespaces.type: own` setting.
+
+prereqs:
+  skip_product: true
+---
+
+<!-- SOURCE: Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5 -->
+
+## Create a GatewayConfiguration
+
+As with the public gateway, `controlPlaneOptions.watchNamespaces.type: own` restricts the in-memory KIC to watch only the `kong-gw-private` namespace.
+
+```bash
+kubectl apply -f - <<EOF
+kind: GatewayConfiguration
+apiVersion: gateway-operator.konghq.com/{{ site.operator_gatewayconfiguration_api_version }}
+metadata:
+  name: gw-private
+  namespace: kong-gw-private
+spec:
+  dataPlaneOptions:
+    deployment:
+      podTemplateSpec:
+        spec:
+          containers:
+          - name: proxy
+            image: kong/kong-gateway:{{ site.data.gateway_latest.release }}
+  controlPlaneOptions:
+    watchNamespaces:
+      type: own
+EOF
+```
+
+## Create a GatewayClass
+
+Create a `GatewayClass` that references the `GatewayConfiguration` above:
+
+```bash
+kubectl apply -f - <<EOF
+kind: GatewayClass
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: gw-private
+spec:
+  controllerName: konghq.com/gateway-operator
+  parametersRef:
+    group: gateway-operator.konghq.com
+    kind: GatewayConfiguration
+    name: gw-private
+    namespace: kong-gw-private
+EOF
+```
+
+## Create a Gateway
+
+Create the `Gateway` resource in the `kong-gw-private` namespace, referencing the `GatewayClass` above:
+
+```bash
+kubectl apply -f - <<EOF
+kind: Gateway
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: gw-private
+  namespace: kong-gw-private
+spec:
+  gatewayClassName: gw-private
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+EOF
+```
+
+## Validate
+
+Wait for the private gateway to become ready:
+
+{% validation kubernetes-resource %}
+kind: Gateway
+name: gw-private
+namespace: kong-gw-private
+{% endvalidation %}
diff --git a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
new file mode 100644
index 0000000000..1e07c23ae1
--- /dev/null
+++ b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
@@ -0,0 +1,147 @@
+---
+title: Deploy test services and validate isolation
+description: "Deploy a backend service and HTTPRoute in each tenant namespace, then confirm that each gateway only serves its own routes."
+content_type: how_to
+
+permalink: /operator/dataplanes/how-to/multi-tenancy/test-services/
+series:
+  id: operator-multi-tenancy
+  position: 4
+
+breadcrumbs:
+  - /operator/
+  - index: operator
+    group: Gateway Deployment
+  - index: operator
+    group: Gateway Deployment
+    section: "How-To"
+
+products:
+  - operator
+
+works_on:
+  - on-prem
+
+min_version:
+  operator: '2.0'
+
+related_resources:
+  - text: "Multi-tenancy reference"
+    url: /operator/reference/multi-tenancy/
+  - text: "{{site.operator_product_name}} architecture"
+    url: /operator/reference/architecture/
+
+next_steps:
+  - text: "Multi-tenancy reference"
+    url: /operator/reference/multi-tenancy/
+  - text: "Limiting namespaces watched by ControlPlane"
+    url: /operator/reference/control-plane-watch-namespaces/
+
+tldr:
+  q: How do I verify that two gateways are isolated from each other?
+  a: |
+    Deploy a backend service and `HTTPRoute` in each tenant namespace. Each in-memory KIC
+    is scoped to its own namespace via `watchNamespaces.type: own`, so routes in
+    `kong-gw-public` are invisible to the private gateway and vice versa.
+
+prereqs:
+  skip_product: true
+---
+
+<!-- SOURCE: Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5,
+     operator-get-started-gateway-api-3-create-route.md -->
+
+## Deploy a test service in each namespace
+
+Deploy the echo service in both tenant namespaces:
+
+```bash
+kubectl apply -f {{site.links.web}}/manifests/kic/echo-service.yaml -n kong-gw-public
+kubectl apply -f {{site.links.web}}/manifests/kic/echo-service.yaml -n kong-gw-private
+```
+
+## Create an HTTPRoute for the public gateway
+
+Create an `HTTPRoute` in the `kong-gw-public` namespace pointing to the echo service:
+
+```bash
+kubectl apply -f - <<EOF
+kind: HTTPRoute
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: echo
+  namespace: kong-gw-public
+spec:
+  parentRefs:
+  - group: gateway.networking.k8s.io
+    kind: Gateway
+    name: gw-public
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /echo
+    backendRefs:
+    - name: echo
+      port: 1027
+EOF
+```
+
+## Create an HTTPRoute for the private gateway
+
+Create an equivalent `HTTPRoute` in the `kong-gw-private` namespace:
+
+```bash
+kubectl apply -f - <<EOF
+kind: HTTPRoute
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: echo
+  namespace: kong-gw-private
+spec:
+  parentRefs:
+  - group: gateway.networking.k8s.io
+    kind: Gateway
+    name: gw-private
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /echo
+    backendRefs:
+    - name: echo
+      port: 1027
+EOF
+```
+
+## Validate
+
+Get the external IP address for each gateway:
+
+```bash
+export PUBLIC_GW_IP=$(kubectl get gateway gw-public -n kong-gw-public \
+  -o jsonpath='{.status.addresses[0].value}')
+export PRIVATE_GW_IP=$(kubectl get gateway gw-private -n kong-gw-private \
+  -o jsonpath='{.status.addresses[0].value}')
+```
+
+Both gateways should respond on `/echo`:
+
+{% validation request-check %}
+url: /echo
+status_code: 200
+on_prem_url: $PUBLIC_GW_IP
+konnect_url: $PUBLIC_GW_IP
+{% endvalidation %}
+
+{% validation request-check %}
+url: /echo
+status_code: 200
+on_prem_url: $PRIVATE_GW_IP
+konnect_url: $PRIVATE_GW_IP
+{% endvalidation %}
+
+<!-- GAP: There is no built-in mechanism in Kong Operator to verify that a route in namespace A
+     is NOT reachable through the gateway in namespace B. The isolation is enforced by the
+     watchNamespaces scoping (logical isolation), not by a NetworkPolicy (network-level isolation).
+     Users who need hard network-level isolation should add Kubernetes NetworkPolicy resources. -->
diff --git a/app/_indices/operator.yaml b/app/_indices/operator.yaml
index 1e1d19837b..432d156d4d 100644
--- a/app/_indices/operator.yaml
+++ b/app/_indices/operator.yaml
@@ -21,6 +21,8 @@ groups:
   - title: Reference
     sections:
       - items:
+          - path: /operator/reference/architecture/
+          - path: /operator/reference/multi-tenancy/
           - path: /operator/reference/configuration-options/
           - path: /operator/reference/custom-resources/
           - path: /operator/reference/version-compatibility/
@@ -63,6 +65,7 @@ groups:
           - path: /operator/dataplanes/how-to/use-custom-ca-certificate/
           - path: /operator/dataplanes/how-to/deploy-custom-plugins/
           - path: /operator/dataplanes/how-to/handle-ingress/
+          - path: /operator/dataplanes/how-to/multi-tenancy/setup/
           - path: /operator/dataplanes/how-to/configure-plugins-for-httproute/
       - title: Observability
         items:
diff --git a/app/operator/reference/control-plane-watch-namespaces.md b/app/operator/reference/control-plane-watch-namespaces.md
index 8e9e122941..f27ef83aaa 100644
--- a/app/operator/reference/control-plane-watch-namespaces.md
+++ b/app/operator/reference/control-plane-watch-namespaces.md
@@ -14,6 +14,14 @@ products:
 
 min_version:
   operator: '1.6'
+
+related_resources:
+  - text: "Multi-tenancy"
+    url: /operator/reference/multi-tenancy/
+  - text: "Deploy multiple isolated gateways"
+    url: /operator/dataplanes/how-to/multi-tenancy/setup/
+  - text: "{{site.operator_product_name}} architecture"
+    url: /operator/reference/architecture/
 ---
 
 By default, {{ site.operator_product_name }}'s `ControlPlane` watches all namespaces.
diff --git a/app/operator/reference/multi-tenancy.md b/app/operator/reference/multi-tenancy.md
new file mode 100644
index 0000000000..bd1a079e6e
--- /dev/null
+++ b/app/operator/reference/multi-tenancy.md
@@ -0,0 +1,190 @@
+---
+title: "Multi-tenancy"
+description: "Understand how to run multiple isolated {{ site.base_gateway }} instances on the same Kubernetes cluster using {{ site.operator_product_name }}."
+content_type: reference
+layout: reference
+
+breadcrumbs:
+  - /operator/
+  - index: operator
+    group: Reference
+
+products:
+  - operator
+
+works_on:
+  - on-prem
+
+min_version:
+  operator: '1.6'
+
+related_resources:
+  - text: "Deploy multiple isolated gateways on the same cluster"
+    url: /operator/dataplanes/how-to/multi-tenancy/setup/
+  - text: "{{site.operator_product_name}} architecture"
+    url: /operator/reference/architecture/
+  - text: "Limiting namespaces watched by ControlPlane"
+    url: /operator/reference/control-plane-watch-namespaces/
+  - text: "Gateway configuration"
+    url: /operator/dataplanes/gateway-configuration/
+  - text: "Managed Gateways"
+    url: /operator/dataplanes/managed-gateways/
+  - text: "Custom Resources"
+    url: /operator/reference/custom-resources/
+---
+
+<!-- SOURCE: architecture.md, control-plane-watch-namespaces.md, Baptiste's gist
+     https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5,
+     and FEATURES.md https://github.com/Kong/kong-operator/blob/main/FEATURES.md -->
+
+Multi-tenancy in {{ site.operator_product_name }} means running multiple isolated {{ site.base_gateway }} instances — each with their own routing configuration, data plane, and namespace scope — on the same Kubernetes cluster, managed by a single {{ site.operator_product_name }} installation.
+
+Common use cases include separating a public-facing API gateway from an internal one, or giving different teams independent gateway instances without requiring separate clusters.
+
+## How it works
+
+<!-- SOURCE: managed-gateways.md, architecture.md -->
+
+Each tenant is represented by a **Gateway**, provisioned using a triptych of three resources:
+
+```
+GatewayConfiguration  ──(parametersRef)──▶  GatewayClass  ──(gatewayClassName)──▶  Gateway
+```
+
+For each `Gateway`, {{ site.operator_product_name }} creates:
+
+- One **in-memory KIC instance** embedded inside the {{ site.operator_product_name }} pod (not a separately deployed pod), which watches Gateway API resources and translates them into Kong configuration.
+- One **DataPlane deployment** running {{ site.base_gateway }} in DB-less mode.
+
+Multiple `Gateway` resources can coexist in the same cluster. The resulting in-memory KIC instances and DataPlane pods are independent of each other. A single {{ site.operator_product_name }} installation manages them all.
+
+## Namespace isolation
+
+<!-- SOURCE: control-plane-watch-namespaces.md -->
+
+By default, each in-memory KIC instance watches **all namespaces** for Gateway API resources (`HTTPRoute`, `GRPCRoute`, etc.). This means, without additional configuration, one tenant's KIC would also process another tenant's routes. Namespace isolation is therefore required for multi-tenancy.
+
+The `watchNamespaces` field on `GatewayConfiguration.spec.controlPlaneOptions` controls which namespaces the in-memory KIC for each `Gateway` will watch.
+
+<!-- GAP: The control-plane-watch-namespaces.md page documents the ControlPlane CRD field directly,
+     but does not explain that it must be set via GatewayConfiguration.spec.controlPlaneOptions
+     when using managed Gateways (i.e., the normal Gateway API flow). Users following that page
+     alone would not know how to apply the setting in practice. -->
+
+### watchNamespaces types
+
+<!-- SOURCE: control-plane-watch-namespaces.md, custom-resources.md WatchNamespacesType -->
+
+The `watchNamespaces.type` field accepts three values:
+
+{% table %}
+columns:
+  - title: Type
+    key: type
+  - title: Behavior
+    key: behavior
+  - title: Use when
+    key: use
+rows:
+  - type: "`all`"
+    behavior: Watches all namespaces (default)
+    use: Single-tenant or dev environments
+  - type: "`own`"
+    behavior: Watches only the `ControlPlane`'s own namespace
+    use: One namespace per tenant (recommended)
+  - type: "`list`"
+    behavior: Watches own namespace plus a specified list
+    use: Routes for this tenant span multiple namespaces
+{% endtable %}
+
+When using `list`, the ControlPlane's own namespace is automatically included. Each additional namespace in the list requires a `WatchNamespaceGrant` resource in that namespace (see [WatchNamespaceGrant](#watchnamespacegrant)).
+
+{:.info}
+> Setting `watchNamespaces` via `GatewayConfiguration.spec.controlPlaneOptions` configures the `CONTROLLER_WATCH_NAMESPACE` environment variable in the managed KIC. If you set this variable manually through `podTemplateSpec`, it will override the `watchNamespaces` field.
+
+## Operator-level namespace scoping {% new_in 2.0 %}
+
+<!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces -->
+
+From v2.0, you can scope {{ site.operator_product_name }} itself to watch only specific namespaces. This is separate from the per-`ControlPlane` `watchNamespaces` configuration and is useful when running multiple {{ site.operator_product_name }} instances on the same cluster with strictly disjoint namespace assignments.
+
+Configure operator-level watch namespaces using the `watch_namespace` Helm value:
+
+```yaml
+# values.yaml
+env:
+  watch_namespace: namespace-a,namespace-b
+```
+
+Or via environment variable:
+
+```sh
+KONG_OPERATOR_WATCH_NAMESPACES='namespace-a,namespace-b'
+```
+
+{:.warning}
+> If both operator-level and `ControlPlane`-level watch namespaces are configured, they must not conflict. For example, if {{ site.operator_product_name }} watches namespaces A and B, a `ControlPlane` may only define watch namespaces A or B. Using namespace C would cause the `ControlPlane` to receive a failure status condition and stop reconciling.
+
+## WatchNamespaceGrant
+
+<!-- SOURCE: control-plane-watch-namespaces.md, custom-resources.md WatchNamespaceGrant -->
+
+When `watchNamespaces.type` is `list`, a `WatchNamespaceGrant` resource must be created in each additional namespace (beyond the ControlPlane's own). This resource explicitly grants the named `ControlPlane` permission to watch resources in that namespace.
+
+```yaml
+apiVersion: gateway-operator.konghq.com/v1alpha1
+kind: WatchNamespaceGrant
+metadata:
+  name: watch-namespace-grant
+  namespace: target-namespace       # the namespace being granted access to
+spec:
+  from:
+  - group: gateway-operator.konghq.com
+    kind: ControlPlane
+    namespace: control-plane-namespace  # the namespace where the ControlPlane lives
+```
+
+For the full field reference, see [WatchNamespaceGrant](/operator/reference/custom-resources/#watchnamespacegrant).
+
+## KongLicense
+
+<!-- SOURCE: Baptiste's docx feedback; confirmed by gist showing license applied once to kong-system -->
+<!-- GAP: Not explicitly documented anywhere that one KongLicense in kong-system covers all Gateways. -->
+
+A single `KongLicense` applied in the `kong-system` namespace (where {{ site.operator_product_name }} is installed) is shared by all `Gateway` instances managed by that operator. You do not need to create a license per tenant.
+
+```yaml
+apiVersion: configuration.konghq.com/v1alpha1
+kind: KongLicense
+metadata:
+  name: kong-license
+  namespace: kong-system
+rawLicenseString: '<your license JSON>'
+```
+
+## Recommended namespace layout
+
+<!-- SOURCE: Baptiste's gist and docx feedback -->
+
+The recommended pattern for namespace-per-tenant isolation:
+
+{% table %}
+columns:
+  - title: Namespace
+    key: namespace
+  - title: Contents
+    key: contents
+rows:
+  - namespace: "`kong-system`"
+    contents: "{{ site.operator_product_name }} pod, `KongLicense`"
+  - namespace: "`kong-gw-public`"
+    contents: "`GatewayConfiguration`, `GatewayClass`, `Gateway`, `DataPlane` pod, `HTTPRoute`s, upstream services for the public gateway"
+  - namespace: "`kong-gw-private`"
+    contents: Same triptych for the private gateway, in isolation
+{% endtable %}
+
+Each namespace is an independent routing domain. The in-memory KIC for `kong-gw-public` only sees routes in `kong-gw-public`; the KIC for `kong-gw-private` only sees routes in `kong-gw-private`.
+
+<!-- GAP: There is no guidance on RBAC / NetworkPolicy to further harden tenant boundaries.
+     For example, whether teams should have RBAC limited to their own namespace,
+     or whether DataPlane pods need NetworkPolicy rules to prevent cross-namespace traffic. -->

From 293df6592899bc91335a96ea5f4ba1b055af00f1 Mon Sep 17 00:00:00 2001
From: Lucie Milan <lucie.milan@konghq.com>
Date: Thu, 11 Jun 2026 12:50:31 +0200
Subject: [PATCH 2/6] add wait and diagram

---
 .../operator-multi-tenancy-1-setup.md         |  78 ++++++++---
 ...operator-multi-tenancy-2-public-gateway.md |  40 +++---
 ...perator-multi-tenancy-3-private-gateway.md |  40 +++---
 .../operator-multi-tenancy-4-test-services.md | 125 ++++++++++--------
 4 files changed, 175 insertions(+), 108 deletions(-)

diff --git a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
index 489e7f0fbf..09b42b4757 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
@@ -1,5 +1,5 @@
 ---
-title: Install Kong Operator for multi-tenancy
+title: Install {{ site.operator_product_name }} for multi-tenancy
 description: "Create tenant namespaces, install {{ site.operator_product_name }} scoped to those namespaces, and apply a KongLicense."
 content_type: how_to
 
@@ -46,9 +46,45 @@ prereqs:
 
 This guide deploys two independent {{ site.base_gateway }} instances — one public-facing, one private — on the same cluster using a single {{ site.operator_product_name }} installation. Each gateway is scoped to its own namespace so that its in-memory KIC only processes routes from that namespace.
 
+The following diagram shows the end state you'll build across this series:
+
+<!--vale off-->
+{% mermaid %}
+flowchart TB
+  subgraph cluster["Kubernetes Cluster"]
+    subgraph sys["kong-system"]
+      KO["{{ site.operator_product_name }}\n(KongLicense)"]
+    end
+
+    subgraph pub["kong-gw-public"]
+      ConfigPub["GatewayConfiguration\nwatchNamespaces: own"]
+      GWPub["Gateway: gw-public"]
+      DPPub["Data plane Pod"]
+      SvcPub["echo service\nHTTPRoute /echo"]
+    end
+
+    subgraph priv["kong-gw-private"]
+      ConfigPriv["GatewayConfiguration\nwatchNamespaces: own"]
+      GWPriv["Gateway: gw-private"]
+      DPPriv["Data plane Pod"]
+      SvcPriv["echo service\nHTTPRoute /echo"]
+    end
+
+    KO -->|manages| GWPub
+    KO -->|manages| GWPriv
+    ConfigPub -.->|configures| GWPub
+    ConfigPriv -.->|configures| GWPriv
+    GWPub -->|provisions| DPPub
+    GWPriv -->|provisions| DPPriv
+    DPPub -->|routes traffic to| SvcPub
+    DPPriv -->|routes traffic to| SvcPriv
+  end
+{% endmermaid %}
+<!--vale on-->
+
 ## Create namespaces
 
-Create the operator namespace and the two tenant namespaces:
+Create the system namespace and the two tenant namespaces:
 
 ```bash
 kubectl create namespace kong-system
@@ -60,25 +96,25 @@ kubectl create namespace kong-gw-private
 
 <!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces -->
 
-Add the Kong Helm chart repository:
-
-```bash
-helm repo add kong https://charts.konghq.com
-helm repo update
-```
-
-Install {{ site.operator_product_name }} scoped to the two tenant namespaces. The `watch_namespace` value prevents the operator from reconciling resources in any other namespace.
-
-```bash
-helm upgrade --install kong-operator kong/kong-operator \
-  -n kong-system \
-  --create-namespace \
-  --set image.tag={{ site.data.operator_latest.release }} \
-  --values - <<EOF
-env:
-  watch_namespace: kong-gw-public,kong-gw-private
-EOF
-```
+1. Add the Kong Helm chart repository:
+
+   ```bash
+   helm repo add kong https://charts.konghq.com
+   helm repo update
+   ```
+
+1. Install {{ site.operator_product_name }} scoped to the two tenant namespaces. The `watch_namespace` value prevents the operator from reconciling resources in any other namespace.
+
+   ```bash
+   helm upgrade --install kong-operator kong/kong-operator \
+     -n kong-system \
+     --create-namespace \
+     --set image.tag={{ site.data.operator_latest.release }} \
+     --values - <<EOF
+   env:
+     watch_namespace: kong-gw-public,kong-gw-private
+   EOF
+   ```
 
 ## Validate
 
diff --git a/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
index 5137214af7..fb4155ca41 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
@@ -76,23 +76,29 @@ EOF
 
 <!-- SOURCE: operator-get-started-gateway-api-2-create-gateway.md -->
 
-Create a `GatewayClass` that references the `GatewayConfiguration` above:
-
-```bash
-kubectl apply -f - <<EOF
-kind: GatewayClass
-apiVersion: gateway.networking.k8s.io/v1
-metadata:
-  name: gw-public
-spec:
-  controllerName: konghq.com/gateway-operator
-  parametersRef:
-    group: gateway-operator.konghq.com
-    kind: GatewayConfiguration
-    name: gw-public
-    namespace: kong-gw-public
-EOF
-```
+1. Create a `GatewayClass` that references the `GatewayConfiguration` above:
+
+   ```bash
+   kubectl apply -f - <<EOF
+   kind: GatewayClass
+   apiVersion: gateway.networking.k8s.io/v1
+   metadata:
+     name: gw-public
+   spec:
+     controllerName: konghq.com/gateway-operator
+     parametersRef:
+       group: gateway-operator.konghq.com
+       kind: GatewayConfiguration
+       name: gw-public
+       namespace: kong-gw-public
+   EOF
+   ```
+
+1. Wait for {{ site.operator_product_name }} to accept the `GatewayClass`:
+
+   ```bash
+   kubectl wait --for=condition=Accepted=True gatewayclass/gw-public --timeout=60s
+   ```
 
 ## Create a Gateway
 
diff --git a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
index 862f6fbf23..ada79fb82d 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
@@ -72,23 +72,29 @@ EOF
 
 ## Create a GatewayClass
 
-Create a `GatewayClass` that references the `GatewayConfiguration` above:
-
-```bash
-kubectl apply -f - <<EOF
-kind: GatewayClass
-apiVersion: gateway.networking.k8s.io/v1
-metadata:
-  name: gw-private
-spec:
-  controllerName: konghq.com/gateway-operator
-  parametersRef:
-    group: gateway-operator.konghq.com
-    kind: GatewayConfiguration
-    name: gw-private
-    namespace: kong-gw-private
-EOF
-```
+1. Create a `GatewayClass` that references the `GatewayConfiguration` above:
+
+   ```bash
+   kubectl apply -f - <<EOF
+   kind: GatewayClass
+   apiVersion: gateway.networking.k8s.io/v1
+   metadata:
+     name: gw-private
+   spec:
+     controllerName: konghq.com/gateway-operator
+     parametersRef:
+       group: gateway-operator.konghq.com
+       kind: GatewayConfiguration
+       name: gw-private
+       namespace: kong-gw-private
+   EOF
+   ```
+
+1. Wait for {{ site.operator_product_name }} to accept the `GatewayClass`:
+
+   ```bash
+   kubectl wait --for=condition=Accepted=True gatewayclass/gw-private --timeout=60s
+   ```
 
 ## Create a Gateway
 
diff --git a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
index 1e07c23ae1..5711d4e3dc 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
@@ -53,66 +53,85 @@ prereqs:
 
 ## Deploy a test service in each namespace
 
-Deploy the echo service in both tenant namespaces:
+1. Deploy the echo service in both tenant namespaces:
 
-```bash
-kubectl apply -f {{site.links.web}}/manifests/kic/echo-service.yaml -n kong-gw-public
-kubectl apply -f {{site.links.web}}/manifests/kic/echo-service.yaml -n kong-gw-private
-```
+   ```bash
+   kubectl apply -f {{site.links.web}}/manifests/kic/echo-service.yaml -n kong-gw-public
+   kubectl apply -f {{site.links.web}}/manifests/kic/echo-service.yaml -n kong-gw-private
+   ```
 
-## Create an HTTPRoute for the public gateway
+1. Wait for both deployments to be ready:
 
-Create an `HTTPRoute` in the `kong-gw-public` namespace pointing to the echo service:
+   ```bash
+   kubectl rollout status deployment/echo -n kong-gw-public --timeout=60s
+   kubectl rollout status deployment/echo -n kong-gw-private --timeout=60s
+   ```
 
-```bash
-kubectl apply -f - <<EOF
-kind: HTTPRoute
-apiVersion: gateway.networking.k8s.io/v1
-metadata:
-  name: echo
-  namespace: kong-gw-public
-spec:
-  parentRefs:
-  - group: gateway.networking.k8s.io
-    kind: Gateway
-    name: gw-public
-  rules:
-  - matches:
-    - path:
-        type: PathPrefix
-        value: /echo
-    backendRefs:
-    - name: echo
-      port: 1027
-EOF
-```
+## Create an HTTPRoute for the public gateway
 
-## Create an HTTPRoute for the private gateway
+1. Create an `HTTPRoute` in the `kong-gw-public` namespace pointing to the echo service:
+
+   ```bash
+   kubectl apply -f - <<EOF
+   kind: HTTPRoute
+   apiVersion: gateway.networking.k8s.io/v1
+   metadata:
+     name: echo
+     namespace: kong-gw-public
+   spec:
+     parentRefs:
+     - group: gateway.networking.k8s.io
+       kind: Gateway
+       name: gw-public
+     rules:
+     - matches:
+       - path:
+           type: PathPrefix
+           value: /echo
+       backendRefs:
+       - name: echo
+         port: 1027
+   EOF
+   ```
+
+1. Wait for the route to be accepted by the gateway:
+
+   ```bash
+   kubectl wait --for=condition=Accepted=True httproute/echo -n kong-gw-public --timeout=60s
+   ```
 
-Create an equivalent `HTTPRoute` in the `kong-gw-private` namespace:
+## Create an HTTPRoute for the private gateway
 
-```bash
-kubectl apply -f - <<EOF
-kind: HTTPRoute
-apiVersion: gateway.networking.k8s.io/v1
-metadata:
-  name: echo
-  namespace: kong-gw-private
-spec:
-  parentRefs:
-  - group: gateway.networking.k8s.io
-    kind: Gateway
-    name: gw-private
-  rules:
-  - matches:
-    - path:
-        type: PathPrefix
-        value: /echo
-    backendRefs:
-    - name: echo
-      port: 1027
-EOF
-```
+1. Create an equivalent `HTTPRoute` in the `kong-gw-private` namespace:
+
+   ```bash
+   kubectl apply -f - <<EOF
+   kind: HTTPRoute
+   apiVersion: gateway.networking.k8s.io/v1
+   metadata:
+     name: echo
+     namespace: kong-gw-private
+   spec:
+     parentRefs:
+     - group: gateway.networking.k8s.io
+       kind: Gateway
+       name: gw-private
+     rules:
+     - matches:
+       - path:
+           type: PathPrefix
+           value: /echo
+       backendRefs:
+       - name: echo
+         port: 1027
+   EOF
+   ```
+
+1. Wait for the route to be accepted by the gateway:
+
+   ```bash
+   kubectl wait --for=condition=Accepted=True httproute/echo -n kong-gw-private --timeout=60s
+   ```
 
 ## Validate
 

From 7ee988aa86c4597341cf027e52b2c5ac8b215e7e Mon Sep 17 00:00:00 2001
From: Lucie Milan <lucie.milan@konghq.com>
Date: Thu, 11 Jun 2026 15:26:17 +0200
Subject: [PATCH 3/6] debug

---
 ...perator-multi-tenancy-3-private-gateway.md |   4 +-
 .../operator-multi-tenancy-4-test-services.md | 160 +++++++++++-------
 2 files changed, 97 insertions(+), 67 deletions(-)

diff --git a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
index ada79fb82d..af6a280daa 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
@@ -98,7 +98,7 @@ EOF
 
 ## Create a Gateway
 
-Create the `Gateway` resource in the `kong-gw-private` namespace, referencing the `GatewayClass` above:
+Create the `Gateway` resource in the `kong-gw-private` namespace. The private gateway uses port 8080 to avoid a host-port conflict with the public gateway on single-node clusters (such as OrbStack, k3s, or kind) where each LoadBalancer service binds a host port.
 
 ```bash
 kubectl apply -f - <<EOF
@@ -112,7 +112,7 @@ spec:
   listeners:
   - name: http
     protocol: HTTP
-    port: 80
+    port: 8080
 EOF
 ```
 
diff --git a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
index 5711d4e3dc..ab93574253 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
@@ -69,69 +69,57 @@ prereqs:
 
 ## Create an HTTPRoute for the public gateway
 
-1. Create an `HTTPRoute` in the `kong-gw-public` namespace pointing to the echo service:
+Create an `HTTPRoute` in the `kong-gw-public` namespace pointing to the echo service:
 
-   ```bash
-   kubectl apply -f - <<EOF
-   kind: HTTPRoute
-   apiVersion: gateway.networking.k8s.io/v1
-   metadata:
-     name: echo
-     namespace: kong-gw-public
-   spec:
-     parentRefs:
-     - group: gateway.networking.k8s.io
-       kind: Gateway
-       name: gw-public
-     rules:
-     - matches:
-       - path:
-           type: PathPrefix
-           value: /echo
-       backendRefs:
-       - name: echo
-         port: 1027
-   EOF
-   ```
-
-1. Wait for the route to be accepted by the gateway:
-
-   ```bash
-   kubectl wait --for=condition=Accepted=True httproute/echo -n kong-gw-public --timeout=60s
-   ```
+```bash
+kubectl apply -f - <<EOF
+kind: HTTPRoute
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: echo
+  namespace: kong-gw-public
+spec:
+  parentRefs:
+  - group: gateway.networking.k8s.io
+    kind: Gateway
+    name: gw-public
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /echo
+    backendRefs:
+    - name: echo
+      port: 1027
+EOF
+```
 
 ## Create an HTTPRoute for the private gateway
 
-1. Create an equivalent `HTTPRoute` in the `kong-gw-private` namespace:
+Create an equivalent `HTTPRoute` in the `kong-gw-private` namespace:
 
-   ```bash
-   kubectl apply -f - <<EOF
-   kind: HTTPRoute
-   apiVersion: gateway.networking.k8s.io/v1
-   metadata:
-     name: echo
-     namespace: kong-gw-private
-   spec:
-     parentRefs:
-     - group: gateway.networking.k8s.io
-       kind: Gateway
-       name: gw-private
-     rules:
-     - matches:
-       - path:
-           type: PathPrefix
-           value: /echo
-       backendRefs:
-       - name: echo
-         port: 1027
-   EOF
-   ```
-
-1. Wait for the route to be accepted by the gateway:
-
-   ```bash
-   kubectl wait --for=condition=Accepted=True httproute/echo -n kong-gw-private --timeout=60s
-   ```
+```bash
+kubectl apply -f - <<EOF
+kind: HTTPRoute
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: echo
+  namespace: kong-gw-private
+spec:
+  parentRefs:
+  - group: gateway.networking.k8s.io
+    kind: Gateway
+    name: gw-private
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /echo
+    backendRefs:
+    - name: echo
+      port: 1027
+EOF
+```
 
 ## Validate
 
@@ -144,7 +132,7 @@ export PRIVATE_GW_IP=$(kubectl get gateway gw-private -n kong-gw-private \
   -o jsonpath='{.status.addresses[0].value}')
 ```
 
-Both gateways should respond on `/echo`:
+The public gateway listens on port 80 and the private gateway on port 8080. Both should respond on `/echo`:
 
 {% validation request-check %}
 url: /echo
@@ -156,11 +144,53 @@ konnect_url: $PUBLIC_GW_IP
 {% validation request-check %}
 url: /echo
 status_code: 200
-on_prem_url: $PRIVATE_GW_IP
-konnect_url: $PRIVATE_GW_IP
+on_prem_url: http://$PRIVATE_GW_IP:8080
+konnect_url: http://$PRIVATE_GW_IP:8080
 {% endvalidation %}
 
-<!-- GAP: There is no built-in mechanism in Kong Operator to verify that a route in namespace A
-     is NOT reachable through the gateway in namespace B. The isolation is enforced by the
-     watchNamespaces scoping (logical isolation), not by a NetworkPolicy (network-level isolation).
-     Users who need hard network-level isolation should add Kubernetes NetworkPolicy resources. -->
+## Test isolation
+
+Both gateways responding on `/echo` confirms they are running, but it does not prove isolation — both routes happen to use the same path. The following test deploys a route that only exists in `kong-gw-private` and verifies that the public gateway has no knowledge of it.
+
+Create an `HTTPRoute` for a `/private` path in `kong-gw-private` only:
+
+```bash
+kubectl apply -f - <<EOF
+kind: HTTPRoute
+apiVersion: gateway.networking.k8s.io/v1
+metadata:
+  name: private-only
+  namespace: kong-gw-private
+spec:
+  parentRefs:
+  - group: gateway.networking.k8s.io
+    kind: Gateway
+    name: gw-private
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /private
+    backendRefs:
+    - name: echo
+      port: 1027
+EOF
+```
+
+Confirm it is accessible via the private gateway:
+
+{% validation request-check %}
+url: /private
+status_code: 200
+on_prem_url: http://$PRIVATE_GW_IP:8080
+konnect_url: http://$PRIVATE_GW_IP:8080
+{% endvalidation %}
+
+Confirm it returns 404 on the public gateway:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" http://$PUBLIC_GW_IP/private
+# Expected: 404
+```
+
+The public gateway returns 404 because its in-memory KIC only watches `kong-gw-public`. The `private-only` HTTPRoute lives in `kong-gw-private`, so the public KIC never processes it and never programs it into the public DataPlane. No matter what routes are deployed in `kong-gw-private`, they are completely invisible to `gw-public` — and vice versa. This is namespace isolation working as intended.

From 739a208ab0cdb82397abc2defb520bdba84c03bc Mon Sep 17 00:00:00 2001
From: Lucie Milan <lucie.milan@konghq.com>
Date: Thu, 11 Jun 2026 17:04:39 +0200
Subject: [PATCH 4/6] fixes

---
 .../operator-multi-tenancy-1-setup.md         |  50 +++---
 ...operator-multi-tenancy-2-public-gateway.md |  56 +++----
 ...perator-multi-tenancy-3-private-gateway.md |  52 +++---
 .../operator-multi-tenancy-4-test-services.md | 121 +++++++-------
 .../kubernetes-resource/snippet.md            |   1 +
 app/operator/dataplanes/faq/license.md        |   2 +
 .../control-plane-watch-namespaces.md         |  51 +++---
 app/operator/reference/multi-tenancy.md       | 151 ++----------------
 8 files changed, 181 insertions(+), 303 deletions(-)

diff --git a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
index 09b42b4757..b2546f2cff 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
@@ -39,12 +39,14 @@ tldr:
 
 prereqs:
   skip_product: true
+  inline:
+    - title: Kong Enterprise license
+      icon_url: /assets/icons/key.svg
+      content: |
+        Save your {{site.ee_product_name}} license as `license.json` in your current working directory. If you don't have a license, contact your Kong representative.
 ---
 
-<!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces,
-     Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5 -->
-
-This guide deploys two independent {{ site.base_gateway }} instances — one public-facing, one private — on the same cluster using a single {{ site.operator_product_name }} installation. Each gateway is scoped to its own namespace so that its in-memory KIC only processes routes from that namespace.
+This series deploys two independent {{ site.base_gateway }} instances — one public-facing, one private — on the same cluster using a single {{ site.operator_product_name }} installation. Each gateway is scoped to its own namespace so that its in-memory {{ site.kic_product_name_short }} only processes routes from that namespace.
 
 The following diagram shows the end state you'll build across this series:
 
@@ -94,8 +96,6 @@ kubectl create namespace kong-gw-private
 
 ## Install {{ site.operator_product_name }}
 
-<!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces -->
-
 1. Add the Kong Helm chart repository:
 
    ```bash
@@ -116,26 +116,32 @@ kubectl create namespace kong-gw-private
    EOF
    ```
 
-## Validate
-
-Wait for {{ site.operator_product_name }} to be ready:
+1. Wait for {{ site.operator_product_name }} to be ready:
 
+{% capture validate %}
 {% include prereqs/products/operator-validate-deployment.md %}
+{% endcapture %}
+
+{{validate | indent}}
 
 ## Apply a KongLicense
 
-<!-- SOURCE: Baptiste's gist; KongLicense applied once in kong-system is shared by all Gateways -->
-<!-- GAP: This behaviour is not documented in the product docs. A single KongLicense in
-     kong-system covers all Gateways managed by this operator installation. -->
+Apply the license once in `kong-system`. It's shared by all gateways managed by this operator installation.
 
-Apply the license once in `kong-system`. It is shared by all gateways managed by this operator installation. This assumes your license file is at `./license.json`.
+1. Apply the `KongLicense`:
 
-```bash
-kubectl -n kong-system apply -f - <<EOF
-apiVersion: configuration.konghq.com/v1alpha1
-kind: KongLicense
-metadata:
-  name: kong-license
-rawLicenseString: '$(cat ./license.json)'
-EOF
-```
+   ```bash
+   echo "
+   apiVersion: configuration.konghq.com/v1alpha1
+   kind: KongLicense
+   metadata:
+     name: kong-license
+   rawLicenseString: '$(cat ./license.json)'
+   " | kubectl -n kong-system apply -f -
+   ```
+
+1. Wait for {{ site.operator_product_name }} to pick up the license:
+
+   ```bash
+   kubectl wait --for=condition=Programmed=True konglicense/kong-license --timeout=60s
+   ```
diff --git a/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
index fb4155ca41..4af2956a1e 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-2-public-gateway.md
@@ -43,16 +43,12 @@ prereqs:
   skip_product: true
 ---
 
-<!-- SOURCE: Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5,
-     GatewayConfigControlPlaneOptions in custom-resources.md,
-     control-plane-watch-namespaces.md -->
-
 ## Create a GatewayConfiguration
 
-The `controlPlaneOptions.watchNamespaces.type: own` field restricts the in-memory KIC for this gateway to watch only the `kong-gw-public` namespace. Without this, it would watch all namespaces and process routes belonging to other tenants.
+The `controlPlaneOptions.watchNamespaces.type: own` field restricts the in-memory {{ site.kic_product_name_short }} for this gateway to watch only the `kong-gw-public` namespace. Without this, it would watch all namespaces and process routes belonging to other tenants.
 
 ```bash
-kubectl apply -f - <<EOF
+echo '
 kind: GatewayConfiguration
 apiVersion: gateway-operator.konghq.com/{{ site.operator_gatewayconfiguration_api_version }}
 metadata:
@@ -69,17 +65,15 @@ spec:
   controlPlaneOptions:
     watchNamespaces:
       type: own
-EOF
+' | kubectl apply -f -
 ```
 
 ## Create a GatewayClass
 
-<!-- SOURCE: operator-get-started-gateway-api-2-create-gateway.md -->
-
 1. Create a `GatewayClass` that references the `GatewayConfiguration` above:
 
    ```bash
-   kubectl apply -f - <<EOF
+   echo '
    kind: GatewayClass
    apiVersion: gateway.networking.k8s.io/v1
    metadata:
@@ -91,7 +85,7 @@ EOF
        kind: GatewayConfiguration
        name: gw-public
        namespace: kong-gw-public
-   EOF
+   ' | kubectl apply -f -
    ```
 
 1. Wait for {{ site.operator_product_name }} to accept the `GatewayClass`:
@@ -102,27 +96,33 @@ EOF
 
 ## Create a Gateway
 
-Create the `Gateway` resource in the `kong-gw-public` namespace, referencing the `GatewayClass` above:
+1. Create the `Gateway` resource in the `kong-gw-public` namespace, referencing the `GatewayClass` above:
 
-```bash
-kubectl apply -f - <<EOF
-kind: Gateway
-apiVersion: gateway.networking.k8s.io/v1
-metadata:
-  name: gw-public
-  namespace: kong-gw-public
-spec:
-  gatewayClassName: gw-public
-  listeners:
-  - name: http
-    protocol: HTTP
-    port: 80
-EOF
-```
+   ```bash
+   echo '
+   kind: Gateway
+   apiVersion: gateway.networking.k8s.io/v1
+   metadata:
+     name: gw-public
+     namespace: kong-gw-public
+   spec:
+     gatewayClassName: gw-public
+     listeners:
+     - name: http
+       protocol: HTTP
+       port: 80
+   ' | kubectl apply -f -
+   ```
+
+1. Wait for the gateway to be programmed:
+
+   ```bash
+   kubectl wait --for=condition=Programmed=True gateway/gw-public -n kong-gw-public --timeout=120s
+   ```
 
 ## Validate
 
-Wait for the public gateway to become ready:
+Verify the public gateway was reconciled successfully:
 
 {% validation kubernetes-resource %}
 kind: Gateway
diff --git a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
index af6a280daa..dd6c157745 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-3-private-gateway.md
@@ -43,14 +43,12 @@ prereqs:
   skip_product: true
 ---
 
-<!-- SOURCE: Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5 -->
-
 ## Create a GatewayConfiguration
 
-As with the public gateway, `controlPlaneOptions.watchNamespaces.type: own` restricts the in-memory KIC to watch only the `kong-gw-private` namespace.
+As with the public gateway, `controlPlaneOptions.watchNamespaces.type: own` restricts the in-memory {{ site.kic_product_name_short }} to watch only the `kong-gw-private` namespace.
 
 ```bash
-kubectl apply -f - <<EOF
+echo '
 kind: GatewayConfiguration
 apiVersion: gateway-operator.konghq.com/{{ site.operator_gatewayconfiguration_api_version }}
 metadata:
@@ -67,7 +65,7 @@ spec:
   controlPlaneOptions:
     watchNamespaces:
       type: own
-EOF
+' | kubectl apply -f -
 ```
 
 ## Create a GatewayClass
@@ -75,7 +73,7 @@ EOF
 1. Create a `GatewayClass` that references the `GatewayConfiguration` above:
 
    ```bash
-   kubectl apply -f - <<EOF
+   echo '
    kind: GatewayClass
    apiVersion: gateway.networking.k8s.io/v1
    metadata:
@@ -87,7 +85,7 @@ EOF
        kind: GatewayConfiguration
        name: gw-private
        namespace: kong-gw-private
-   EOF
+   ' | kubectl apply -f -
    ```
 
 1. Wait for {{ site.operator_product_name }} to accept the `GatewayClass`:
@@ -98,27 +96,33 @@ EOF
 
 ## Create a Gateway
 
-Create the `Gateway` resource in the `kong-gw-private` namespace. The private gateway uses port 8080 to avoid a host-port conflict with the public gateway on single-node clusters (such as OrbStack, k3s, or kind) where each LoadBalancer service binds a host port.
+1. Create the `Gateway` resource in the `kong-gw-private` namespace. The private gateway uses port 8080 to avoid a host-port conflict with the public gateway on single-node clusters (such as OrbStack, k3s, or kind) where each LoadBalancer service binds a host port.
 
-```bash
-kubectl apply -f - <<EOF
-kind: Gateway
-apiVersion: gateway.networking.k8s.io/v1
-metadata:
-  name: gw-private
-  namespace: kong-gw-private
-spec:
-  gatewayClassName: gw-private
-  listeners:
-  - name: http
-    protocol: HTTP
-    port: 8080
-EOF
-```
+   ```bash
+   echo '
+   kind: Gateway
+   apiVersion: gateway.networking.k8s.io/v1
+   metadata:
+     name: gw-private
+     namespace: kong-gw-private
+   spec:
+     gatewayClassName: gw-private
+     listeners:
+     - name: http
+       protocol: HTTP
+       port: 8080
+   ' | kubectl apply -f -
+   ```
+
+1. Wait for the gateway to be programmed:
+
+   ```bash
+   kubectl wait --for=condition=Programmed=True gateway/gw-private -n kong-gw-private --timeout=120s
+   ```
 
 ## Validate
 
-Wait for the private gateway to become ready:
+Verify the private gateway was reconciled successfully:
 
 {% validation kubernetes-resource %}
 kind: Gateway
diff --git a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
index ab93574253..93819b9afb 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-4-test-services.md
@@ -1,5 +1,5 @@
 ---
-title: Deploy test services and validate isolation
+title: Deploy test services
 description: "Deploy a backend service and HTTPRoute in each tenant namespace, then confirm that each gateway only serves its own routes."
 content_type: how_to
 
@@ -40,7 +40,7 @@ next_steps:
 tldr:
   q: How do I verify that two gateways are isolated from each other?
   a: |
-    Deploy a backend service and `HTTPRoute` in each tenant namespace. Each in-memory KIC
+    Deploy a backend service and `HTTPRoute` in each tenant namespace. Each in-memory {{ site.kic_product_name_short }}
     is scoped to its own namespace via `watchNamespaces.type: own`, so routes in
     `kong-gw-public` are invisible to the private gateway and vice versa.
 
@@ -48,10 +48,7 @@ prereqs:
   skip_product: true
 ---
 
-<!-- SOURCE: Baptiste's gist https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5,
-     operator-get-started-gateway-api-3-create-route.md -->
-
-## Deploy a test service in each namespace
+## Deploy test services
 
 1. Deploy the echo service in both tenant namespaces:
 
@@ -72,7 +69,7 @@ prereqs:
 Create an `HTTPRoute` in the `kong-gw-public` namespace pointing to the echo service:
 
 ```bash
-kubectl apply -f - <<EOF
+echo '
 kind: HTTPRoute
 apiVersion: gateway.networking.k8s.io/v1
 metadata:
@@ -91,15 +88,15 @@ spec:
     backendRefs:
     - name: echo
       port: 1027
-EOF
+' | kubectl apply -f -
 ```
 
-## Create an HTTPRoute for the private gateway
+## Create two HTTPRoutes for the private gateway
 
-Create an equivalent `HTTPRoute` in the `kong-gw-private` namespace:
+Create two `HTTPRoute` resources in the `kong-gw-private` namespace. One is equivalent to the one in the `kong-gw-public` namespace, and the other is a `/private` path in `kong-gw-private` only:
 
 ```bash
-kubectl apply -f - <<EOF
+echo '
 kind: HTTPRoute
 apiVersion: gateway.networking.k8s.io/v1
 metadata:
@@ -118,44 +115,7 @@ spec:
     backendRefs:
     - name: echo
       port: 1027
-EOF
-```
-
-## Validate
-
-Get the external IP address for each gateway:
-
-```bash
-export PUBLIC_GW_IP=$(kubectl get gateway gw-public -n kong-gw-public \
-  -o jsonpath='{.status.addresses[0].value}')
-export PRIVATE_GW_IP=$(kubectl get gateway gw-private -n kong-gw-private \
-  -o jsonpath='{.status.addresses[0].value}')
-```
-
-The public gateway listens on port 80 and the private gateway on port 8080. Both should respond on `/echo`:
-
-{% validation request-check %}
-url: /echo
-status_code: 200
-on_prem_url: $PUBLIC_GW_IP
-konnect_url: $PUBLIC_GW_IP
-{% endvalidation %}
-
-{% validation request-check %}
-url: /echo
-status_code: 200
-on_prem_url: http://$PRIVATE_GW_IP:8080
-konnect_url: http://$PRIVATE_GW_IP:8080
-{% endvalidation %}
-
-## Test isolation
-
-Both gateways responding on `/echo` confirms they are running, but it does not prove isolation — both routes happen to use the same path. The following test deploys a route that only exists in `kong-gw-private` and verifies that the public gateway has no knowledge of it.
-
-Create an `HTTPRoute` for a `/private` path in `kong-gw-private` only:
-
-```bash
-kubectl apply -f - <<EOF
+---
 kind: HTTPRoute
 apiVersion: gateway.networking.k8s.io/v1
 metadata:
@@ -174,23 +134,66 @@ spec:
     backendRefs:
     - name: echo
       port: 1027
-EOF
+' | kubectl apply -f -
 ```
 
-Confirm it is accessible via the private gateway:
+## Validate
+
+1. Get the external IP address for each gateway:
+
+   ```bash
+   export PUBLIC_GW_IP=$(kubectl get gateway gw-public -n kong-gw-public \
+     -o jsonpath='{.status.addresses[0].value}')
+   echo $PUBLIC_GW_IP
+   export PRIVATE_GW_IP=$(kubectl get gateway gw-private -n kong-gw-private \
+     -o jsonpath='{.status.addresses[0].value}')
+   echo $PRIVATE_GW_IP
+   ```
+
+{% capture check_1 %}
+{% validation request-check %}
+url: /echo
+status_code: 200
+on_prem_url: $PUBLIC_GW_IP
+konnect_url: $PUBLIC_GW_IP
+{% endvalidation %}
+{% endcapture %}
 
+{% capture check_2 %}
+{% validation request-check %}
+url: /echo
+status_code: 200
+on_prem_url: $PRIVATE_GW_IP:8080
+konnect_url: $PRIVATE_GW_IP:8080
+{% endvalidation %}
+{% endcapture %}
+
+{% capture check_3 %}
 {% validation request-check %}
 url: /private
 status_code: 200
-on_prem_url: http://$PRIVATE_GW_IP:8080
-konnect_url: http://$PRIVATE_GW_IP:8080
+on_prem_url: $PRIVATE_GW_IP:8080
+konnect_url: $PRIVATE_GW_IP:8080
 {% endvalidation %}
+{% endcapture %}
 
-Confirm it returns 404 on the public gateway:
+{% capture check_4 %}
+{% validation request-check %}
+url: /private
+status_code: 200
+on_prem_url: $PUBLIC_GW_IP
+konnect_url: $PUBLIC_GW_IP
+{% endvalidation %}
+{% endcapture %}
 
-```bash
-curl -s -o /dev/null -w "%{http_code}\n" http://$PUBLIC_GW_IP/private
-# Expected: 404
-```
+1. The public gateway listens on port 80 and the private gateway on port 8080. Check that both return a `200` response on `/echo`:
+   
+   {{check_1 | indent}}
+   {{check_2 | indent}}
+
+1. Send a request to the Route that only exists in `kong-gw-private` to verify that the public gateway has no knowledge of it:
+
+   {{check_3 | indent}}
+   {{check_4 | indent}}
 
-The public gateway returns 404 because its in-memory KIC only watches `kong-gw-public`. The `private-only` HTTPRoute lives in `kong-gw-private`, so the public KIC never processes it and never programs it into the public DataPlane. No matter what routes are deployed in `kong-gw-private`, they are completely invisible to `gw-public` — and vice versa. This is namespace isolation working as intended.
+The public gateway returns 404 because its in-memory {{ site.kic_product_name_short }} only watches `kong-gw-public`. The `private-only` HTTPRoute lives in `kong-gw-private`, so the public {{ site.kic_product_name_short }} never processes it and never programs it into the public data plane. No matter what routes are deployed in `kong-gw-private`, they are completely invisible to `gw-public` — and vice versa. This is namespace isolation working as intended.
diff --git a/app/_includes/how-tos/validations/kubernetes-resource/snippet.md b/app/_includes/how-tos/validations/kubernetes-resource/snippet.md
index f847053a28..6d37c4d92b 100644
--- a/app/_includes/how-tos/validations/kubernetes-resource/snippet.md
+++ b/app/_includes/how-tos/validations/kubernetes-resource/snippet.md
@@ -22,3 +22,4 @@ The output should look similar to this:
   "type": "{{ conditionType }}"
 }
 ```
+{:.no-copy-code}
diff --git a/app/operator/dataplanes/faq/license.md b/app/operator/dataplanes/faq/license.md
index 02032533a1..93efe4d7df 100644
--- a/app/operator/dataplanes/faq/license.md
+++ b/app/operator/dataplanes/faq/license.md
@@ -19,6 +19,8 @@ breadcrumbs:
 
 ## KongLicense
 
+`KongLicense` is a cluster-scoped resource. A single `KongLicense` applied to the cluster is shared by all `Gateway` instances managed by that {{ site.operator_product_name }} installation, you don't need to create one per tenant or per namespace.
+
 1. Create a file named `license.json` containing your {{site.ee_product_name}} license.
 
 1. Create a `KongLicense` object with the `rawLicenseString` field set to your license:
diff --git a/app/operator/reference/control-plane-watch-namespaces.md b/app/operator/reference/control-plane-watch-namespaces.md
index f27ef83aaa..92269c4d13 100644
--- a/app/operator/reference/control-plane-watch-namespaces.md
+++ b/app/operator/reference/control-plane-watch-namespaces.md
@@ -24,24 +24,23 @@ related_resources:
     url: /operator/reference/architecture/
 ---
 
-By default, {{ site.operator_product_name }}'s `ControlPlane` watches all namespaces.
-This provides a convenient out-of-the-box experience but may not suit all production environments, especially those where multiple teams share the same cluster or in multi-tenant setups.
+By default, {{ site.operator_product_name }}'s `ControlPlane` watches all namespaces. This provides a convenient out-of-the-box experience but may not suit production environments where multiple teams share the same cluster.
 
-To limit the namespaces watched by `ControlPlane`, you can set the `watchNamespaces` field in the `ControlPlane`'s `spec`.
+You can restrict namespace watching in two ways depending on how you manage your gateways:
 
-## ControlPlane's watchNamespaces field
+* *Managed Gateways (Gateway API flow): Set `watchNamespaces` via `GatewayConfiguration.spec.controlPlaneOptions`. You do not create a `ControlPlane` directly. See [Multi-tenancy](/operator/reference/multi-tenancy/) for the full use case.
+* Direct `ControlPlane` management: Set `watchNamespaces` directly in the `ControlPlane`'s `spec`.
 
-The `spec.watchNamespaces.type` field accepts three values to control this behavior:
+## watchNamespaces types
 
-- `all` (default): Watches resources in all namespaces.
-- `own`: Watches resources only in the `ControlPlane`'s own namespace.
-- `list`: Watches resources in the `ControlPlane`'s own namespace and in the specified list of additional namespaces.
-  When using `list`, the `ControlPlane`'s own namespace is automatically added to the list of watched namespaces, because this behavior is required by {{ site.kic_product_name }}.  
-  By default, the publish service (the `Service` for the `DataPlane`, exposed by {{ site.base_gateway }}) is created in the same namespace as the `ControlPlane`.
+The `watchNamespaces.type` field accepts three values:
+
+* `all` (default): Watches resources in all namespaces.
+* `own`: Watches resources only in the `ControlPlane`'s own namespace.
+* `list`: Watches resources in the `ControlPlane`'s own namespace and in a specified list of additional namespaces. The `ControlPlane`'s own namespace is automatically included, as required by {{ site.kic_product_name }}.
 
 {:.info}
-> **Note:** Setting this field in `ControlPlane` will configure the `CONTROLLER_WATCH_NAMESPACE` environment variable in the managed {{ site.kic_product_name }}.
-> If you manually set the `CONTROLLER_WATCH_NAMESPACE` environment variable through `podTemplateSpec`, it will **override** this configuration.
+> The `watchNamespaces` setting configures the `CONTROLLER_WATCH_NAMESPACE` environment variable in the managed {{ site.kic_product_name_short }}. If you set this variable manually through `podTemplateSpec`, it will override the `watchNamespaces` field.
 
 The `all` and `own` types don't require any further changes or additional resources. The `list` type requires further configuration.
 
@@ -49,17 +48,18 @@ The `all` and `own` types don't require any further changes or additional resour
 
 The `list` type requires two additional steps:
 
-1. Specify the namespaces to watch in the `spec.watchNamespaces.list` field.
+1. Specify the namespaces to watch in the `spec.watchNamespaces.list` field:
+
    ```yaml
    spec:
      watchNamespaces:
        type: list
-        list:
-        - namespace-a
-        - namespace-b
+       list:
+       - namespace-a
+       - namespace-b
    ```
 
-1. Create a `WatchNamespaceGrant` resource in each of the specified namespaces. This resource grants the `ControlPlane` permission to watch resources in the specified namespace. It can be defined as:
+1. Create a `WatchNamespaceGrant` resource in each of the specified namespaces. This resource grants the `ControlPlane` permission to watch resources in that namespace:
 
    ```yaml
    apiVersion: gateway-operator.konghq.com/v1alpha1
@@ -76,20 +76,18 @@ The `list` type requires two additional steps:
 
 For more information on the `WatchNamespaceGrant` CRD, see the [CRD reference](/operator/reference/custom-resources/#watchnamespacegrant).
 
-## Multi-tenancy using watch namespaces {% new_in 2.0 %}
+## Operator-level namespace scoping {% new_in 2.0 %}
 
-Multi-tenancy, in the context of {{ site.operator_product_name }}, is an approach that allows multiple instances of the {{ site.operator_product_name }} to share the same underlying infrastructure while keeping their data isolated and more specifically to watch disjoint namespaces.
-
-This allows you to configure {{ site.operator_product_name }} itself to watch namespaces instead of always specifying them in the `ControlPlane` resources.
+From v2.0, you can scope {{ site.operator_product_name }} itself to watch only specific namespaces. This is separate from the per-`ControlPlane` `watchNamespaces` configuration and is useful when running multiple {{ site.operator_product_name }} instances on the same cluster with strictly disjoint namespace assignments.
 
 {:.warning}
-> **Important:** If you configure watch namespaces on both {{ site.operator_product_name }} and `ControlPlane` resources, they must be configured so that they don't conflict. For example, if the {{ site.operator_product_name }} watches namespaces A and B, the `ControlPlane` resource can only define watch namespaces A and B. If you use other watch namespaces, such as namespace C, the `ControlPlane` object will receive an appropriate status condition and won't reconcile your configuration.
+> If you configure watch namespaces on both {{ site.operator_product_name }} and `ControlPlane` resources, they must not conflict. For example, if {{ site.operator_product_name }} watches namespaces A and B, the `ControlPlane` can only define watch namespaces A or B. Using namespace C would cause the `ControlPlane` to receive a failure status condition and stop reconciling.
 
 You can set watch namespaces for {{ site.operator_product_name }} using several methods:
 
 {% navtabs "multi-tenant-namespaces" %}
 {% navtab "Helm chart" %}
-When using the `kong-operator` Helm chart, you can use the `env` top level configuration in your `values.yaml`:
+When using the `kong-operator` Helm chart, use the `env` top-level configuration in your `values.yaml`:
 
 ```yaml
 env:
@@ -102,15 +100,10 @@ KONG_OPERATOR_WATCH_NAMESPACES='namespace-a,namespace-b'
 ```
 {% endnavtab %}
 {% navtab "CLI" %}
-To specify the comma separated list of namespaces to watch you can use the `--watch-namespaces` flag:
+Use the `--watch-namespaces` flag with a comma-separated list of namespaces:
 
 ```bash
 ... --watch-namespaces namespace-a,namespace-b ...
 ```
 {% endnavtab %}
 {% endnavtabs %}
-
-
-
-
-
diff --git a/app/operator/reference/multi-tenancy.md b/app/operator/reference/multi-tenancy.md
index bd1a079e6e..9a5b5d2775 100644
--- a/app/operator/reference/multi-tenancy.md
+++ b/app/operator/reference/multi-tenancy.md
@@ -33,158 +33,27 @@ related_resources:
     url: /operator/reference/custom-resources/
 ---
 
-<!-- SOURCE: architecture.md, control-plane-watch-namespaces.md, Baptiste's gist
-     https://gist.github.com/bcollard/44caa409cdf7d796506a7a2e61a4a0d5,
-     and FEATURES.md https://github.com/Kong/kong-operator/blob/main/FEATURES.md -->
-
 Multi-tenancy in {{ site.operator_product_name }} means running multiple isolated {{ site.base_gateway }} instances — each with their own routing configuration, data plane, and namespace scope — on the same Kubernetes cluster, managed by a single {{ site.operator_product_name }} installation.
 
-Common use cases include separating a public-facing API gateway from an internal one, or giving different teams independent gateway instances without requiring separate clusters.
+Common use cases include separating a public-facing API gateway from an internal one, or giving different teams independent gateway instances without requiring separate clusters. For a step-by-step walkthrough, see [Deploy multiple isolated gateways](/operator/dataplanes/how-to/multi-tenancy/setup/).
 
 ## How it works
 
-<!-- SOURCE: managed-gateways.md, architecture.md -->
-
-Each tenant is represented by a **Gateway**, provisioned using a triptych of three resources:
+Each tenant is represented by a `Gateway`, provisioned using three resources:
 
-```
-GatewayConfiguration  ──(parametersRef)──▶  GatewayClass  ──(gatewayClassName)──▶  Gateway
-```
+* `GatewayConfiguration`: A Kong-specific resource that configures the control plane and data plane options for a gateway, such as the proxy image, environment variables, and namespace watch scope.
+* `GatewayClass`: A cluster-scoped Gateway API resource that registers {{ site.operator_product_name }} as the controller for gateways of this class. It references the `GatewayConfiguration` via `parametersRef`.
+* `Gateway`: A namespaced Gateway API resource that declares a gateway instance. It references the `GatewayClass` via `gatewayClassName`, which is how {{ site.operator_product_name }} associates it with the correct `GatewayConfiguration`.
 
 For each `Gateway`, {{ site.operator_product_name }} creates:
 
-- One **in-memory KIC instance** embedded inside the {{ site.operator_product_name }} pod (not a separately deployed pod), which watches Gateway API resources and translates them into Kong configuration.
-- One **DataPlane deployment** running {{ site.base_gateway }} in DB-less mode.
+* One in-memory {{ site.kic_product_name_short }} instance embedded inside the {{ site.operator_product_name }} Pod, which watches Gateway API resources and translates them into Kong configuration.
+* One*data plane deployment running {{ site.base_gateway }} in DB-less mode.
 
-Multiple `Gateway` resources can coexist in the same cluster. The resulting in-memory KIC instances and DataPlane pods are independent of each other. A single {{ site.operator_product_name }} installation manages them all.
+Multiple `Gateway` resources can coexist in the same cluster. The resulting in-memory {{ site.kic_product_name_short }} instances and data plane Pods are independent of each other. A single {{ site.operator_product_name }} installation manages them all.
 
 ## Namespace isolation
 
-<!-- SOURCE: control-plane-watch-namespaces.md -->
-
-By default, each in-memory KIC instance watches **all namespaces** for Gateway API resources (`HTTPRoute`, `GRPCRoute`, etc.). This means, without additional configuration, one tenant's KIC would also process another tenant's routes. Namespace isolation is therefore required for multi-tenancy.
-
-The `watchNamespaces` field on `GatewayConfiguration.spec.controlPlaneOptions` controls which namespaces the in-memory KIC for each `Gateway` will watch.
-
-<!-- GAP: The control-plane-watch-namespaces.md page documents the ControlPlane CRD field directly,
-     but does not explain that it must be set via GatewayConfiguration.spec.controlPlaneOptions
-     when using managed Gateways (i.e., the normal Gateway API flow). Users following that page
-     alone would not know how to apply the setting in practice. -->
-
-### watchNamespaces types
-
-<!-- SOURCE: control-plane-watch-namespaces.md, custom-resources.md WatchNamespacesType -->
-
-The `watchNamespaces.type` field accepts three values:
-
-{% table %}
-columns:
-  - title: Type
-    key: type
-  - title: Behavior
-    key: behavior
-  - title: Use when
-    key: use
-rows:
-  - type: "`all`"
-    behavior: Watches all namespaces (default)
-    use: Single-tenant or dev environments
-  - type: "`own`"
-    behavior: Watches only the `ControlPlane`'s own namespace
-    use: One namespace per tenant (recommended)
-  - type: "`list`"
-    behavior: Watches own namespace plus a specified list
-    use: Routes for this tenant span multiple namespaces
-{% endtable %}
-
-When using `list`, the ControlPlane's own namespace is automatically included. Each additional namespace in the list requires a `WatchNamespaceGrant` resource in that namespace (see [WatchNamespaceGrant](#watchnamespacegrant)).
-
-{:.info}
-> Setting `watchNamespaces` via `GatewayConfiguration.spec.controlPlaneOptions` configures the `CONTROLLER_WATCH_NAMESPACE` environment variable in the managed KIC. If you set this variable manually through `podTemplateSpec`, it will override the `watchNamespaces` field.
-
-## Operator-level namespace scoping {% new_in 2.0 %}
-
-<!-- SOURCE: control-plane-watch-namespaces.md#multi-tenancy-using-watch-namespaces -->
-
-From v2.0, you can scope {{ site.operator_product_name }} itself to watch only specific namespaces. This is separate from the per-`ControlPlane` `watchNamespaces` configuration and is useful when running multiple {{ site.operator_product_name }} instances on the same cluster with strictly disjoint namespace assignments.
-
-Configure operator-level watch namespaces using the `watch_namespace` Helm value:
-
-```yaml
-# values.yaml
-env:
-  watch_namespace: namespace-a,namespace-b
-```
-
-Or via environment variable:
-
-```sh
-KONG_OPERATOR_WATCH_NAMESPACES='namespace-a,namespace-b'
-```
-
-{:.warning}
-> If both operator-level and `ControlPlane`-level watch namespaces are configured, they must not conflict. For example, if {{ site.operator_product_name }} watches namespaces A and B, a `ControlPlane` may only define watch namespaces A or B. Using namespace C would cause the `ControlPlane` to receive a failure status condition and stop reconciling.
-
-## WatchNamespaceGrant
-
-<!-- SOURCE: control-plane-watch-namespaces.md, custom-resources.md WatchNamespaceGrant -->
-
-When `watchNamespaces.type` is `list`, a `WatchNamespaceGrant` resource must be created in each additional namespace (beyond the ControlPlane's own). This resource explicitly grants the named `ControlPlane` permission to watch resources in that namespace.
-
-```yaml
-apiVersion: gateway-operator.konghq.com/v1alpha1
-kind: WatchNamespaceGrant
-metadata:
-  name: watch-namespace-grant
-  namespace: target-namespace       # the namespace being granted access to
-spec:
-  from:
-  - group: gateway-operator.konghq.com
-    kind: ControlPlane
-    namespace: control-plane-namespace  # the namespace where the ControlPlane lives
-```
-
-For the full field reference, see [WatchNamespaceGrant](/operator/reference/custom-resources/#watchnamespacegrant).
-
-## KongLicense
-
-<!-- SOURCE: Baptiste's docx feedback; confirmed by gist showing license applied once to kong-system -->
-<!-- GAP: Not explicitly documented anywhere that one KongLicense in kong-system covers all Gateways. -->
-
-A single `KongLicense` applied in the `kong-system` namespace (where {{ site.operator_product_name }} is installed) is shared by all `Gateway` instances managed by that operator. You do not need to create a license per tenant.
-
-```yaml
-apiVersion: configuration.konghq.com/v1alpha1
-kind: KongLicense
-metadata:
-  name: kong-license
-  namespace: kong-system
-rawLicenseString: '<your license JSON>'
-```
-
-## Recommended namespace layout
-
-<!-- SOURCE: Baptiste's gist and docx feedback -->
+By default, each in-memory {{ site.kic_product_name_short }} instance watches all namespaces for Gateway API resources (`HTTPRoute`, `GRPCRoute`, etc.). Without additional configuration, one tenant's {{ site.kic_product_name_short }} would also process another tenant's routes, so namespace isolation is required for multi-tenancy.
 
-The recommended pattern for namespace-per-tenant isolation:
-
-{% table %}
-columns:
-  - title: Namespace
-    key: namespace
-  - title: Contents
-    key: contents
-rows:
-  - namespace: "`kong-system`"
-    contents: "{{ site.operator_product_name }} pod, `KongLicense`"
-  - namespace: "`kong-gw-public`"
-    contents: "`GatewayConfiguration`, `GatewayClass`, `Gateway`, `DataPlane` pod, `HTTPRoute`s, upstream services for the public gateway"
-  - namespace: "`kong-gw-private`"
-    contents: Same triptych for the private gateway, in isolation
-{% endtable %}
-
-Each namespace is an independent routing domain. The in-memory KIC for `kong-gw-public` only sees routes in `kong-gw-public`; the KIC for `kong-gw-private` only sees routes in `kong-gw-private`.
-
-<!-- GAP: There is no guidance on RBAC / NetworkPolicy to further harden tenant boundaries.
-     For example, whether teams should have RBAC limited to their own namespace,
-     or whether DataPlane pods need NetworkPolicy rules to prevent cross-namespace traffic. -->
+Set `watchNamespaces` on `GatewayConfiguration.spec.controlPlaneOptions` to restrict each gateway's in-memory {{ site.kic_product_name_short }} to its own namespace. For the full field reference, type options, `WatchNamespaceGrant` configuration, and operator-level scoping, see [Limiting namespaces watched by ControlPlane](/operator/reference/control-plane-watch-namespaces/).
\ No newline at end of file

From 57b77bcbc530346ae855625a59cffa97189d8f8f Mon Sep 17 00:00:00 2001
From: Lucie Milan <lucie.milan@konghq.com>
Date: Thu, 11 Jun 2026 17:08:20 +0200
Subject: [PATCH 5/6] fixes

---
 app/operator/dataplanes/faq/license.md                   | 2 +-
 app/operator/reference/control-plane-watch-namespaces.md | 4 ++--
 app/operator/reference/multi-tenancy.md                  | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/app/operator/dataplanes/faq/license.md b/app/operator/dataplanes/faq/license.md
index 93efe4d7df..dd9217edeb 100644
--- a/app/operator/dataplanes/faq/license.md
+++ b/app/operator/dataplanes/faq/license.md
@@ -75,7 +75,7 @@ breadcrumbs:
     kubectl create secret generic kong-enterprise-license --from-file=license=./license.json -n default
     ```
 
-1. Specify the `KONG_LICENSE_DATA` environment variable for your DataPlane pods. This can be provided on the `DataPlane` or `GatewayConfiguration`
+1. Specify the `KONG_LICENSE_DATA` environment variable for your DataPlane pods. This can be provided on the `DataPlane` or `GatewayConfiguration`.
 
 ### DataPlane
 
diff --git a/app/operator/reference/control-plane-watch-namespaces.md b/app/operator/reference/control-plane-watch-namespaces.md
index 92269c4d13..f4c964e32b 100644
--- a/app/operator/reference/control-plane-watch-namespaces.md
+++ b/app/operator/reference/control-plane-watch-namespaces.md
@@ -28,10 +28,10 @@ By default, {{ site.operator_product_name }}'s `ControlPlane` watches all namesp
 
 You can restrict namespace watching in two ways depending on how you manage your gateways:
 
-* *Managed Gateways (Gateway API flow): Set `watchNamespaces` via `GatewayConfiguration.spec.controlPlaneOptions`. You do not create a `ControlPlane` directly. See [Multi-tenancy](/operator/reference/multi-tenancy/) for the full use case.
+* Managed Gateways (Gateway API flow): Set `watchNamespaces` via `GatewayConfiguration.spec.controlPlaneOptions`. You do not create a `ControlPlane` directly. See [Multi-tenancy](/operator/reference/multi-tenancy/) for the full use case.
 * Direct `ControlPlane` management: Set `watchNamespaces` directly in the `ControlPlane`'s `spec`.
 
-## watchNamespaces types
+## `watchNamespaces` types
 
 The `watchNamespaces.type` field accepts three values:
 
diff --git a/app/operator/reference/multi-tenancy.md b/app/operator/reference/multi-tenancy.md
index 9a5b5d2775..8774022971 100644
--- a/app/operator/reference/multi-tenancy.md
+++ b/app/operator/reference/multi-tenancy.md
@@ -48,7 +48,7 @@ Each tenant is represented by a `Gateway`, provisioned using three resources:
 For each `Gateway`, {{ site.operator_product_name }} creates:
 
 * One in-memory {{ site.kic_product_name_short }} instance embedded inside the {{ site.operator_product_name }} Pod, which watches Gateway API resources and translates them into Kong configuration.
-* One*data plane deployment running {{ site.base_gateway }} in DB-less mode.
+* One data plane deployment running {{ site.base_gateway }} in DB-less mode.
 
 Multiple `Gateway` resources can coexist in the same cluster. The resulting in-memory {{ site.kic_product_name_short }} instances and data plane Pods are independent of each other. A single {{ site.operator_product_name }} installation manages them all.
 

From e18aa272a12f53c64410a42d4a03c44461d8db45 Mon Sep 17 00:00:00 2001
From: Lucie Milan <lucie.milan@konghq.com>
Date: Thu, 11 Jun 2026 17:09:44 +0200
Subject: [PATCH 6/6] Update operator-multi-tenancy-1-setup.md

---
 app/_how-tos/operator/operator-multi-tenancy-1-setup.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
index b2546f2cff..3892ef6406 100644
--- a/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
+++ b/app/_how-tos/operator/operator-multi-tenancy-1-setup.md
@@ -40,7 +40,7 @@ tldr:
 prereqs:
   skip_product: true
   inline:
-    - title: Kong Enterprise license
+    - title: "{{site.ee_product_name}} license"
       icon_url: /assets/icons/key.svg
       content: |
         Save your {{site.ee_product_name}} license as `license.json` in your current working directory. If you don't have a license, contact your Kong representative.