Developer Quick-Start on StreamsHub

Prerequisites

Mon, 01 Jan 0001 00:00:00 +0000

Required #

kubectl v1.27 or later — the install scripts use Kustomize v5.0 features (the labels transformer) which require kubectl 1.27+.

Check your version:
```
kubectl version --client
```
A running Kubernetes cluster — any local or development cluster should work. Common options:
- minikube
- KIND

Recommended #

An Ingress controller — required if you want to access the StreamsHub Console via its hostname (console.streamshub.local). Without one, you can still use port-forwarding to access Kafka.

Cluster Setup #

If you don’t already have a cluster running, here are quick setup instructions for the most common options:

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Quick-Start Install #

Deploy the entire core stack with a single command:

curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | bash

The script:

Checks prerequisites (kubectl, IngressClass)
Installs operators and CRDs (Phase 1)
Waits for each operator to become ready
Deploys Kafka, Registry, and Console instances (Phase 2)

Install with an Overlay #

Overlays extend the core stack with optional components. To install with an overlay, set the OVERLAY variable:

curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | OVERLAY=<name> bash

See Overlays for the list of available overlays and what each one adds.

Accessing Services

Mon, 01 Jan 0001 00:00:00 +0000

StreamsHub Console #

Ingress Access #

For the Console to startup correctly and be accessible, you need an Ingress controller running in your cluster.

minikube #

Enable the ingress addon (if not already enabled):

minikube addons enable ingress

Use port-forwarding to access the console:

kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80

Open http://localhost:8090 in your browser.

KIND #

If you created your KIND cluster with the port mappings described in Prerequisites, and deployed ingress-nginx: Use port-forwarding to access the console:

Uninstallation

Mon, 01 Jan 0001 00:00:00 +0000

Using the Uninstall Script #

The uninstall script provides safe teardown with shared-cluster awareness:

curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/uninstall.sh | bash

If you installed with the metrics overlay:

curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/uninstall.sh | OVERLAY=metrics bash

Configuration #

Variable	Default	Description
`REPO`	`streamshub/developer-quickstart`	GitHub repository path
`REF`	`main`	Git ref, branch, or tag
`OVERLAY`	(empty)	Overlay to uninstall (e.g. `metrics`)
`TIMEOUT`	`120s`	kubectl wait/poll timeout
`LOCAL_DIR`	(empty)	Use a local directory instead of GitHub

What the Script Does #

The uninstall follows a 4-phase process designed to be safe on shared clusters:

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Two-Phase Deployment #

The event stack is deployed in two sequential phases:

Phase 1 - The Base - Operators and CRDs: Deploys operator Deployments, RBAC resources, and Custom Resource Definitions. The install script waits for each operator to become ready before proceeding.

Phase 2 - The Stack - Operands: Deploys the actual workloads as Custom Resources (Kafka, ApicurioRegistry3, Console). Operators must be running to process these resources.

This separation exists for three reasons:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Operator Not Becoming Ready #

If an operator deployment does not reach Ready/Available within the timeout:

# Check the deployment status
kubectl describe deployment/strimzi-cluster-operator -n strimzi

# Check operator pod logs
kubectl logs -n strimzi deployment/strimzi-cluster-operator

# Check for pending pods (resource constraints)
kubectl get pods -n strimzi -o wide

Common causes:

Insufficient resources — the cluster may not have enough CPU or memory. This can often be an issue if you have selected an overlay which multiple components on top of the core. Try increasing resources assigned to your Kubernetes cluster: minikube start --cpus=8 --memory=12g
Image pull errors — check that the cluster can reach container registries (quay.io, docker.io)
Timeout too short — increase with TIMEOUT=300s

Custom Resource Not Reconciling #

If a Kafka, Registry, or Console resource is stuck: