kuberoku 0.2.1

Heroku-like DX on vanilla Kubernetes — CLI + SDK, zero server-side components.

kuberoku

Heroku-like DX on vanilla Kubernetes.
CLI + SDK. Zero server-side components. Open source.

---

You bring a Kubernetes cluster. Kuberoku gives you apps:create, deploy, config:set, services:logs --tail, and everything else you loved about Heroku — without vendor lock-in, without YAML, without installing anything on your cluster.

Install

pipx install kuberoku                                    # Python (recommended)
pip install kuberoku                                     # Python (alternative)

# Linux / macOS binary
curl -fsSL https://github.com/amanjain/kuberoku/releases/latest/download/install.sh | sh

# Windows (PowerShell)
irm https://github.com/amanjain/kuberoku/releases/latest/download/install.ps1 | iex

Pre-built binaries for Linux, macOS, and Windows are available on the GitHub Releases page.

Requires kubectl configured with a valid kubeconfig. The Python install requires Python 3.11+; the binary install has no Python dependency.

Quick start

Already have a cluster?

From zero to a running app accessible on the internet:

kuberoku apps:create myapi
kuberoku deploy --app myapi --image nginx:1.27 --port 80/tcp
kuberoku services:connect --app myapi                          # test locally
kuberoku services:expose:on --app myapi web                    # get a public IP
kuberoku config:set --app myapi GREETING=hello SECRET_KEY=abc123
kuberoku services:logs --app myapi --tail

That's it. No Deployments, Services, ConfigMaps, or Ingress manifests. Kuberoku created them all.

Need a cluster first?

Local (fastest way to try):

We recommend k3d — it's the fastest to start and lightest on resources.

macOS

# k3d (recommended)
brew install k3d && k3d cluster create dev

# or kind
brew install kind && kind create cluster

# or minikube
brew install minikube && minikube start

Ubuntu / Debian

# k3d (recommended) — requires Docker
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
k3d cluster create dev

# or kind
curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-amd64
chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind
kind create cluster

# or minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
minikube start

Fedora / RHEL

# k3d (recommended) — requires Docker or Podman
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
k3d cluster create dev

# or kind
curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-amd64
chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind
kind create cluster

Arch Linux

# k3d (recommended)
yay -S k3d-bin && k3d cluster create dev

# or kind
pacman -S kind && kind create cluster

Then run the five commands above.

Cloud:

Provider	Quickest path
AWS	eksctl create cluster --name dev (docs)
GCP	gcloud container clusters create dev (docs)
Azure	az aks create -g dev -n dev (docs)
DigitalOcean	doctl kubernetes cluster create dev (docs)

Kuberoku works on any conformant K8s cluster (1.33+). No special setup required.

What you get

Deploy and scale

kuberoku deploy --app myapi --image myapi:v2       # deploy a pre-built image
kuberoku ps:scale --app myapi web=3 worker=2        # scale independently
kuberoku ps:restart --app myapi                      # rolling restart
kuberoku ps:type --app myapi web --cpu 500m --memory 512Mi

Config and secrets

kuberoku config:set --app myapi DATABASE_URL=postgres://... API_KEY=secret
kuberoku config:set --app myapi --secret STRIPE_KEY=sk_live_...
kuberoku config --app myapi                   # secrets are masked
kuberoku config:unset --app myapi API_KEY

Config changes automatically trigger a rolling restart and create a new release.

Releases and rollbacks

kuberoku releases --app myapi                 # list all releases
kuberoku releases:info --app myapi 3          # inspect a specific release
kuberoku releases:rollback --app myapi        # roll back to previous
kuberoku releases:rollback --app myapi 2      # roll back to specific version

Every deploy, config change, and rollback creates an immutable release. Full audit trail.

Built-in addons

kuberoku addons:create --app myapi postgres           # PostgreSQL 16
kuberoku addons:create --app myapi redis              # Redis 7
kuberoku addons:create --app myapi redis --as cache   # named instances
kuberoku addons:credentials --app myapi postgres      # show connection string
kuberoku addons:backup --app myapi postgres            # pg_dump backup

DATABASE_URL and REDIS_URL are injected automatically. Addons run as StatefulSets with persistent storage.

Non-HTTP services

Not everything is a web app. Deploy SMTP servers, game servers, DNS, gRPC — anything TCP/UDP:

kuberoku apps:create gameserver
kuberoku deploy --app gameserver --image game:v1 --port 7777/udp --port 7778/tcp
kuberoku services:expose:on --app gameserver web --method loadbalancer
# External IP: 34.123.45.67  :7777/udp  :7778/tcp

Multi-cluster

kuberoku clusters:add production --context prod-eks
kuberoku clusters:add staging --context staging-k3d
kuberoku clusters:switch production
kuberoku clusters:doctor                      # cluster health checks

SDK

Every CLI command maps 1:1 to a Python method:

from kuberoku import Kuberoku

k = Kuberoku()

# Create and deploy
app = k.apps.create("myapi")
k.config.set("myapi", {"DATABASE_URL": "postgres://..."})
release = k.deploy.deploy("myapi", image="myapi:v2", ports=[{"containerPort": 8080, "protocol": "TCP"}])

# Inspect
for app in k.apps.list():
    print(f"{app.name} v{app.release_version} ({'maintenance' if app.maintenance else 'active'})")

# Scale and rollback
k.ps.scale("myapi", {"web": 3})
k.releases.rollback("myapi")

All methods return frozen dataclasses. No K8s types leak into your code.

All commands

Group	Commands
apps	create destroy info rename status link:add link:remove maintenance:on maintenance:off
deploy	deploy (image or build-from-git)
config	set get unset
ps	scale restart stop type set commands
releases	info rollback prune
services	expose:on expose:off open connect ports:add ports:remove logs exec maintenance:on maintenance:off
addons	create destroy info scale migrate migrate-rollback credentials credentials-rotate exec backup expose:on expose:off connect
domains	add remove clear
clusters	add remove switch current info doctor setup
plugins	install uninstall search

Run kuberoku <group> --help for details on any command.

How it works

Kuberoku stores all state in standard Kubernetes resources — ConfigMaps, Secrets, Deployments, Services, Ingress, NetworkPolicies. No CRDs, no operators, no server-side components. Uninstall kuberoku and your apps keep running.

You  ──>  kuberoku CLI (Click)  ──>  SDK (business logic)  ──>  K8s API
                                      |
                                 also importable as Python SDK

The SDK is a strict three-layer architecture. The CLI never touches K8s directly. A typing.Protocol abstracts the K8s client, making the entire stack testable with an in-memory fake.

See docs/NORTHSTAR.txt for the complete specification.

Project status

Alpha. Kuberoku is under active development. The core commands work and are well-tested, but the API may change between releases. Use it for development, staging, and side projects. Evaluate thoroughly before using in production.

If something breaks, please open an issue.

Security

If you discover a security vulnerability, please report it responsibly via GitHub's private security reporting instead of opening a public issue.

Contributing

Contributions welcome. Start with the NORTHSTAR spec to understand the architecture.

git clone https://github.com/amanjain/kuberoku.git
cd kuberoku
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
mypy src/kuberoku/ --strict         # strict type checking
ruff check src/ tests/              # lint

License

Apache 2.0

Author

Built by Aman Kumar Jain.