Key and Key Set

In this guide you’ll learn how to use the KongKey and KongKeySet custom resources to manage Kong Konnect keys and key sets natively from your Kubernetes cluster.

Before you create any Konnect entity, make sure you've installed Kong Gateway Operator and created a valid KonnectAPIAuthConfiguration and KonnectGatewayControlPlane in your cluster.

Prerequisites

Install Kong Gateway Operator

Update the Helm repository:

helm repo add kong https://charts.konghq.com
helm repo update kong

Install Kong Gateway Operator with Helm:

helm upgrade --install kgo kong/gateway-operator -n kong-system --create-namespace --set image.tag=1.4 \
  --set kubernetes-configuration-crds.enabled=true \
  --set env.ENABLE_CONTROLLER_KONNECT=true

You can wait for the operator to be ready using kubectl wait:

kubectl -n kong-system wait --for=condition=Available=true --timeout=120s deployment/kgo-gateway-operator-controller-manager

Create an access token in Konnect

You may create either a Personal Access Token (PAT) or a Service Account Token (SAT) in Konnect. Please refer to the Konnect authentication documentation for more information. You will need this token to create a KonnectAPIAuthConfiguration object that will be used by the Kong Gateway Operator to authenticate with Konnect APIs.

Create a Kong Konnect API auth configuration

Depending on your preferences, you can create a KonnectAPIAuthConfiguration object with the token specified directly in its spec or as a reference to a Kubernetes Secret. The serverURL field should be set to the Konnect API URL in a region where your Kong Konnect account is located. Please refer to the list of available API URLs for more information.

Directly in specification

Stored in a Secret

echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: konnect-api-auth
  namespace: default
spec:
  type: token
  token: kpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  serverURL: us.api.konghq.com
' | kubectl apply -f -

Please note that the Secret must have the konghq.com/credential: konnect label to make the Kong Gateway Operator reconcile it.

echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: konnect-api-auth
  namespace: default
spec:
  type: secretRef
  secretRef:
    name: konnect-api-auth-secret
  serverURL: us.api.konghq.com
---
kind: Secret
apiVersion: v1
metadata:
  name: konnect-api-auth-secret
  namespace: default
  labels:
    konghq.com/credential: konnect
stringData:
  token: kpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
' | kubectl apply -f -

You can verify the KonnectAPIAuthConfiguration object was reconciled successfully by checking its status.

kubectl get konnectapiauthconfiguration konnect-api-auth

The output should look like this:

NAME               VALID   ORGID                                  SERVERURL
konnect-api-auth   True    <your-konnect-org-id>                  https://us.api.konghq.tech

Create a Kong Gateway control plane

Creating the KonnectGatewayControlPlane object in your Kubernetes cluster will provision a Kong Konnect Gateway control plane in your Gateway Manager. The KonnectGatewayControlPlane CR API allows you to explicitly set a type of the Kong Gateway control plane, but if you don’t specify it, the default type is a Self-Managed Hybrid gateway control plane.

You can create one by applying the following YAML manifest:

echo '
kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: gateway-control-plane
  namespace: default
spec:
  name: gateway-control-plane # Name used to identify the Gateway Control Plane in Konnect
  konnect:
    authRef:
      name: konnect-api-auth # Reference to the KonnectAPIAuthConfiguration object
  ' | kubectl apply -f -

You can see the status of the Gateway Control Plane by running:

kubectl get konnectgatewaycontrolplanes.konnect.konghq.com gateway-control-plane

If the Gateway Control Plane is successfully created, you should see the following output:

NAME                    PROGRAMMED   ID                                     ORGID
gateway-control-plane   True         <konnect-control-plane-id>             <your-konnect-ord-id>

Having that in place, you will be able to reference the gateway-control-plane in your Kong Konnect entities as their parent.

Create a Key

Creating the KongKey object in your Kubernetes cluster will provision a Kong Konnect key in your Gateway Manager. You can refer to the CR API to see all the available fields.

Your KongKey must be associated with a KonnectGatewayControlPlane object that you’ve created in your cluster. It will make it part of the Gateway control plane’s configuration.

KongKey supports two types of keys: JWK and PEM. You can create a PEM KongKey by providing spec.pem.private_key and spec.pem.public_key fields. For JWK keys, you should provide spec.jwk field with the JWK key string representation.

For this example, we will create a PEM KongKey by applying the following YAML manifest:

echo '
kind: KongKey
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: key
  namespace: default
spec:
  controlPlaneRef:
    type: konnectNamespacedRef # This indicates that an in cluster reference is used
    konnectNamespacedRef:
      name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object
  kid: key-id
  name: key
  pem:
    private_key: | # Sample private key in PEM format, replace with your own
      -----BEGIN PRIVATE KEY-----
      MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEA4f5Ur6EzZKsfu0ct
      QCmmbCkUohHp6lAgGGmVmQpj5Xrx5jrjGWWdDAF1ADFPh/XMC58iZFaX33UpGOUn
      tuWbJQIDAQABAkEAxqXvvL2+1iNRbiY/kWHLBtIJb/i9G5i4zZypwe+PJduIPRlH
      4bFHih8sHtYt5rEs4RnT0SJnZN1HKhJcisVLdQIhAPKboGS0dTprmMLrAXQh15p7
      xz4XUbZrNqPct+hqa5JXAiEA7nfrjPYm2UXKRzvFo9Zbd9K/Y3M0Xas9LsXdRaO8
      6OMCIAhkX8D8CQ4TSL59WJiGzyl13KeGMPppbQNwECCHBd+TAiB8dDOHprORsz2l
      PYmhPu8PsvpVkbtjo0nUDkmz3Ydq1wIhAIMCsZQ7A3H/kN88aYsqKeGg9c++yqIP
      /9xIOKHsjlB4
      -----END PRIVATE KEY-----
    public_key: | # Sample public key in PEM format, replace with your own
      -----BEGIN PUBLIC KEY-----
      MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOH+VK+hM2SrH7tHLUAppmwpFKIR6epQ
      IBhplZkKY+V68eY64xllnQwBdQAxT4f1zAufImRWl991KRjlJ7blmyUCAwEAAQ==
      -----END PUBLIC KEY-----
  ' | kubectl apply -f -

You can verify the KongKey was reconciled successfully by checking its Programmed condition.

kubectl get kongkey key -o=jsonpath='{.status.conditions[?(@.type=="Programmed")]}' | jq

The output should look similar to this:

{
  "observedGeneration": 1,
  "reason": "Programmed",
  "status": "True",
  "type": "Programmed"
}

At this point, you should see the key in the Gateway Manager UI.

Create a key set

Creating the KongKeySet object in your Kubernetes cluster will provision a Kong Konnect key set in your Gateway Manager. You can refer to the CR API to see all the available fields.

Your KongKeySet must be associated with a KonnectGatewayControlPlane object that you’ve created in your cluster.

To create a KongKeySet, you can apply the following YAML manifest:

echo '
kind: KongKeySet
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: key-set
  namespace: default
spec:
  controlPlaneRef:
    type: konnectNamespacedRef # This indicates that an in cluster reference is used
    konnectNamespacedRef:
      name: gateway-control-plane # KonnectGatewayControlPlane reference
  name: key-set
  ' | kubectl apply -f -

You can verify the KongKeySet was reconciled successfully by checking its Programmed condition.

kubectl get kongkeyset key-set -o=jsonpath='{.status.conditions[?(@.type=="Programmed")]}' | jq

The output should look similar to this:

{
  "observedGeneration": 1,
  "reason": "Programmed",
  "status": "True",
  "type": "Programmed"
}

At this point, you should see the key set in the Gateway Manager UI.

Associate the key with the key set

A single KongKey can be associated with only one KongKeySet. To associate a KongKey with a KongKeySet, you need to update the KongKey object with the keySetRef field. You can do this by applying the following YAML manifest:

echo '
kind: KongKey
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: key
  namespace: default
spec:
  controlPlaneRef:
    type: konnectNamespacedRef # This indicates that an in cluster reference is used
    konnectNamespacedRef:
      name: gateway-control-plane # KonnectGatewayControlPlane reference
  kid: key-id
  name: key
  pem:
    private_key: | # Sample private key in PEM format, replace with your own
      -----BEGIN PRIVATE KEY-----
      MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEA4f5Ur6EzZKsfu0ct
      QCmmbCkUohHp6lAgGGmVmQpj5Xrx5jrjGWWdDAF1ADFPh/XMC58iZFaX33UpGOUn
      tuWbJQIDAQABAkEAxqXvvL2+1iNRbiY/kWHLBtIJb/i9G5i4zZypwe+PJduIPRlH
      4bFHih8sHtYt5rEs4RnT0SJnZN1HKhJcisVLdQIhAPKboGS0dTprmMLrAXQh15p7
      xz4XUbZrNqPct+hqa5JXAiEA7nfrjPYm2UXKRzvFo9Zbd9K/Y3M0Xas9LsXdRaO8
      6OMCIAhkX8D8CQ4TSL59WJiGzyl13KeGMPppbQNwECCHBd+TAiB8dDOHprORsz2l
      PYmhPu8PsvpVkbtjo0nUDkmz3Ydq1wIhAIMCsZQ7A3H/kN88aYsqKeGg9c++yqIP
      /9xIOKHsjlB4
      -----END PRIVATE KEY-----
    public_key: | # Sample public key in PEM format, replace with your own
      -----BEGIN PUBLIC KEY-----
      MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOH+VK+hM2SrH7tHLUAppmwpFKIR6epQ
      IBhplZkKY+V68eY64xllnQwBdQAxT4f1zAufImRWl991KRjlJ7blmyUCAwEAAQ==
      -----END PUBLIC KEY-----
  keySetRef:
    type: namespacedRef
    namespacedRef:
      name: key-set # KongKeySet reference
  ' | kubectl apply -f -

You can verify the KongKey was reconciled successfully by checking its KeySetRefValid condition.

kubectl get kongkey key -o=jsonpath='{.status.conditions[?(@.type=="KeySetRefValid")]}' | jq

The output should look similar to this:

{
  "observedGeneration": 1,
  "reason": "Valid",
  "status": "True",
  "type": "KeySetRefValid"
}

At this point, you should see the key associated with the key set in the Gateway Manager UI.