<p align="center">
  <h1 align="center">kuberoku</h1>
  <p align="center">Heroku-like DX on vanilla Kubernetes.<br>CLI + SDK. Zero server-side components. Open source.</p>
</p>

<p align="center">
  <a href="https://github.com/amanjain/kuberoku/actions"><img src="https://github.com/amanjain/kuberoku/actions/workflows/tests.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/kuberoku/"><img src="https://img.shields.io/pypi/v/kuberoku" alt="PyPI"></a>
  <a href="https://pypi.org/project/kuberoku/"><img src="https://img.shields.io/pypi/pyversions/kuberoku" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
</p>

---

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

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

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

```powershell
# 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](https://github.com/amanjain/kuberoku/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?

Five commands from zero to a running app:

```bash
kuberoku apps:create myapi
kuberoku deploy --app myapi --image nginx:1.27 --port 80/tcp
kuberoku config:set --app myapi GREETING=hello SECRET_KEY=abc123
kuberoku ps:scale --app myapi web=3
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](https://k3d.io) — it's the fastest to start and lightest on resources.

<details>
<summary><strong>macOS</strong></summary>

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

# or kind
brew install kind && kind create cluster

# or minikube
brew install minikube && minikube start
```

</details>

<details>
<summary><strong>Ubuntu / Debian</strong></summary>

```bash
# 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
```

</details>

<details>
<summary><strong>Fedora / RHEL</strong></summary>

```bash
# 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
```

</details>

<details>
<summary><strong>Arch Linux</strong></summary>

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

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

</details>

Then run the five commands above.

**Cloud:**

| Provider | Quickest path |
|----------|--------------|
| **AWS** | `eksctl create cluster --name dev` ([docs](https://eksctl.io)) |
| **GCP** | `gcloud container clusters create dev` ([docs](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster)) |
| **Azure** | `az aks create -g dev -n dev` ([docs](https://learn.microsoft.com/en-us/azure/aks/learn/quick-kubernetes-deploy-cli)) |

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

## What you get

### Deploy and scale

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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

```bash
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:

```python
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`](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](https://github.com/amanjain/kuberoku/issues).

## Security

If you discover a security vulnerability, please report it responsibly via [GitHub's private security reporting](https://github.com/amanjain/kuberoku/security/advisories/new) instead of opening a public issue.

## Contributing

Contributions welcome. Start with the [NORTHSTAR spec](docs/NORTHSTAR.txt) to understand the architecture.

```bash
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](LICENSE)

## Author

Built by [Aman Kumar Jain](https://github.com/amanjain).
