Upstream and Target

In this guide you’ll learn how to use the KongUpstream and KongTarget custom resources to manage Kong Konnect upstreams and their targets natively from your Kubernetes cluster.

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

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

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

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 -

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 -

kubectl get konnectapiauthconfiguration konnect-api-auth

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

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 -

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

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

Create an upstream

Creating the KongUpstream 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 KongUpstream 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.

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

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

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

kubectl get kongupstream upstream -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 Upstream in the Gateway Manager UI.

Create a target

Each KongTarget must be associated with a KongUpstream it’s meant to be a backend for. For this reason, you must specify the upstreamRef field in the spec section of the KongTarget object. Please refer to the CR API to see all the available fields.

To create two different KongTargets associated with the KongUpstream created before, you can apply the following YAML manifest:

echo '
kind: KongTarget
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: target-a
  namespace: default
spec:
  upstreamRef:
    name: upstream # Reference to the KongUpstream object
  target: "10.0.0.1"
  weight: 30
---
kind: KongTarget
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: target-b
  namespace: default
spec:
  upstreamRef:
    name: upstream # Reference to the KongUpstream object
  target: "10.0.0.2"
  weight: 70
  ' | kubectl apply -f - 

You can verify both KongTargets successfully were associated with the KongUpstream by checking their KongUpstreamRefValid condition.

kubectl get kongtarget target-a -o=jsonpath='{.status.conditions[?(@.type=="KongUpstreamRefValid")]}' | jq

The output should look similar to this:

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

kubectl get kongtarget target-b -o=jsonpath='{.status.conditions[?(@.type=="KongUpstreamRefValid")]}' | jq

The output should look similar to this:

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

You can also verify both KongTargets were reconciled successfully by checking their Programmed condition.

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

The output should look similar to this:

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

kubectl get kongtarget target-b -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 both Targets in the upstream Upstream in the Gateway Manager UI.