Deploy on Kubernetes

This guide shows how to deploy Kafkorama Portal on Kubernetes alongside a Kafkorama Gateway cluster.

Kafkorama Platform — Kubernetes Deployment

Deploys the complete Kafkorama real-time messaging stack — Portal, Kafkorama Gateway, and live-data demo publishers — on Kubernetes using a kafkorama namespace.

Find the complete source code and configuration in the kafkorama-deployment repository on GitHub.

Directory Tree

kubernetes/
├── 01-apache-kafka.yaml        # Apache Kafka (Service, StatefulSet)
├── 02-kafkorama-portal.yaml   # Kafkorama Portal (Services, PVC, ConfigMap, Deployment)
├── 03-kafkorama-gateway.yaml  # Kafkorama Gateway (Service, ConfigMap, Deployment)
├── 04-demos.yaml              # Demo data publishers (stocks, traffic, crypto, parking, seismic)
└── README.md                  # This file

Architecture Overview

                    ┌───────────────────────────────────────┐
                    │           kafkorama namespace          │
                    │                                        │
  Browser / SDK ───►│  kafkorama-portal-external             │
       :8080        │  (LoadBalancer)                        │
                    │            │                           │
                    │    kafkorama-portal                    │
                    │    (Deployment + PVC 5Gi)              │
                    │            │ internal                  │
                    │  kafkorama-portal-internal             │
                    │  (ClusterIP)                           │
                    │            │                           │
  Client SDK ──────►│  kafkorama-gateway-external            │
       :8800        │  (LoadBalancer)                        │
                    │            │                           │
                    │    kafkorama-gateway                   │
                    │    (Deployment)                        │
                    │            │                           │
                    │    kafka-service (ClusterIP :9092)     │
                    │    kafka (StatefulSet)                 │
                    │                                        │
                    │    demo-* (Deployments)                │
                    └───────────────────────────────────────┘

Service	Type	Port	Purpose
`kafkorama-portal-external`	LoadBalancer	`8080`	Portal web UI — browser access
`kafkorama-portal-internal`	ClusterIP	`8080`	Portal — internal cluster communication
`kafkorama-gateway-external`	LoadBalancer	`8800`	Kafkorama Gateway — client SDK connections
`kafka-service`	ClusterIP	`9092`	Apache Kafka — internal cluster communication

Prerequisites

kubectl configured for your target cluster
Minikube for local development

Verify your setup:

kubectl version --client
minikube version

Setup Instructions

1. Clone the repository (if not already done)

git clone git@github.com:kafkorama/kafkorama-deployment.git
cd kafkorama-deployment/kubernetes

2. Start Minikube (local development only)

minikube start

Optionally, open the Kubernetes dashboard:

minikube dashboard

3. Create the namespace

All resources are deployed into the kafkorama namespace:

kubectl create namespace kafkorama

Switch your active context to the new namespace so subsequent commands default to it:

kubectl config set-context --current --namespace=kafkorama

4. Deploy Apache Kafka

Deploys a single-node Apache Kafka broker (KRaft mode) with a ClusterIP service accessible within the cluster at kafka-service:9092:

kubectl apply -f 01-apache-kafka.yaml

5. Deploy the Portal

Deploys the Kafkorama Portal with its external and internal Services, a 5 Gi PersistentVolumeClaim for the SQLite database, a ConfigMap for configuration, and the Portal Deployment.

kubectl apply -f 02-kafkorama-portal.yaml

Note: The storageClassName: local-path in the PVC spec may need to be adjusted to match the storage classes available in your cluster. Run kubectl get storageclass to list available classes.

6. Deploy the Kafkorama Gateway

Deploys the Kafkorama Gateway with a LoadBalancer Service and a ConfigMap-backed configuration:

kubectl apply -f 03-kafkorama-gateway.yaml

7. Deploy Demo Applications (optional)

Deploys live-data publishers that continuously stream real-time data to the Kafkorama Gateway for demonstration purposes:

kubectl apply -f 04-demos.yaml

8. Expose LoadBalancer Services (Minikube only)

Minikube does not automatically assign external IPs to LoadBalancer services. Run the tunnel in a separate terminal to enable access:

minikube tunnel

Verify Installation

Check that all pods reach Running status:

kubectl get pods

Expected output:

NAME                                     READY   STATUS    RESTARTS   AGE
kafka-0                                  1/1     Running   0          5m
kafkorama-portal-5c94794f9-gzxbs         1/1     Running   0          4m
kafkorama-gateway-bd4c75658-5rhx8        1/1     Running   0          3m
demo-stocks-7bdd96c4fc-6lps5             1/1     Running   0          1m
demo-traffic-6d4d5d4868-vkrv9            1/1     Running   0          1m
demo-cryptocurrency-846789989b-wctzl     1/1     Running   0          1m

Verify Services and their external IPs:

kubectl get svc

Expected output:

NAME                             TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
kafka-service                    ClusterIP      10.43.112.45    <none>        9092/TCP         5m
kafkorama-portal-external        LoadBalancer   10.43.158.123   127.0.0.1     8080:30856/TCP   4m
kafkorama-portal-internal        ClusterIP      10.43.199.88    <none>        8080/TCP         4m
kafkorama-gateway-external       LoadBalancer   10.43.237.196   127.0.0.1     8800:31735/TCP   3m

Getting Started

Open the Portal

Navigate to the Portal in your browser:

http://127.0.0.1:8080

Field	Value
Email	`admin@admin.com`
Password	`password`

Security: Change the default admin password and all shared secrets before any non-local deployment.

Useful Commands

View logs

# Portal logs
kubectl logs -f deployment/kafkorama-portal

# Kafkorama Gateway logs
kubectl logs -f deployment/kafkorama-gateway

# Kafka logs
kubectl logs -f statefulset/kafka

Inspect a pod

kubectl describe pod <pod-name>

Open a shell inside a pod

kubectl exec -it <pod-name> -- /bin/bash

Update configuration

Configuration is stored in ConfigMaps inside each manifest. To apply a config change:

Edit the relevant ConfigMap section in the YAML file.
Re-apply the manifest:

kubectl apply -f 02-kafkorama-portal.yaml   # for portal config changes
kubectl apply -f 03-kafkorama-gateway.yaml  # for gateway config changes

Restart the affected deployment to pick up the new ConfigMap:

kubectl rollout restart deployment/kafkorama-portal
kubectl rollout restart deployment/kafkorama-gateway

Uninstall

Remove all resources by deleting the namespace:

kubectl delete namespace kafkorama

Then restore the default namespace context:

kubectl config set-context --current --namespace=default

previous

Deploy on Docker

Kafkorama Platform — Kubernetes Deployment Directory Tree Architecture Overview Prerequisites Setup Instructions Verify Installation Getting Started Useful Commands Uninstall