Certificate and CA Certificate

In this guide you’ll learn how to use the KongCertificate and KongCACertificate custom resources to manage Konnect Certificates and CA Certificates 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 certificate

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

Your KongCertificate 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.

You can create a KongCertificate by applying the following YAML manifest:

echo '
kind: KongCertificate
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: cert
  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
  cert: | # Sample certificate in PEM format, replace with your own
    -----BEGIN CERTIFICATE-----
    MIIB4TCCAYugAwIBAgIUAenxUyPjkSLCe2BQXoBMBacqgLowDQYJKoZIhvcNAQEL
    BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM
    GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yNDEwMjgyMDA3NDlaFw0zNDEw
    MjYyMDA3NDlaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw
    HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwXDANBgkqhkiG9w0BAQEF
    AANLADBIAkEAyzipjrbAaLO/yPg7lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42
    e6WGFf9hggP6xjG4qbU8jFVczpd1UPwGbQIDAQABo1MwUTAdBgNVHQ4EFgQUkPPB
    ghj+iHOHAKJlC1gLbKT/ZHQwHwYDVR0jBBgwFoAUkPPBghj+iHOHAKJlC1gLbKT/
    ZHQwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAANBALfy49GvA2ld+u+G
    Koxa8kCt7uywoqu0hfbBfUT4HqmXPvsuhz8RinE5ltxId108vtDNlD/+bKl+N5Ub
    qKjBs0k=
    -----END CERTIFICATE-----
  key: | # Sample private key in PEM format, replace with your own
    -----BEGIN PRIVATE KEY-----
    MIIBVAIBADANBgkqhkiG9w0BAQEFAASCAT4wggE6AgEAAkEAyzipjrbAaLO/yPg7
    lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42e6WGFf9hggP6xjG4qbU8jFVczpd1
    UPwGbQIDAQABAkB4pTPsOMxznDrAWbYtcFovzJMPRIOp/2J5rtGdUcIAxP2rsdqh
    Y1Nj2MV91UPsWjM0OpTD694T5mVR92oTUIvVAiEA7D1L8dCNc4pwZD7tpNLhZVh9
    BhCHPVVQ2RUwBype4FsCIQDcOFV7eD6LWTGLQfCcATr4qYLQ96Xu84F/CyqRIXvu
    1wIhAM3glYDFuaBJs60JUl1kEl4aAcr5OILxCSZGWrbD7C8lAiBtERF1JyaCyVf6
    SlwqR4m3YezCJgTuhXdbPmKEonrI3QIgIh52IOxTS7+ETXY1JjbouTR5irPEWgTM
    +qqDoIn8JJI=
    -----END PRIVATE KEY-----
  ' | kubectl apply -f -

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

kubectl get kongcertificate cert -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 certificate in the Gateway Manager UI.

Assign an SNI to the certificate

You can assign multiple SNIs to a KongCertificate. To do so, you need to create a KongSNI object and associate it with the KongCertificate. Please refer to the CR API to see all the available fields.

You can create a KongSNI by applying the following YAML manifest:

echo '
apiVersion: configuration.konghq.com/v1alpha1
kind: KongSNI
metadata:
  name: example-sni
  namespace: default
spec:
  certificateRef:
    name: cert # Reference to the KongCertificate object
  name: "sni.example.com"
  ' | kubectl apply -f -

You can ensure the KongCertificate reference is valid by checking the KongSNI’s KongCertificateRefValid condition.

kubectl get kongsni example-sni -o=jsonpath='{.status.conditions[?(@.type=="KongCertificateRefValid")]}' | jq

The output should look similar to this:

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

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

kubectl get kongsni example-sni -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 SNI in the Certificate’s SNIs in the Gateway Manager UI.

Create a CA Certificate

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

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

You can create a KongCACertificate by applying the following YAML manifest:

echo '
kind: KongCACertificate
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: ca-cert
  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
  cert: | # Sample CA certificate in PEM format, replace with your own
      -----BEGIN CERTIFICATE-----
      MIIB4TCCAYugAwIBAgIUAenxUyPjkSLCe2BQXoBMBacqgLowDQYJKoZIhvcNAQEL
      BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM
      GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yNDEwMjgyMDA3NDlaFw0zNDEw
      MjYyMDA3NDlaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw
      HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwXDANBgkqhkiG9w0BAQEF
      AANLADBIAkEAyzipjrbAaLO/yPg7lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42
      e6WGFf9hggP6xjG4qbU8jFVczpd1UPwGbQIDAQABo1MwUTAdBgNVHQ4EFgQUkPPB
      ghj+iHOHAKJlC1gLbKT/ZHQwHwYDVR0jBBgwFoAUkPPBghj+iHOHAKJlC1gLbKT/
      ZHQwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAANBALfy49GvA2ld+u+G
      Koxa8kCt7uywoqu0hfbBfUT4HqmXPvsuhz8RinE5ltxId108vtDNlD/+bKl+N5Ub
      qKjBs0k=
      -----END CERTIFICATE-----
' | kubectl apply -f -

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

kubectl get kongcacertificate ca-cert -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 CA Certificate in the Gateway Manager UI.