Kong Operator 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.
Cross namespace references
Uses:
Kong Operator
Related Documentation
Minimum Version
Kong Operator - 2.1
ControlPlane configuration v2.1+
When configuring a KonnectGatewayControlPlane, you can reference it from entities defined in a different namespace.
This reference can be done via the spec.controlPlaneRef.konnectNamespacedRef.namespace field, by specifying the namespace of the KonnectGatewayControlPlane resource.
apiVersion: configuration.konghq.com/v1alpha1
kind: KongService
metadata:
name: my-service
namespace: default
spec:
name: service-1
host: example.com
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: my-control-plane
namespace: kongIn order to protect cross namespace references, the KonnectGatewayControlPlane resource must explicitly allow references from other namespaces by specifying KongReferenceGrant resources.
apiVersion: configuration.konghq.com/v1alpha1
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-planeCertificate configuration v2.1+
When configuring KongCertificate and KongCACertificate objects, you can reference Secret resources containing the actual certificate data in a different namespace.
You can do this with the spec.secretRef.namespace and spec.secretRefAlt.namespace fields, by specifying the namespace of the Secret resource:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongCertificate
metadata:
name: dual-cert-cross-namespace
namespace: default
spec:
type: secretRef
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: my-control-plane
# Primary certificate (RSA) - cross-namespace reference
secretRef:
name: rsa-tls-secret
namespace: tls-secrets-namespace
# Alternative certificate (ECDSA) - cross-namespace reference
secretRefAlt:
name: ecdsa-tls-secret
namespace: tls-secrets-namespaceIn order to protect cross-namespace references, the Secret resource must explicitly allow references from other namespaces using KongReferenceGrant resources:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
name: allow-kongcertificate-to-secret
namespace: tls-secrets-namespace
spec:
from:
- group: configuration.konghq.com
kind: KongCertificate
namespace: default
to:
- group: core
kind: Secret
# Optionally specify a specific Secret name to allow
# only this specific resource to be referenced.
# name: my-secret-nameKongPlugin configuration v2.1+
When configuring KongPluginBinding to bind targets to an existing KongPlugin, you can reference KongPlugin resources in a different namespace.
You can do this with the spec.pluginRef.namespace field, by specifying the namespace of the KongPlugin resource:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
name: plugin-binding-kongservice
namespace: default
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: demo-cp
pluginRef:
name: rate-limit-5-min
namespace: ns-plugin
targets:
serviceRef:
name: service-1
kind: KongService
group: configuration.konghq.comIn order to protect cross-namespace references, the KongPlugin resource must explicitly allow references from other namespaces using KongReferenceGrant resources:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
name: allow-kongpluginbinding-to-kongplugin
namespace: ns-plugin
spec:
from:
- group: configuration.konghq.com
kind: KongPluginBinding
namespace: default
to:
- group: configuration.konghq.com
kind: KongPlugin
# Optionally specify a specific KongPlugin name to allow
# only this specific resource to be referenced.
# name: my-plugin-nameKongRoute configuration v2.1+
When configuring KongRoute to bind to a KongService, you can reference KongService in a different namespace.
You can do this with the spec.serviceRef.namespacedRef.namespace field, by specifying the namespace of the KongService resource:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
name: my-route
namespace: default
spec:
name: route-1
protocols:
- http
hosts:
- example.com
serviceRef:
type: namespacedRef
namespacedRef:
name: my-service-name
namespace: service-namespaceIn order to protect cross-namespace references, the KongPlugin resource must explicitly allow references from other namespaces using KongReferenceGrant resources:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
name: allow-kongroute-to-kongservice
namespace: service-namespace
spec:
from:
- group: configuration.konghq.com
kind: KongRoute
namespace: default
to:
- group: configuration.konghq.com
kind: KongService
# Optionally specify a specific KongService name to allow
# only this specific resource to be referenced.
# name: my-service-nameKonnect authentication configuration v2.3+
When configuring a KonnectAPIAuthConfiguration with spec.type: secretRef, you can reference the Secret holding the Konnect token in a different namespace.
You can do this with the spec.secretRef.namespace field, by specifying the namespace of the Secret resource:
apiVersion: konnect.konghq.com/v1alpha1
kind: KonnectAPIAuthConfiguration
metadata:
name: konnect-api-auth
namespace: default
spec:
type: secretRef
secretRef:
name: konnect-api-auth-secret
namespace: auth
serverURL: us.api.konghq.comIn order to protect cross-namespace references, the Secret resource must explicitly allow references from other namespaces using KongReferenceGrant resources:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
name: allow-konnectapiauthconfiguration-to-secret
namespace: auth
spec:
from:
- group: konnect.konghq.com
kind: KonnectAPIAuthConfiguration
namespace: default
to:
- group: core
kind: Secret
# Optionally specify a specific Secret name to allow
# only this specific resource to be referenced.
# name: konnect-api-auth-secretWithout a valid grant, the KonnectAPIAuthConfiguration reports ResolvedRefs=False with reason RefNotPermitted and APIAuthValid=False. Once a permitting KongReferenceGrant is created, the object is reconciled and the reference becomes valid.
Vault Config Store configuration v2.3+
When configuring a KongVault with spec.backend: konnect, you can reference the KonnectConfigStore that backs the
Vault instead of copying the Konnect Config Store ID into spec.config.config_store_id.
You can do this with the spec.configStoreRef field. KongVault is cluster-scoped and KonnectConfigStore is
namespaced, so spec.configStoreRef.namespace is required and the reference always crosses a namespace boundary:
apiVersion: configuration.konghq.com/v1alpha1
kind: KongVault
metadata:
name: certvault
spec:
backend: konnect
prefix: certvault
configStoreRef:
kind: KonnectConfigStore
name: cert-keys
namespace: kong
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: my-control-plane
namespace: kongIn order to protect cross-namespace references, the KonnectConfigStore resource must explicitly allow references from
other namespaces using KongReferenceGrant resources. Because a KongVault is cluster-scoped and has no namespace of
its own, the from entry must set namespace: "":
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
name: allow-kongvault-to-konnect-config-store
namespace: kong
spec:
from:
- group: configuration.konghq.com
kind: KongVault
namespace: ""
to:
- group: konnect.konghq.com
kind: KonnectConfigStore
# Optionally specify a specific KonnectConfigStore name to allow
# only this specific resource to be referenced.
# name: cert-keysWithout a valid grant, the KongVault reports ConfigStoreRefValid=False with reason RefNotPermitted and isn’t
pushed to Konnect, so that a Vault is never created with a missing Config Store ID. If the grant is
removed after the KongVault has been programmed, subsequent updates stop, but the Vault that already exists in
Konnect isn’t rolled back or removed.
The denial is reported on ConfigStoreRefValid rather than on ResolvedRefs, which the control plane reference already
uses for this resource.
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:
kg kongservice -n kong service-1 -o jsonpath-as-json="{ .status.conditions[?(@.type=='ResolvedRefs')]}"[
{
"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"
}
]