Home / Kong Operator / Konnect
Edit
Report

Enable static naming for Konnect control planes with Kong Operator

Uses: Kong Operator
Incompatible with
on-prem
Related Documentation
Operator 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.

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

  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

Kong Operator running

  1. Add the Kong Helm charts:

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

  2. Install Kong Operator using Helm:

    helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.1.0 \
  --set env.ENABLE_CONTROLLER_KONNECT=true

    helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.1.0

    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=true

    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 certificateAuthority section in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.

This tutorial doesn’t require a license, but you can add one using KongLicense. This assumes that your license is available in ./license.json.

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongLicense
metadata:
 name: kong-license
rawLicenseString: '$(cat ./license.json)'
" | kubectl apply -f -

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

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.

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 -
Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support