Skip to content
AggregaAggrega
Select language: English

Kafka — Kubernetes single-node event-streaming broker

This example compiles a small, real stack — an Apache Kafka event-streaming broker in its single-node KRaft shape — from one Developer-authored Aggregate to Kubernetes, synthesized directly from the official Apache Kafka image with no upstream chart.

Kafka is an event-streaming broker: producers append records to topics and consumers read them back in order. In the single-node KRaft shape the broker and the controller roles run inside one process — no ZooKeeper and no second bundled service — so the whole server is one stateful workload. The commit log persists to a local data volume. A producer or consumer connects to the client bootstrap endpoint and exchanges records there.

Files

FileRole
aggregate.yamlDeveloper intent: a single broker component (core/messaging/kafka).
manifest.yamlMaps the component type to the Kafka synthesis Recipe (kafka).
release.yamlOperator record for the Kubernetes target: the server compute and commit-log volume size.

What it demonstrates

  • One authoring surface. A single Aggregate is the source of truth for what Kafka is; the Manifest says how to realize it.
  • A single-node KRaft broker. The synthesis Recipe renders Kafka as one StatefulSet with a data volume and two Service objects — a ClusterIP exposing the client bootstrap port, and a headless governing Service for the StatefulSet.
  • KRaft, no ZooKeeper. The node runs both the broker and controller roles in one process, configured entirely through environment variables.
  • A pinned cluster identity. The cluster identity is a fixed developer value passed verbatim to the image, which reads it as-is with no random generation, so the rendered manifest is byte-identical across builds.
  • A stable advertised address. The broker advertises the in-cluster Service name, so clients reconnect through the stable address rather than the pod’s own hostname.
  • Persistent log. The commit log writes to the persistent volume at /var/lib/kafka/data, so record data survives restarts.
  • An exported bootstrap contract. The component exports its bootstrap host and client port through the uses topology, so a producer or consumer wires to it and connects there.
  • Reproducible images. The Recipe pins the Kafka server image to a resolvable tag so the rendered workload references a pinned version.

Scaffold the example

You can build this example with the commands below, or have your AI assistant build it for you.

Write the example into a new folder named after it:

Terminal window
aggrega scaffold --example kafka-broker

It then prints the commands to run next. The first changes into the new folder:

Terminal window
cd kafka-broker

Build

This workspace carries no .aggrega-config.yaml, so the standard-library entities resolve from the hub registry, hub.aggrega.ai, and no catalog flag is needed:

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

Rendered artifacts land under dist/. The Kubernetes target renders plain manifests offline — no chart pull is required.

With an AI assistant

An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.

Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `kafka-broker` folder yet, call the `scaffold` tool once with `example` set to `kafka-broker` and no `dir`: it writes the example into a new `kafka-broker` folder. Then call the `build` tool with `workspace_root` set to `kafka-broker`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `kafka-broker/dist/`.

What renders

The build emits the Kafka server as three Kubernetes objects:

  • a StatefulSet — the single-node Kafka process, with its commit log on a persistent volume mounted at /var/lib/kafka/data and the full KRaft configuration supplied through environment variables,
  • a ClusterIP Service — exposing the client bootstrap port on 9092,
  • a headless Service — the governing Service the StatefulSet requires for stable per-replica identity.

The Kafka image is pinned to its release tag, so the workload references a pinned image tag.