helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.1 \
--set env.ENABLE_CONTROLLER_KONNECT=true
Copied!
Enable 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'Copied!
Kong Operator running
-
Add the Kong Helm charts:
helm repo add kong https://charts.konghq.com helm repo updateCopied! -
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=trueCopied!If 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 -
Copied!
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 a static, predictable name for the generated control plane based on the Gateway’s namespace and name (for example, default-hybrid). This enables you to configure references before the control plane is created.
When static naming is enabled, Kong Operator derives the name for the KonnectGatewayControlPlane using the following logic:
- If the Gateway is in the same namespace as Kong Operator, the name will be the same as the Gateway name.
- If the Gateway is in a different namespace, the name will be the Gateway name prefixed with the namespace.
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.13
---
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 -
Copied!
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 -
Copied!
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"
Copied!
You should see a control plane named kong-hybrid.
You can now reference the control plane in other resources using the Gateway 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 -
Copied!