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