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.

Install Kong Gateway Operator and create a valid KonnectAPIAuthConfiguration and KonnectGatewayControlPlane in your cluster.

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.6 \
  --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.

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.com

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.

Thank you for your feedback.

Was this page useful?