KonnectExtension

Kong data plane instances can be configured in Konnect using the KonnectExtension resource. This resource can be used to provision isolated DataPlane resources (Hybrid mode) or pairs of ControlPlane and DataPlane resources (Kong Ingress Controller mode).

The KonnectExtension resource can be referenced by ControlPlane, DataPlane, or GatewayConfiguration resources from the extension point in their spec. Dedicated guides will guide you through these kinds of setup.

KonnectExtension can be attached to Konnect ControlPlane resources of type Hybrid or KIC. This reference can be performed via Kubernetes object reference to an in cluster KonnectGatewayControlPlane.

Reference by Kubernetes object

The KonnectExtension can reference an object in the cluster. This reference allows to attach the DataPlane resources to the Konnect control plane via a local object (a.k.a. KonnectGatewayControlPlane). When this type of reference is used, the KonnectAPIAuthConfiguration data is inferred by the KonnectGatewayControlPlane objects. For this reason, it’s not possible to set the konnect.configuration.authref field in this scenario.

spec:
  konnect:
    controlPlane:
      ref:
        type: konnectNamespacedRef
        konnectNamespacedRef:
          name: gateway-control-plane # The KonnectGatewayControlPlane resource name

The DataPlane, in order to be configured in Konnect, needs a client certificate. This certificate can be manually created and managed by the user, or automatically provisioned by Kong Operator.

Manual certificate provisioning

In order to manually create and set up a certificate to be used for Konnect DataPlane resources, you can run the following commands:

1. Generate a new certificate and key:

   openssl req -new -x509 -nodes -newkey rsa:2048 -subj "/CN=kongdp/C=US" -keyout ./tls.key -out ./tls.crt

   Copied!

2. Create a Kubernetes secret that contains the previously created certificate:

   kubectl create secret tls konnect-client-tls --cert=./tls.crt --key=./tls.key

   Copied!

3. Label the Secret with KO’s Secret label selector (default: konghq.com/secret):

   kubectl label secret konnect-client-tls konghq.com/secret=true

   Copied!

4. Label the Secret to tell Kong Operator’s KonnectExtension controller to reconcile it:

   kubectl label secret konnect-client-tls konghq.com/konnect-dp-cert=true

   Copied!

Once the Secret containing your certificate has been created in the cluster, you can set up your KonnectExtension as follows:

spec:
  clientAuth:
    certificateSecret:
      provisioning: Manual
        secretRef:
          name: konnect-client-tls # The name of the secret containing your certificate

Automatic certificate provisioning

Alternatively, you can leave the certificate provisioning and management to Kong Operator, which will take care of creating a new certificate, write it into a Kubernetes Secret and manage the Secret’s lifecycle on behalf of you. To do so, you can configure a KonnectExtension as follows:

spec:
  clientAuth:
    certificateSecret:
      provisioning: Automatic

or you can just leave the spec.clientAuth field empty, and the automatic provisioning will be used as the default value.

Multiple labels can be configured to the Konnect DataPlane via the following field:

spec:
  konnect:
    dataPlane:
      foo: bar
      foo2: bar2

Please note that the amount of labels that can be set on DataPlane resources via KonnectExtension is limited to 5.

When a DataPlane, ControlPlane, or GatewayConfiguration resource successfully references a KonnectExtension, Kong Operator records the association on the KonnectExtension status, not on the referencing resource. Check the KonnectExtension status to confirm the reference was accepted:

kubectl get konnectextensions.konnect.konghq.com -n kong

A KonnectExtension that’s fully reconciled shows READY: True:

NAME                 READY
my-konnect-config    True

For more detail, inspect the full status block:

kubectl get konnectextension my-konnect-config -n kong -o yaml | yq '.status'

The status includes:

• conditions: The current reconciliation conditions for the extension.
• dataPlaneRefs and controlPlaneRefs: The DataPlane and ControlPlane resources that currently reference this extension. If the resource you expect to see referenced here is missing, double-check that its spec.extensions block correctly names the KonnectExtension.
• dataPlaneClientAuth: The state of the client certificate used to authenticate the DataPlane with Konnect.
• konnect.controlPlaneID and konnect.clusterType: The ID and cluster type of the Konnect control plane this extension resolves to.

A GatewayConfiguration doesn’t add its own entry to dataPlaneRefs or controlPlaneRefs. Those only track DataPlane and ControlPlane resources directly. To confirm a GatewayConfiguration accepted a KonnectExtension, check that the DataPlane and ControlPlane resources it provisions show up under the extension’s dataPlaneRefs and controlPlaneRefs, and that the GatewayConfiguration’s status.conditions don’t report an extension resolution error.

For more information, see Status fields.

If a KonnectExtension is attached and the Gateway or DataPlane deployed successfully, but the data plane still isn’t showing up as connected in Konnect, check the following:

1. Confirm the extension is actually referenced. The DataPlane (or the Gateway/GatewayConfiguration that provisions it) must list the KonnectExtension under spec.extensions, matching on group, kind, and name. A typo or namespace mismatch means the reference is silently ignored.
2. Check the KonnectExtension status. Run kubectl get konnectextensions.konnect.konghq.com -n <namespace> and confirm READY is True. If it’s False, inspect status.conditions for the failure reason.
3. Verify the referenced control plane exists and is programmed. If you’re using a konnectNamespacedRef, confirm the referenced KonnectGatewayControlPlane shows PROGRAMMED: True:

   kubectl get konnectgatewaycontrolplanes.konnect.konghq.com -n <namespace>

   Copied!
4. Check the client certificate. If you’re using manual certificate provisioning, confirm the Secret referenced in spec.clientAuth.certificateSecret.secretRef exists and contains a valid certificate and key. If you’re using automatic provisioning, confirm Kong Operator was able to create and write the Secret. Check status.dataPlaneClientAuth on the KonnectExtension.
5. Confirm outbound network access. Data planes using the ControlPlane (hybrid) cluster type connect to Konnect over an outbound WebSocket (WSS) connection on port 443. If your cluster is behind a proxy or firewall, make sure outbound HTTPS/WSS traffic to your Konnect region’s endpoint is allowed.
6. Check the data plane and operator pod logs. Look in the DataPlane container logs for TLS handshake or connectivity errors, and in the kong-operator-controller-manager logs for reconciliation failures related to the KonnectExtension or its control plane reference.