Gateway Control Plane

In this guide you’ll learn how to use the KonnectGatewayControlPlane custom resource to manage Konnect Gateway Control Planes natively from your Kubernetes cluster.

Prerequisites: Install Kong Gateway Operator and create a valid KonnectAPIAuthConfiguration 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 self-managed hybrid gateway control plane

Creating the KonnectGatewayControlPlane object in your Kubernetes cluster will provision a Konnect Gateway control plane in your Gateway Manager. The KonnectGatewayControlPlane CR API allows you to explicitly set a type of the 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>

Create a control plane group

Gateway Manager allows you to group multiple Gateway control planes. You can create a Control Plane Group by setting the cluster_type field in the spec section of the KonnectGatewayControlPlane object to CLUSTER_TYPE_CONTROL_PLANE_GROUP.

echo '
kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: control-plane-group
  namespace: default
spec:
  name: control-plane-group # Name used to identify the Gateway Control Plane in Konnect
  cluster_type: CLUSTER_TYPE_CONTROL_PLANE_GROUP # Type of the Gateway Control Plane
  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 konnectgatewaycontrolplane control-plane-group

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

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

Add a gateway control plane to a control plane group

To assign Gateway control planes to a control plane group, you need to specify the members field in the spec section of the KonnectGatewayControlPlane object.

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

You can check in your Gateway Manager to see if the Gateway control plane was successfully added to the control plane group.

Create a Kubernetes ingress controller control plane

To create a Kubernetes Ingress Controller Control Plane, you need to specify the cluster_type field in the spec section of the KonnectGatewayControlPlane object.

echo '
kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: kic-control-plane
  namespace: default
spec:
  name: kic-control-plane # Name used to identify the Gateway Control Plane in Konnect
  cluster_type: CLUSTER_TYPE_K8S_INGRESS_CONTROLLER # Type of the Gateway Control Plane
  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 konnectgatewaycontrolplane kic-control-plane

If the control plane is successfully created, you should see the following output:

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