helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.3 \
--set env.ENABLE_CONTROLLER_KONNECT=trueEnable 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
-
Add the Kong Helm charts:
helm repo add kong https://charts.konghq.com helm repo update -
Install Kong Operator using Helm:
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
certificateAuthoritysection in thevalues.yamlof 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
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 -