Service and Route

In this guide you’ll learn how to use the KongService and KongRoute custom resources to manage Kong Konnect services and routes natively from your Kubernetes cluster.

Prerequisites: Install Kong Gateway Operator and create 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 service

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

Your KongService 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 KongService by applying the following YAML manifest:

echo '
kind: KongService
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: service
  namespace: default
spec:
  name: service
  host: example.com
  controlPlaneRef:
    type: konnectNamespacedRef # This indicates that an in cluster reference is used
    konnectNamespacedRef:
      name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object
  ' | kubectl apply -f -

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

kubectl get kongservice service -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 Service in the Gateway Manager UI.

Create a route

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

Your KongRoute can either be associated with a KongService (and inherit the relation with a KonnectGatewayControlPlane from it) or be directly associated with a KonnectGatewayControlPlane object when referring a KongService.

Associate a route with a service

You can create a KongRoute associated with a KongService by applying the following YAML manifest:

echo '
kind: KongRoute
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: route-with-service
  namespace: default
spec:
  name: route-with-service
  protocols:
  - http
  hosts:
  - example.com
  serviceRef:
    type: namespacedRef
    namespacedRef:
      name: service # KongService reference
' | kubectl apply -f -

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

kubectl get kongroute route-with-service -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 Route in the Gateway Manager UI.

Associate a route with a gateway control plane

You can also create a KongRoute that won’t refer any KongService. In that case, you must associate it with a KonnectGatewayControlPlane so that Kong Gateway Operator knows what Gateway control plane it should be created in. You can do so by applying the following YAML manifest:

echo '
kind: KongRoute
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: route-without-service
  namespace: default
spec:
  name: route-without-service
  protocols:
  - http
  hosts:
  - example.com
  controlPlaneRef:
    type: konnectNamespacedRef
    konnectNamespacedRef:
      name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object
' | kubectl apply -f -

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

kubectl get kongroute route-without-service -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 route in the Gateway Manager UI.