Set Konnect labels on control planes and data planes with Kong Operator

TL;DR

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

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

  1. 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.
  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

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=true

If 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.

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 plane
  • konghq.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=5m

Create 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=10m

Kong 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

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.

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.

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:

  • KonnectGatewayControlPlaneProgrammed for the konghq.com/konnect-cp-labels annotation
  • KonnectExtensionReady for the konghq.com/konnect-dp-labels annotation

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.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!