Skip to main content

Kubernetes operator

The operator manages gateway configuration as Kubernetes resources: VirtualTopic, Client, Role and Group. It applies them through the gateway's admin API, keeps the gateway in sync and reverts changes made elsewhere.

Install​

The operator is the kawa-operator chart, installed next to the gateway. The examples assume the gateway from Getting started: release kawa in namespace kawa.

1. Share a client secret​

The operator logs in as the fixed client kawa-operator with the OAuth 2.0 client credentials grant. Create its secret:

kubectl -n kawa create secret generic kawa-operator-client \
--from-literal=client-secret="$(openssl rand -hex 32)"

Enable the client on the gateway (requires admin.auth.type: oauth) and helm upgrade it:

my-values.yaml
gateway:
extraEnv:
- name: KAWA_OPERATOR_SECRET
valueFrom:
secretKeyRef: { name: kawa-operator-client, key: client-secret }
config:
admin:
auth:
settings:
operatorSecret: ${KAWA_OPERATOR_SECRET}

2. Install the chart​

operator-values.yaml
gateway:
adminUrl: http://kawa-gateway.kawa.svc:8080
auth:
existingSecret: kawa-operator-client
helm install kawa-operator oci://ghcr.io/kawa-platform/charts/kawa-operator --version 0.1.0-rc.3 \
-n kawa -f operator-values.yaml --wait

The chart version pins the operator image. The Secrets must live in the operator's namespace.

ValueDefaultDescription
gateway.adminUrlrequiredThe gateway's admin API.
gateway.auth.existingSecretrequiredSecret with key client-secret. Read on every use, so rotating it needs no restart.
gateway.tls.caSecretsystem rootsSecret with key ca.crt, for an https admin API with a private CA.
namespaceSelectorall namespacesLabel selector of namespaces to serve, e.g. kawa-platform.github.io/gateway=kawa.
resyncInterval5mHow often synced resources are compared with the gateway again.
metrics.enabledfalseMetrics over HTTPS on :8443, Service <release>-metrics. Scrapers need the <release>-metrics-reader ClusterRole.

The chart installs the CRDs and keeps them, and every resource, on uninstall. It aggregates into the built-in view, edit and admin roles, so namespace editors manage their own kawa resources. For several gateways, install one release per gateway, each with its own namespaceSelector.

3. Check it​

kubectl create namespace team-a
kubectl apply -f - <<'EOF'
apiVersion: kawa-platform.github.io/v1alpha1
kind: VirtualTopic
metadata:
name: orders-eu
namespace: team-a
spec:
physicalTopic: orders-v2
EOF
kubectl -n team-a get virtualtopic orders-eu \
-o jsonpath='{.status.conditions[?(@.type=="Ready")].reason}' # Synced

Resources​

All kinds are namespaced, in kawa-platform.github.io/v1alpha1. Each one is described on its module page:

KindManagesFields
VirtualTopicA virtual topicVirtual topics
ClientA SASL client and its passwordAuthentication
RoleA set of ACLsAccess control
GroupClients that share rolesAccess control

The gateway name is metadata.name (a VirtualTopic can override it). Every kind has deletionPolicy: Delete (default) removes the object from the gateway, Retain leaves it.

Ownership​

Gateway names are global per gateway. The operator records the name it manages in status, and only changes or deletes that name. If two resources claim one name, the older wins and the other reports Conflict. An object that already exists on the gateway (made in Studio or the API) reports AlreadyExists until you annotate the resource with kawa-platform.github.io/adopt: "true".

Deletion goes through a finalizer and needs the gateway to be reachable.

Status​

Each resource has a Ready condition, observedGeneration, and the managed name in status.

ReasonMeaning
SyncedThe gateway matches the spec. Checked again every resync interval.
InvalidSpecThe admin API refused the spec (400), e.g. a CEL expression that does not compile.
GovernanceRejectedA governance rule refused the change (403). Retried each resync.
AlreadyExistsExists on the gateway but not managed by the operator. See Ownership.
ConflictAnother resource already manages this name.
NamespaceNotAllowedThe namespace does not match namespaceSelector.
NamespaceUnreadableThe operator cannot read the namespace to check it.
SecretUnavailableA Client's password Secret or key is missing. Retried when the Secret changes.
AuthenticationFailedThe gateway refused the operator's client secret.
GatewayConfigInvalidThe operator's own gateway settings are unusable, e.g. an unreadable client secret or CA file.
GatewayUnavailableThe admin API is unreachable or failing. Retried with backoff.
APIUnavailableThe Kubernetes API failed. Retried with backoff.
DeletionRejectedThe gateway refused the delete (403). Retried every minute; the finalizer holds the resource.

Operator flags​

The chart sets these. They matter only when running the binary yourself.

FlagDefaultDescription
--gateway-admin-urlrequiredAbsolute http:// or https:// URL.
--gateway-client-idemptykawa-operator. Set together with --gateway-client-secret-file.
--gateway-client-secret-fileemptyFile with the client secret.
--gateway-ca-filesystem rootsPEM CAs for an https admin API.
--namespace-selectorallLabel selector of namespaces to serve.
--resync-interval5m
--leader-elect, --leader-election-idfalse, kawa-operator.kawa-platform.github.ioThe chart enables it, with the release name as id.
--health-probe-bind-address:8081/healthz and /readyz.
--metrics-bind-address, --metrics-secure, --enable-http20, true, falseStandard controller-runtime options.