helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.3 \
--set env.ENABLE_CONTROLLER_KONNECT=true
kubectl -n kong-system wait --for=condition=Available=true --timeout=300s deployment/kong-operator-kong-operator-controller-managerEnable static naming for Konnect control planes with Kong Operator
Uses:
Kong Operator
Incompatible with
on-prem
Related Documentation
Minimum Version
Kong Operator - 2.1
TL;DR
Add the gateway-operator.konghq.com/static-naming: "true" annotation to your Gateway resource.
Prerequisites
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
Kong Operator running
If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:
--set global.webhooks.options.certManager.enabled=trueIf you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates.
Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane.
This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the certificateAuthority section
in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.
Create a KonnectAPIAuthConfiguration resource
kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
name: konnect-api-auth
namespace: kong
spec:
type: token
token: "'$KONNECT_TOKEN'"
serverURL: us.api.konghq.com
' | kubectl apply -f -By default, Kong Operator generates unique, dynamic names for KonnectGatewayControlPlane resources created from a Gateway.
The gateway-operator.konghq.com/static-naming: "true" annotation instructs Kong Operator to use static, predictable names for the resources it generates from a Gateway. The KonnectGatewayControlPlane resource is named after the Gateway. In Kong Operator 2.3.2 and later, the control plane this resource creates in Konnect is named <namespace>_<gateway-name> (for example, kong_hybrid); in earlier versions, it’s named after the Gateway alone (for example, hybrid). This enables you to configure references before the control plane is created.
Kong Operator names the
KonnectGatewayControlPlaneresource and the control plane it creates in Konnect at creation time, and it doesn’t rename them afterwards. Adding or removing the annotation on an existingGatewaydoesn’t rename the resources already created for it, and control planes created before upgrading to Kong Operator 2.3.2 keep the name they already have. To rename an existing control plane in Konnect, editspec.createControlPlaneRequest.nameon theKonnectGatewayControlPlane.
When static naming is enabled, Kong Operator names the KonnectGatewayControlPlane resource after the Gateway. The control plane it creates in Konnect is named <namespace>_<gateway-name> in Kong Operator 2.3.2 and later, and after the Gateway alone in earlier versions.
The namespace is part of the Konnect name because control plane names must be unique across your whole Konnect organization, while Gateway names only have to be unique within a namespace. The two parts are joined with an underscore, which can’t appear in a namespace or a Gateway name, so the namespace and the Gateway name stay unambiguously separated. As a result, the Kubernetes and Konnect names of the same control plane differ, for example hybrid and kong_hybrid.
Create the GatewayConfiguration and GatewayClass resources
Configure the GatewayConfiguration resources with your Konnect authentication and configure the GatewayClass resource to reference the GatewayConfiguration:
echo '
kind: GatewayConfiguration
apiVersion: gateway-operator.konghq.com/v2beta1
metadata:
name: hybrid
namespace: kong
spec:
konnect:
authRef:
name: konnect-api-auth
dataPlaneOptions:
deployment:
podTemplateSpec:
spec:
containers:
- name: proxy
image: kong/kong-gateway:3.16
---
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: hybrid
spec:
controllerName: konghq.com/gateway-operator
parametersRef:
group: gateway-operator.konghq.com
kind: GatewayConfiguration
name: hybrid
namespace: kong ' | kubectl apply -f -Configure the Gateway with static naming
Configure the Gateway resource to reference the GatewayClass resource and add the gateway-operator.konghq.com/static-naming: "true" annotation:
echo '
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: hybrid
namespace: kong
annotations:
gateway-operator.konghq.com/static-naming: "true"
spec:
gatewayClassName: hybrid
listeners:
- name: http
protocol: HTTP
port: 80' | kubectl apply -f -Validate
Check that the operator created the KonnectGatewayControlPlane and that it’s Programmed:
You can verify the KonnectGatewayControlPlane was reconciled successfully by checking its Programmed condition.
kubectl get -n kong konnectgatewaycontrolplane hybrid \
-o=jsonpath='{.status.conditions[?(@.type=="Programmed")]}' | jqThe output should look similar to this:
{
"observedGeneration": 1,
"reason": "Programmed",
"status": "True",
"type": "Programmed"
}The resource asks Konnect for a control plane named <namespace>_<gateway-name>. Confirm the name it requests:
kubectl get -o yaml -n kong konnectgatewaycontrolplane hybrid \
| yq '.spec.createControlPlaneRequest.name'You should see the value kong_hybrid.
To validate, fetch a list of control planes in Konnect:
curl -X GET "https://us.api.konghq.com/v2/control-planes" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN"You should see a control plane named kong_hybrid (hybrid on Kong Operator 2.3.1 and earlier).
You can now reference the control plane in other resources using the name of the KonnectGatewayControlPlane resource, which matches the Gateway name. No resource looks up the control plane by its Konnect name. For example, here’s how to reference it in a KongConsumer resource:
echo '
kind: KongConsumer
apiVersion: configuration.konghq.com/v1
metadata:
name: consumer1
namespace: kong
username: consumer1
spec:
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: hybrid' | kubectl apply -f -Confirm that the KongConsumer resolved the reference to the generated resource:
kubectl get -o yaml -n kong kongconsumer consumer1 \
| yq '.status.conditions[] | select(.type == "ControlPlaneRefValid") | .status'You should see the value True.
Cleanup
Delete the resources created in this guide
Deleting the Gateway also deletes the KonnectGatewayControlPlane that Kong Operator
created for it, which removes the control plane from Konnect:
kubectl delete -n kong --ignore-not-found gateway/hybrid kongconsumer/consumer1
kubectl delete -n kong --ignore-not-found konnectgatewaycontrolplane --all
kubectl delete -n kong --ignore-not-found gatewayconfiguration/hybrid
kubectl delete --ignore-not-found gatewayclass/hybrid
kubectl delete namespace --ignore-not-found kong