helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.4 \
--set env.ENABLE_CONTROLLER_KONNECT=true
kubectl -n kong-system wait --for=condition=Available=true --timeout=300s deployment/kong-operator-kong-operator-controller-managerSet Konnect labels on control planes and data planes with Kong Operator
Add the konghq.com/konnect-cp-labels and konghq.com/konnect-dp-labels annotations to your Gateway or GatewayClass resources, using the format key1=value1,key2=value2. When both resources set the same key, the Gateway value takes precedence.
Prerequisites
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
Kong Operator running
If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:
--set global.webhooks.options.certManager.enabled=trueIf you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates.
Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane.
This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the certificateAuthority section
in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.
Create a KonnectAPIAuthConfiguration resource
kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
name: konnect-api-auth
namespace: kong
spec:
type: token
token: "'$KONNECT_TOKEN'"
serverURL: us.api.konghq.com
' | kubectl apply -f -Konnect labels are key-value pairs that you can attach to control planes and data plane nodes to organize and filter them. To label the control plane and data plane nodes of a hybrid Gateway, add the following annotations to the Gateway or its GatewayClass:
konghq.com/konnect-cp-labels: Labels for the control planekonghq.com/konnect-dp-labels: Labels for the data plane nodes
Each annotation takes a comma-separated list of key=value pairs, for example env=prod,team=platform. Labels on a GatewayClass apply to every Gateway that uses the class. When both set the same key, the Gateway value takes precedence. For limits and requirements, see Labels on hybrid Gateways.
Create the GatewayConfiguration and GatewayClass resources
Create a GatewayConfiguration resource with your Konnect authentication:
echo '
kind: GatewayConfiguration
apiVersion: gateway-operator.konghq.com/v2beta1
metadata:
name: hybrid
namespace: kong
spec:
konnect:
authRef:
name: konnect-api-auth
dataPlaneOptions:
deployment:
podTemplateSpec:
spec:
containers:
- name: proxy
image: kong/kong-gateway:3.16
' | kubectl apply -f -Create a GatewayClass resource that references the GatewayConfiguration. The annotations on the GatewayClass define default labels for all Gateway resources that use the class:
echo '
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: hybrid
namespace: kong
annotations:
konghq.com/konnect-cp-labels: env=dev,team=platform
konghq.com/konnect-dp-labels: env=dev,region=us-west
spec:
controllerName: konghq.com/gateway-operator
parametersRef:
group: gateway-operator.konghq.com
kind: GatewayConfiguration
name: hybrid
namespace: kong
' | kubectl apply -f -Wait for the GatewayClass to be accepted:
kubectl wait gatewayclass/hybrid \
--for=condition=Accepted=True \
--timeout=5mCreate a Gateway that overrides labels
Create a Gateway resource that references the GatewayClass. The Gateway annotations override the env label from the GatewayClass and add an owner label to the control plane:
echo '
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: hybrid
namespace: kong
annotations:
konghq.com/konnect-cp-labels: env=prod,owner=payments
konghq.com/konnect-dp-labels: env=prod
spec:
gatewayClassName: hybrid
listeners:
- name: http
protocol: HTTP
port: 80
' | kubectl apply -f -Wait for the Gateway to be programmed:
kubectl wait gateway/hybrid -n kong \
--for=condition=Programmed=True \
--timeout=10mKong Operator merges the labels from the GatewayClass and the Gateway, and applies the following labels in Konnect:
|
Resource |
Labels |
|---|---|
| Control plane |
env: prod, team: platform, owner: payments
|
| Data plane nodes |
env: prod, region: us-west
|
Kong Operator keeps the labels in sync with the annotations. If you change the annotations on the Gateway or GatewayClass later, Kong Operator updates the labels in Konnect.
Validate
To check the control plane labels, fetch the control planes that have the owner: payments label in Konnect:
curl -X GET "https://us.api.konghq.com/v2/control-planes?labels=owner:payments" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN"The response contains the control plane that Kong Operator created for the Gateway, with the env: prod, team: platform, and owner: payments labels in its labels field.
To check the data plane labels, get the labels from the KonnectExtension that Kong Operator created for the Gateway:
kubectl get konnectextension -n kong -o jsonpath='{.items[*].spec.konnect.dataPlane.labels}'The command returns the following output:
{"env":"prod","region":"us-west"}The data plane nodes connected to the control plane show the same labels in Konnect.
FAQs
How many labels can I set, and which keys and values are allowed?
Each annotation can contain at most 5 labels on the Gateway and 5 on the GatewayClass, and the merged result can’t exceed 5 labels. Keys and values can’t contain , or =, and some key prefixes are reserved. For the full list of limitations and requirements, see Labels on hybrid Gateways.
Can I set labels on an existing control plane?
No. If your GatewayConfiguration uses an existing control plane (spec.konnect.source: Mirror), Kong Operator doesn’t manage that control plane, so it ignores the konghq.com/konnect-cp-labels annotation. The konghq.com/konnect-dp-labels annotation still applies to the data plane nodes.
Why aren’t my labels applied in Konnect?
If an annotation is malformed, contains too many labels, or contains an invalid key or value, Kong Operator doesn’t apply any labels from that annotation and sets the Programmed condition of the Gateway to False. Kong Operator reports the error in one of the following Gateway conditions, with the reason InvalidKonnectLabels:
KonnectGatewayControlPlaneProgrammedfor thekonghq.com/konnect-cp-labelsannotationKonnectExtensionReadyfor thekonghq.com/konnect-dp-labelsannotation
For example, if the Gateway sets 6 control plane labels, the Gateway has the following condition:
{
"lastTransitionTime": "2026-10-30T10:15:42Z",
"message": "invalid konghq.com/konnect-cp-labels annotation: Gateway kong/hybrid: too many labels: 6 exceeds the maximum of 5",
"observedGeneration": 2,
"reason": "InvalidKonnectLabels",
"status": "False",
"type": "KonnectGatewayControlPlaneProgrammed"
}Kong Operator doesn’t retry the Gateway while the annotation is invalid. Fix the annotation on the Gateway or GatewayClass to trigger a new reconciliation.