Kong Event Gateway with Kong Operator

Kong Operator reconciles Kong Event Gateway resources and deploys a matching KegDataPlane workload in your Kubernetes cluster.

For a step-by-step walkthrough you can apply directly to a cluster, see the Kong Event Gateway getting started guide.

Kong Operator manages three layers:

  • A control plane, which is one of the following:
    • A KonnectEventGateway in konnect.konghq.com/v1alpha1, which creates the control plane in Konnect
    • An OnPremEventGateway in eventgateway.konghq.com/v1alpha1, which a control plane in your cluster serves
  • Event Gateway configuration resources in configuration.konghq.com/v1alpha1
  • A KegDataPlane workload in eventgateway.konghq.com/v1alpha1

Resource model

Here are the Kubernetes resources that form a typical Kong Event Gateway deployment:

Resource

API group

Purpose

KonnectEventGateway konnect.konghq.com/v1alpha1 Creates the Event Gateway control plane in Konnect
OnPremEventGateway eventgateway.konghq.com/v1alpha1 Defines an on-prem Kong Event Gateway, whose configuration Kong Operator pushes to the in-cluster control plane
GWAdmin gateway-operator.konghq.com/v1alpha1 Deploys the in-cluster control plane that serves OnPremEventGateway configuration to data planes
EventGatewayBackendCluster configuration.konghq.com/v1alpha1 Describes the upstream Kafka cluster
EventGatewayVirtualCluster configuration.konghq.com/v1alpha1 Defines the virtual cluster presented to clients
EventGatewayListener configuration.konghq.com/v1alpha1 Declares listener addresses and ports
EventGatewayListenerPolicy configuration.konghq.com/v1alpha1 Configures routing and TLS behavior on the listener
EventGatewayVirtualClusterConsumePolicy configuration.konghq.com/v1alpha1 Applies consume-side policy to a virtual cluster
EventGatewayVirtualClusterProducePolicy configuration.konghq.com/v1alpha1 Applies produce-side policy to a virtual cluster
EventGatewaySchemaRegistry configuration.konghq.com/v1alpha1 Connects to a schema registry for consume and produce schema validation policies
KegDataPlane eventgateway.konghq.com/v1alpha1 Deploys the Event Gateway data plane in Kubernetes

Resources reference each other in this order:

  1. EventGatewayBackendCluster.spec.parentRef (or the deprecated spec.gatewayRef) points to a KonnectEventGateway
  2. EventGatewayVirtualCluster.spec.eventGatewayBackendClusterRef points to an EventGatewayBackendCluster
  3. EventGatewayListener.spec.parentRef (or the deprecated spec.gatewayRef) points to the same KonnectEventGateway
  4. EventGatewayListenerPolicy.spec.eventGatewayListenerRef points to an EventGatewayListener
  5. Consume and produce policies point to an EventGatewayVirtualCluster
  6. EventGatewaySchemaRegistry.spec.parentRef (or the deprecated spec.gatewayRef) points to the same KonnectEventGateway, and consume or produce policies reference it via schemaValidation.config.confluentSchemaRegistry.schemaRegistry
  7. KegDataPlane.spec.controlPlaneRef points to the KonnectEventGateway

With an on-prem control plane, the same resources point to an OnPremEventGateway instead, with spec.parentRef, and KegDataPlane.spec.controlPlaneRef uses type: onpremNamespacedRef. See On-prem control plane.

Deployment patterns

There are two ways to expose Kong Event Gateway with Kong Operator:

  • LoadBalancer with portMapping. Use this pattern if:
    • you need a fast local validation loop
    • you can expose one port per broker
    • a stable external IP is acceptable for clients
  • Gateway with TLSRoute and SNI. Use this pattern if:
    • you want a production-oriented edge pattern
    • you need a single public Kafka listener
    • you want broker metadata returned as DNS names on one port
    • you plan to front multiple virtual clusters behind one entrypoint

LoadBalancer with port mapping

This pattern suits local validation and simple deployments where exposing one port per broker is acceptable. The KegDataPlane exposes a LoadBalancer Service with one port for bootstrap traffic and one port per broker.

The listener policy uses forwardToVirtualCluster.config.type: portMapping:

apiVersion: configuration.konghq.com/v1alpha1
kind: EventGatewayListenerPolicy
metadata:
  name: example-listener-policy
  namespace: kong
spec:
  apiSpec:
    type: forwardToVirtualCluster
    forwardToVirtualCluster:
      name: forward
      config:
        type: portMapping
        portMapping:
          advertisedHost: "10.0.1.1"
          bootstrapPort: at_start
          destination:
            name: example-virtual-cluster
  eventGatewayListenerRef:
    type: namespacedRef
    namespacedRef:
      name: example-listener

Set advertisedHost explicitly. Kafka clients use it when resolving broker metadata after bootstrap.

In a three-broker cluster, the data plane Service exposes:

  • 9092 for bootstrap
  • 9093 for broker 0
  • 9094 for broker 1
  • 9095 for broker 2

For a full deployment walkthrough, see Deploy Kong Event Gateway with port mapping.

Gateway with TLSRoute and SNI

This is the production-oriented pattern. A single TLS listener at the Kubernetes edge routes Kafka traffic to the correct virtual cluster by SNI:

  • A Kubernetes Gateway exposes a single TLS listener
  • A TLSRoute forwards encrypted traffic to the KegDataPlane Service
  • An EventGatewayListenerPolicy with type: tlsServer terminates TLS in Kong Event Gateway
  • A second EventGatewayListenerPolicy with forwardToVirtualCluster.config.type: sni routes clients by SNI

This keeps the public edge to a single port and returns broker metadata as stable DNS names instead of distinct ports.

The SNI forwarding policy looks like this:

apiVersion: configuration.konghq.com/v1alpha1
kind: EventGatewayListenerPolicy
metadata:
  name: sni-forward
  namespace: kong
spec:
  apiSpec:
    type: forwardToVirtualCluster
    forwardToVirtualCluster:
      name: forward_sni
      config:
        type: sni
        sni:
          sniSuffix: ".keg.example.com"
          brokerHostFormat:
            type: per_cluster_suffix
          advertisedPort: 9092
  eventGatewayListenerRef:
    type: namespacedRef
    namespacedRef:
      name: sni-listener

With a virtual cluster dnsLabel of vc-tls-1, clients receive metadata like:

  • bootstrap.vc-tls-1.keg.example.com:9092
  • broker-0.vc-tls-1.keg.example.com:9092
  • broker-1.vc-tls-1.keg.example.com:9092
  • broker-2.vc-tls-1.keg.example.com:9092

In production, configure wildcard DNS so that the advertised bootstrap and broker hostnames resolve to the Gateway address.

For a full deployment walkthrough, see Deploy Kong Event Gateway with TLSRoute and SNI.

On-prem control plane

An OnPremEventGateway replaces the Konnect-hosted control plane with a control plane that runs in your cluster. Three resources work together:

  • A GWAdmin deploys the control plane: a Deployment, and the Services that Kong Operator and the data planes connect to. Kong Operator creates the certificate authorities that the control plane, Kong Operator, and the data planes use to authenticate each other, and renews the certificates before they expire.
  • An OnPremEventGateway references the control plane with spec.gwAdminRef. It doesn’t create any Pods. Kong Operator collects the Event Gateway resources attached to it and pushes their configuration to every control plane Pod over mTLS.
  • A KegDataPlane references the OnPremEventGateway with spec.controlPlaneRef.type: onpremNamespacedRef. Kong Operator issues the data plane a client certificate and registers the certificate on the control plane. The data plane then pulls its configuration from the control plane.

The control plane and data planes don’t send anything to Konnect, so Konnect features such as analytics and the Konnect UI aren’t available. To follow the getting started series with an on-prem control plane, see Install Kong Operator for Kong Event Gateway.

Enable the on-prem controllers

The GWAdmin and OnPremEventGateway controllers are disabled by default. Enable them alongside the KegDataPlane controller by adding the following flags to your helm install or helm upgrade command for Kong Operator:

--set env.ENABLE_CONTROLLER_KEGDATAPLANE=true \
--set env.ENABLE_CONTROLLER_GWADMIN=true \
--set env.ENABLE_CONTROLLER_ONPREMEVENTGATEWAY=true

License

The control plane requires an Event Gateway license with the event_gateway entitlement. This is a signed license token, not the JSON license that KongLicense uses for Kong Gateway. Store it in a Secret labeled konghq.com/secret=true, and reference the Secret key from the GWAdmin:

apiVersion: gateway-operator.konghq.com/v1alpha1
kind: GWAdmin
metadata:
  name: gw-admin
  namespace: kong
spec:
  license:
    secretRef:
      name: gw-admin-license
      key: license

Kong Operator mounts the license in the control plane Pods. The control plane, not Kong Operator, validates it, and doesn’t start without a valid license. To renew the license, update the Secret in place: the control plane reads the mounted file again on its periodic license checks, without a restart. The KegDataPlane doesn’t need a KongLicense.

Reference an OnPremEventGateway

EventGatewayBackendCluster, EventGatewayListener, EventGatewaySchemaRegistry, EventGatewayStaticKey, EventGatewayTLSTrustBundle, and EventGatewayDataPlaneCertificate attach to an OnPremEventGateway with spec.parentRef, which must set group and kind:

spec:
  parentRef:
    group: eventgateway.konghq.com
    kind: OnPremEventGateway
    name: cp-event-1

Virtual clusters and policies attach to their parent entities as they do with Konnect, so they don’t change.

You can’t change the kind of the referenced gateway on an existing resource to move it between a KonnectEventGateway and an OnPremEventGateway. Delete and recreate it instead.

A KegDataPlane attaches to an OnPremEventGateway with spec.controlPlaneRef.type: onpremNamespacedRef:

spec:
  controlPlaneRef:
    type: onpremNamespacedRef
    onpremNamespacedRef:
      name: cp-event-1

You can’t change the control plane reference after you create the KegDataPlane. The name of an on-prem KegDataPlane must be a valid DNS label of at most 57 characters.

To reference a GWAdmin or an OnPremEventGateway in another namespace, create a KongReferenceGrant in the namespace of the referenced resource. See Cross namespace references.

How configuration is pushed

Kong Operator pushes the whole configuration of an OnPremEventGateway as one unit. If Kong Operator can’t send an entity, for example a policy that references a resource that doesn’t exist, it doesn’t push the configuration at all. The control plane keeps serving the last configuration that it accepted. The OnPremEventGateway reports Programmed=False with the reason InvalidEntities and names the entities. Each entity reports the cause in its own Programmed condition. Fix or delete the entity to resume pushing.

status.configRevision on the OnPremEventGateway increases by one every time its configuration changes.

Status conditions

The on-prem resources report the following conditions:

Resource

Condition

Meaning

GWAdmin Ready The certificates and the control plane Deployment are configured. It can be True before the control plane Pod is running, so wait for the Deployment to be available too.
GWAdmin LicenseProvisioned The license Secret and key exist and are mounted in the control plane Pods. It doesn’t mean the license is valid.
OnPremEventGateway GWAdminResolved The control plane can serve the gateway. The reason is NotFound if the GWAdmin doesn’t exist, RefNotPermitted if a cross-namespace reference doesn’t have a KongReferenceGrant, and NotReady while the control plane doesn’t have a running Pod.
OnPremEventGateway ConfigurationPushed Kong Operator pushed the current configuration to every control plane Pod.
OnPremEventGateway Programmed The configuration was applied. Wait on this condition, as you would for a KonnectEventGateway.
KegDataPlane OnPremEventGatewayResolved The OnPremEventGateway, and what the data plane needs from its control plane, were found.
KegDataPlane GWAdminCertificateRegistered The client certificate of the data plane is registered on the control plane.

Event Gateway configuration resources report a Programmed condition, as they do with Konnect. With an on-prem control plane, Programmed=True means the resource is in the configuration pushed to the control plane.

Troubleshooting

A listener policy isn’t programmed

If the Programmed message of a forwardToVirtualCluster listener policy reports that an EventGatewayVirtualCluster is not found, check destination.name. It must be the name of the EventGatewayVirtualCluster resource, not its apiSpec.name. Until you fix it, Kong Operator doesn’t push any configuration change for the OnPremEventGateway.

The control plane Pod doesn’t start

Check the control plane logs:

kubectl logs -n kong deployment/gw-admin

The control plane doesn’t start without a valid Event Gateway license. Make sure that the Secret holds the license token with the event_gateway entitlement, not a Kong Gateway Enterprise JSON license.

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!