Limiting namespaces watched by ControlPlane

By default, Kong Operator’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.

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 for the full use case.
• Direct ControlPlane management: Set watchNamespaces directly in the ControlPlane’s spec.

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 Kong Ingress Controller.

The watchNamespaces setting 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.

The all and own types don’t require any further changes or additional resources. The list type requires further configuration.

The list type requires two additional steps:

1. Specify the namespaces to watch in the spec.watchNamespaces.list field:

   spec:
     watchNamespaces:
       type: list
       list:
       - namespace-a
       - namespace-b

   Copied!

2. Create a WatchNamespaceGrant resource in each of the specified namespaces. This resource grants the ControlPlane permission to watch resources in that namespace:

   apiVersion: gateway-operator.konghq.com/v1alpha1
   kind: WatchNamespaceGrant
   metadata:
     name: watch-namespace-grant
     namespace: namespace-a
   spec:
     from:
     - group: gateway-operator.konghq.com
       kind: ControlPlane
       namespace: control-plane-namespace

   Copied!

For more information on the WatchNamespaceGrant CRD, see the CRD reference.

From v2.0, you can scope Kong Operator itself to watch only specific namespaces. This is separate from the per-ControlPlane watchNamespaces configuration and is useful when running multiple Kong Operator instances on the same cluster with strictly disjoint namespace assignments.

If you configure watch namespaces on both Kong Operator and ControlPlane resources, they must not conflict. For example, if Kong Operator 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 Kong Operator using several methods:

env:
  watch_namespace: namespace-a,namespace-b

KONG_OPERATOR_WATCH_NAMESPACES='namespace-a,namespace-b'

... --watch-namespaces namespace-a,namespace-b ...