# kuber `kuber` is a Docker Compose to Kubernetes translation layer backed by a self-hosted management service (`kuber-server`). It reads a local Compose file, renders Kubernetes resources, and applies them to the cluster through an authenticated v2 API. Image builds happen inside the cluster with rootless BuildKit, so the workstation needs neither Docker nor `kubectl`. ## Architecture ``` workstation (kuber CLI) ──HTTPS──▶ kuber-server (in-cluster pod) │ ├─ CAS (content-addressed blobs on RWX PVC) ├─ BuildKit Jobs (rootless) ──▶ registry └─ Kubernetes API (RBAC-scoped) ``` The CLI authenticates to the server with a Bearer token acquired by `kuber login`. It snapshots the repository into a content-addressed workspace, uploads only the blobs the server is missing, and submits a build request. The server materializes that workspace onto a shared RWX PVC and runs a rootless BuildKit Job that builds and pushes the image, then the CLI pins the resulting immutable registry digest into the rendered Deployment. The server also owns reconciliation: it plans, applies, and prunes resources in a per-project namespace, reconciles managed Postgres and S3 claims, rolls deployments back, streams logs, and exposes interactive `exec` sessions over a WebSocket. ## Directory Trust Before `kuber up`, run `kuber trust` from the configured project directory. Trust is exactly the configured namespace plus a SHA-256 fingerprint of the resolved current working directory. The local mode-0600 store lets `up` fail before builds from an untrusted directory. The server stores only namespace and fingerprint registrations in labelled ConfigMaps in its `kuber-system` control plane namespace, then checks the pair when resource reconciliation begins. This is an accidental-targeting safeguard, not a security boundary: a client that intentionally forges a registered fingerprint can pass it. `kuber trust status` shows local/server awareness without printing paths; `kuber trust revoke` removes the current directory registration. ## Environment Assumptions kuber targets a specific self-hosted cluster and workstation setup. It is not intended to run unchanged against an arbitrary Kubernetes environment. The expected setup: - an account on the `kuber-server` management API - a working ClusterRole/Role (see [Server Deployment](#server-deployment)) - a registry the in-cluster BuildKit can push to Not required locally: - Docker - `kubectl` ## API Origin The v2 management API has one hard-coded origin: ```text https://kuber.astrxl.dev/api/v2 ``` ## Authentication ```bash kuber login dmgnr kuber login dmgnr --persist kuber whoami kuber logout ``` The default login is stored with mode `0600` under `$XDG_RUNTIME_DIR/kuber/session.json` and disappears with the user runtime directory. `--persist` instead uses `$XDG_CONFIG_HOME/kuber/session.json`, or `~/.config/kuber/session.json` when `XDG_CONFIG_HOME` is unset. Password input is never echoed. Runtime sessions last 24 hours and persistent sessions last 30 days; `logout` revokes the server-side session. `readSession` falls back to the persistent file when no runtime session exists. The default login is scoped to the current user and the authenticated identity is available to every v2 command. `login`, `logout`, `whoami`, and global `maintenance` are the only commands that run without a loaded project configuration. ### API Keys Create API keys for automation or other non-interactive clients. Keys belong to a user and carry explicit capabilities; use the smallest capability set the task needs. The `--workspace` option further restricts Kubernetes access to one workspace. Capabilities describe *what* the key may do, while workspace scope describes *where* its Kubernetes access applies; neither replaces the other. Valid capabilities are `kubernetes:read`, `kubernetes:write`, `kubernetes:exec`, `users:read`, `users:write`, `sessions:revoke`, and `platform:adopt`. For example, a deployment key that only reads and updates resources in the `website` workspace can be created with: ```bash kuber users keys create deployer --capabilities kubernetes:read,kubernetes:write --workspace website ``` The default expiry is 90 days. Set `--expires-days` to an integer from 1 to 365, or explicitly use `none` for a key that does not expire: ```bash kuber users keys create deployer --capabilities kubernetes:read --expires-days 30 kuber users keys create deployer --capabilities kubernetes:read --expires-days none ``` The raw token is printed once at creation. Copy it directly into a secret manager; it cannot be retrieved later. List keys (optionally filtered by owner) to find the key ID, then revoke a compromised or retired key: ```bash kuber users keys ls kuber users keys ls deployer kuber users keys revoke deployer ``` Revoking a key immediately prevents it from authenticating. Do not place API tokens in source control, command-line arguments, or committed configuration. ### CI Integration Create a dedicated automation user/key with only the capabilities required by the CI job, and set the token as a masked repository or organization secret (for example, `KUBER_API_TOKEN`). Expose the secret as an environment variable for the job step. Commands that use the v2 API can then authenticate with that token without an interactive `kuber login`: ```yaml - name: Deploy with kuber env: KUBER_API_TOKEN: ${{ secrets.KUBER_API_TOKEN }} run: kuber up ``` Use the CI provider's secret store, never commit the token or print it in logs. For example, a workspace-scoped key with `kubernetes:read,kubernetes:write` allows deployment operations in that workspace, but does not grant user administration, exec, or platform adoption. Add a capability only when the job needs that operation, and choose `--workspace` to limit its Kubernetes scope. ### Roles and Authorization The server grants capabilities through three roles: - `viewer` — read-only cluster access (`kubernetes:read`) - `operator` — `viewer` plus `kubernetes:write` and `kubernetes:exec` - `admin` — all capabilities, including user administration (`users:read`, `users:write`, `sessions:revoke`, `platform:adopt`) Administer users with the `users` command tree: ```bash kuber users ls kuber users add dmgnr --roles admin kuber users update dmgnr --roles operator kuber users update dmgnr --password kuber users disable dmgnr kuber users enable dmgnr kuber users delete dmgnr kuber users revoke dmgnr ``` `users add`, `update --password`, and `delete` prompt for password / written confirmation on an interactive terminal. Passwords are hashed with Argon2id on the server and never stored in plaintext. Updating a user's roles or password revokes all of that user's active sessions. Inspect server-side operations and the audit trail: ```bash kuber operations ls kuber operations get kuber audit ls ``` ## Server Deployment The repository's `compose.yml` owns the `kuber-system` namespace, the `kuber-server` image, its Deployment, Service, and Ingress. `.kuberrc.ts` extends the rendered manifests with the server's ServiceAccount and RBAC: - a namespaced `Role`/`RoleBinding` (`kuber-server-auth`) for the `kuber-system` Secrets, ConfigMaps, Pods, Jobs, and Leases the server itself reads and writes - a `ClusterRole`/`ClusterRoleBinding` (`kuber-server-manager`) granting the cross-namespace verbs it needs to manage user projects `compose.yml` runs the server as a non-root user (`runAsUser`/`runAsGroup` `1000`), drops all Linux capabilities, uses a read-only root filesystem with a `RuntimeDefault` seccomp profile, and backs `/data` with a Longhorn PVC (`kuber-build-data`). The PVC hosts the CAS, materialized workspaces, and resumable upload bytes, and is shared with BuildKit Jobs. Deploy the server with kuber itself: ```bash KUBER_BOOTSTRAP_PASSWORD='replace-me' kuber up ``` The server creates an `admin` user (from `KUBER_BOOTSTRAP_USERNAME`, default `dmgnr`) on first boot only if that user does not already exist. The bootstrap Secret is only rendered while `KUBER_BOOTSTRAP_PASSWORD` is set. After logging in successfully, reconcile without that variable and restart once so kuber removes the stale bootstrap Secret and the password leaves the pod environment: ```bash kuber up --no-b kuber restart kuber-server ``` See [Account Recovery](#account-recovery) for what to do if you are locked out. ### Security Constraints Because the server's ServiceAccount is scoped by the RBAC in `.kuberrc.ts`, it can only act on the resources kuber manages. The management layer additionally enforces ownership, so the server refuses to mutate resources that do not carry kuber's workspace labels. Deleting a resource requires its UID as an optimistic concurrency precondition, and workspace deletion also requires the namespace UID. Namespaces that are not owned by kuber, or owned by a different workspace, are never mutated (see [Workspaces and Migration](#workspaces-and-migration)). ## Workspaces and Migration Each project maps to a Kubernetes namespace derived from the current working directory. The CLI records a "workspace" on the server keyed by project name and borrows the namespace UID to guarantee it owns the namespace before reconciling. Adopting existing resources relabels them (Server-Side Apply) only when they are already managed by kuber and not owned by another workspace. `up` refuses to mutate a namespace when: - the namespace already exists but does not carry kuber's managed-by label (`external`), or - the namespace is labeled for a different workspace UID (`different-workspace`) In those cases the CLI prints a hint to `POST /workspaces//adopt` with the namespace UID to complete a safe, explicit adoption. The platform namespace (`kuber-system`) is adopted through the admin-only platform adoption route. Workspace state, revisions, operations, and audit events are stored as Secrets and ConfigMaps in `kuber-system` keyed by kuber's `kuber.astrxl.dev/type` label. Workspace updates are optimistic (If-Match on resource version) and immutable revisions are recorded so history survives. Expired sessions are cleaned up on an interval, and stale operations are marked failed on server startup recovery. ### Migration Behavior `kuber up` is idempotent and safe to re-run. Each run: 1. snapshots the workspace and uploads missing blobs to the server CAS, 2. ensures the workspace record (creating or updating it with an optimistic If-Match), 3. adopts the namespace and its kuber-managed resources, 4. reconciles managed Postgres and S3 claims, 5. renders manifests, plans the diff, applies desired resources, waits for rollout, and deletes stale resources. Because resource references are immutable digests, re-running `up` only restarts deployments whose image content actually changed. `start` re-resolves published digests without building. ## Registry Authentication Building and pushing images from inside the cluster typically requires credentials for the target registry. These are read from a Docker config file (`KUBER_REGISTRY_CONFIG`, default `/etc/kuber/registry/config.json`) and mounted as an image pull secret named by `KUBER_REGISTRY_SECRET`. Registry authentication is optional. If `KUBER_REGISTRY_SECRET` is unset, the server warns at startup and BuildKit uses anonymous registry access. This is intended for registries that allow anonymous push/pull. The same credentials are used when the server resolves a published image digest (`start` / `export`). The server supports both standard registry bearer-token (`WWW-Authenticate: Bearer`) and pre-emptive Basic auth when resolving digests. ### Build Registry Environment The server's registry behavior is driven by a few closely related environment variables: - `KUBER_BUILD_REGISTRY` (default `registry.neko-piranha.ts.net`): the registry the in-cluster BuildKit pushes built images to and `kuber` uses as the image namespace. It also supplies the registry host for authentication. - `KUBER_INTERNAL_REGISTRY_HOST`: the host of an internal registry (for example the in-cluster distribution service) used for the BuildKit cache image and, when set, the image direct push target. When unset, push and cache fall back to `KUBER_BUILD_REGISTRY`. - `KUBER_INTERNAL_REGISTRY_INSECURE`: set to `"true"` to push to the internal registry over plain HTTP instead of HTTPS. Only meaningful when `KUBER_INTERNAL_REGISTRY_HOST` is set. - `KUBER_PUSH_IMAGE_PREFIX` (default `kuber/`): a prefix applied to project images pushed to the internal registry when `KUBER_INTERNAL_REGISTRY_HOST` is configured. - `KUBER_REGISTRY_RESOLVE_ORIGIN`: an explicit origin used to resolve a published image digest (used by `start` / `export`). Useful when the digest must be resolved from a different endpoint than the build/push registry, such as an internal HTTP registry. - `KUBER_REGISTRY_CONFIG`: path to the Docker config file with registry credentials (see above). - `KUBER_REGISTRY_SECRET`: the image pull Secret mounted for BuildKit's registry access. - `KUBER_BUILDKIT_IMAGE`: override the BuildKit runner image used for builds. - `KUBER_BUILD_DATA_CLAIM`: the PVC claim backing builds. - `KUBER_BUILD_RECONCILE_MS` (default `30000`): the background build reconciliation interval in milliseconds. Values must be greater than zero and no greater than `2147483647` (the JavaScript timer maximum); invalid values use the default. - `KUBER_BUILD_RECONCILE_TIMEOUT_MS` (default `20000`, maximum `25000`): the deadline for one background build-reconciliation scan in milliseconds. The maximum leaves time within the 30-second reconciliation lease for normal renewal or release. The reconciler renews both its workspace and per-build leases every 10 seconds for the lifetime of a generation, including while an observation, log read, or store call is pending. On timeout its abort signal is cancelled and logged, but Kubernetes requests may be unabortable; the generation remains active and continues its lease heartbeat until that request settles, so a later scan cannot overlap it. See [Server Deployment](#server-deployment) for how `compose.yml` wires the internal registry variables for the kuber-server pod. ## Account Recovery If you lose your credentials and cannot log in: 1. Recreate the bootstrap admin by deploying with `KUBER_BOOTSTRAP_PASSWORD` set again: ```bash KUBER_BOOTSTRAP_PASSWORD='new-password' kuber up --no-b kuber restart kuber-server ``` 2. The server only creates the bootstrap user if the account does not already exist, so a fresh `kuber login ` with the new password works, or use the newly created admin to reset other accounts: ```bash kuber users update --password ``` 3. After recovering, reconcile without `KUBER_BOOTSTRAP_PASSWORD` and restart so the bootstrap Secret is removed and the password leaves the pod environment. Because user records and session hashes are stored as Secrets in `kuber-system`, recovery relies on cluster administrators being able to redeploy the server with bootstrap credentials. `users revoke ` forcibly logs a user out across all devices. ## Next.js Example [`example/`](example/) contains a documented deployment template for adding kuber to an existing Bun-powered Next.js project without initializing or bundling an application in this repository. It includes a standalone-output Dockerfile, `.dockerignore`, `compose.yml`, and the required Next.js configuration. ## Running During development: ```bash bun run index.ts up ``` Run the dedicated unit suite and type checks: ```bash bun run test bun run typecheck ``` Other useful commands: ```bash bun run index.ts ps bun run index.ts logs bun run index.ts logs -f bun run index.ts exec app sh bun run index.ts start bun run index.ts stop bun run index.ts restart bun run index.ts rollback bun run index.ts fuck app bun run index.ts db ls bun run index.ts s3 ls bun run index.ts s3 creds app bun run index.ts s3 ui app bun run index.ts login dmgnr bun run index.ts users ls bun run index.ts operations ls bun run index.ts audit ls ``` All commands accept `--config` to use a configuration file other than `.kuberrc.ts`: ```bash kuber --config production.kuberrc.ts up kuber up --config production.kuberrc.ts ``` `login`, `logout`, and `whoami` are context-free and do not require a configuration. ### Shell Completion Generate and load completions for your shell: ```bash source <(kuber complete zsh) source <(kuber complete bash) ``` For a permanent setup, write the generated script to a file and source it from your shell configuration. Fish and PowerShell are also supported through `kuber complete fish` and `kuber complete powershell`. ## Commands - `up [--no-b]`: build images if needed, ensure the workspace, reconcile managed Postgres/S3, render manifests, apply them, wait for rollout, and delete stale resources - `start`: like `up` but re-resolves the currently published image digests instead of building - `login [username] [--persist]`: authenticate with the kuber API - `logout`: revoke and remove the current API session - `whoami`: show the authenticated API user and roles - `users`: administer user accounts and roles - `operations`: inspect server-side reconciliation operations - `audit`: inspect the audit trail - `ps [-a]`: print an ANSI graph of the current project namespace, hiding stopped deployments by default - `logs [deployment] [-f]`: print (or follow) logs for one deployment or all managed deployments - `exec `: execute a command inside a running deployment pod over an interactive WebSocket - `restart [deployment]`: roll out a restart across managed deployments - `stop`: delete the matching name-scoped HPAs (so autoscaling cannot scale replicas back up) and scale managed deployments to zero - `rollback` (alias `fuck`) `[deployment]`: roll one deployment back to its previous release, or all managed deployments when no name is given - `down [-f]`: delete managed resources while keeping ingress, PVCs, managed databases, and managed S3 storage; `-f` also deletes those and the namespace - `db ls` / `db creds `: list or print credentials for managed Postgres claims - `s3 ls` / `s3 creds ` / `s3 ui `: list managed S3 claims, print their credentials, or print the Garage UI URL for a bucket - `export [-o file]`: render manifests to a YAML file without applying them Lifecycle commands (`restart`, `stop`, `rollback`, `down`) are idempotent: identical requests are deduplicated server-side and tracked as operations. ## Configuration Kuber optionally loads `.kuberrc.ts` from the working directory. The file must default export an object satisfying the published `KuberConfig` type: ```ts import type { KuberConfig } from "@dmgnr/kuber"; export default { project: "my-app", composeFile: "compose.production.yml", registry: "registry.example.com", rolloutTimeoutMs: 10 * 60_000, async compose(compose) { const app = compose.services?.app; if (app && !Array.isArray(app.environment)) { app.environment ??= {}; app.environment.NEXT_PUBLIC_BUILD_ID = await Bun.$`git rev-parse --short HEAD` .text() .then((value) => value.trim()); } }, } satisfies KuberConfig; ``` Operational defaults: - `project`: Compose top-level `name`, falling back to the current working directory name - `composeFile`: the first recognized Compose filename in the working directory - `registry`: `registry.neko-piranha.ts.net` - `rolloutTimeoutMs`: `300000` Project-name precedence is `.kuberrc.ts project`, Compose top-level `name`, then the current working directory name. The `registry` value controls which registry the CLI requests build images from and which the server uses to resolve published digests. `rolloutTimeoutMs` bounds how long `up` and `rollback` wait for a Deployment rollout. Configuration hooks can be synchronous or asynchronous and receive mutable values: - `compose(compose, context)`: once after parsing and validation; affects every command that reads Compose - `preBuild(compose, context)`: before build eligibility is evaluated when builds are enabled - `postBuild(result, context)`: after images are built; `result` contains `built` and `changed` service names - `postRender(resources, context)`: after rendering and before reconciliation planning; also runs for `export` - `postApply(resources, context)`: after desired resources are successfully applied Hook context contains the resolved `cwd`, `project`, `composeFile`, and optional `configFile`. A hook error aborts the command and is reported by the normal CLI error handler. Registry and rollout configuration remain part of the CLI-facing contract. Image builder selection is not configurable: builds are scheduled, executed, and owned entirely by the server. ## Compose Conventions `kuber` supports a few project-specific Compose conventions on top of normal service translation. ### Host-Based Ports If a `ports` entry uses a hostname instead of a numeric published port, `kuber` treats it as an ingress host and routes traffic to the target container port. Example: ```yml services: app: ports: - somedomain.astrxl.dev:3000 ``` That produces a Kubernetes `Ingress` rule for `somedomain.astrxl.dev` pointing at the service port for container port `3000`. Single-level wildcard subdomains are supported. Quote wildcard entries so YAML does not treat the leading `*` as an alias: ```yml services: app: ports: - "*.astrxl.dev:3000" - "*.secure.astrxl.dev:3001:protected" ``` Protected routes use the kuber dialect and render Traefik `IngressRoute` resources instead of plain Kubernetes `Ingress`: ```yml services: app: ports: - db.astrxl.dev:4984:protected - status.astrxl.dev:3001:protected(/dashboard,/socket.io) ``` Translation rules: - `host:port` -> Kubernetes `Ingress` - `host:port:protected` -> Traefik `IngressRoute` with middleware `routing/cf-auth` and host-wide matching - `host:port:protected(path1,path2,...)` -> Traefik `IngressRoute` with middleware `routing/cf-auth` and explicit `PathPrefix(...)` matches only ### Replicas and Autoscaling `deploy.replicas` (or the top-level `scale` field) controls the Deployment replica count. A plain integer or numeric string renders a fixed `replicas` value, with `scale` taking precedence over `deploy.replicas`. A `"min-max"` range string requests autoscaling instead of a fixed count: ```yml services: app: image: app deploy: replicas: "2-6" ``` kuber renders: - a `Deployment` with `replicas` set to the range minimum (`2`) - a `HorizontalPodAutoscaler` (`autoscaling/v2`) targeting that Deployment, with `minReplicas: 2`, `maxReplicas: 6`, and a CPU target of 80% utilization - a `100m` CPU request injected into the container, unless `x-container` already specifies a CPU request (the HPA needs a CPU request to scale on) For both fixed counts above one and autoscaled ranges whose maximum exceeds one, kuber also adds a `topologySpreadConstraints` entry spreading pods across hosts (`kubernetes.io/hostname`, `maxSkew: 1`, `whenUnsatisfiable: ScheduleAnyway`). Malformed non-numeric replica values (for example `"lots"`) are rejected with a clear error instead of silently defaulting. ### Managed Postgres You can declare a managed Postgres database with a pseudo-volume: ```yml services: app: volumes: - postgresql:app ``` Or with an explicit username and database name: ```yml services: app: volumes: - postgresql:user/database ``` This creates or reuses the managed CNPG role secret, reconciles the database resource, and injects `DATABASE_URL` and `REDIS_URL=redis://redis.database.svc.cluster.local` into the generated app secret in Kubernetes. `REDIS_URL` is only added to services with a managed Postgres claim. Running `kuber db creds ` performs the same focused Secret, role, and Database reconciliation before printing credentials. ### Managed S3 Declare a Garage S3 bucket and access key with a pseudo-volume: ```yml services: app: volumes: - s3:app ``` This creates `GarageBucket/app` and `GarageKey/app` in `garage-system`. To use different key and bucket names: ```yml services: app: volumes: - s3:app-key/shared-assets ``` The Garage operator generates the credentials. `kuber` reads its generated Secret and injects these values into the service's `-env` Secret: - `AWS_ACCESS_KEY_ID` - `AWS_SECRET_ACCESS_KEY` - `AWS_ENDPOINT_URL_S3` - `AWS_REGION` - `S3_BUCKET` One service can declare both `postgresql:...` and `s3:...`; all generated values are merged into the same service Secret. Managed Garage buckets and keys are retained by normal `down` and deleted by `down -f`. Inspect a claim, print its generated credentials, or get its Garage UI URL: ```bash kuber s3 ls kuber s3 creds app kuber s3 ui app ``` `s3 creds` prints `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION`, and `S3_BUCKET` as shell-style environment assignments. `s3 ui` only prints the URL; it does not open a browser. ### Environment Files `env_file` entries are read locally and turned into a Kubernetes `Secret` named `-env`. Deployments then consume that secret through `envFrom`. This is also where generated values such as `DATABASE_URL` and the managed S3 environment are injected. ### Volumes `kuber` treats different volume shapes differently: - file bind mounts become ConfigMaps - directory bind mounts become PVC-backed mounts - named volumes become PVC-backed mounts - `tmpfs` becomes `emptyDir` with memory backing - `postgresql:...` is treated as a managed database claim, not as a filesystem mount - `s3:...` is treated as a managed object-storage claim, not as a filesystem mount Named volumes also support kuber-specific Longhorn storage hints. Kuber renders each distinct placement policy as a deterministic, reusable Longhorn `StorageClass`, then references that class from the PVC. The generated class uses Longhorn's `numberOfReplicas`, `diskSelector`, and `dataLocality` parameters; placement fields are never written directly to the PVC. Default behavior: ```yml # compose services: app: volumes: - myvolume:/data # effective kuber interpretation services: app: volumes: - myvolume(1Gi on 2 fast):/data ``` Short syntax: ```yml services: app: volumes: - data(20Gi):/data - archive(200Gi on archive):/archive - cache(10Gi on 1 fast):/cache ``` Meaning: - `name(20Gi):/path` -> PVC size `20Gi` - `name(20Gi on archive):/path` -> PVC size `20Gi`, with a StorageClass using `diskSelector: "archive"` and disabled data locality - `name(20Gi on 1 archive):/path` -> PVC size `20Gi`, with a StorageClass using one replica and `diskSelector: "archive"` Explicit extensions are also supported. Top-level named volume: ```yml volumes: data: x-size: 20Gi x-diskTag: [archive] x-replicaCount: 1 x-dataLocality: none ``` Long-form service mount: ```yml services: app: volumes: - type: volume source: data target: /data volume: x-size: 20Gi x-diskTag: [archive] x-replicaCount: 1 x-dataLocality: none ``` Precedence: - short syntax like `data(20Gi on 1 archive):/data` - long-form `volume.x-*` - top-level `volumes..x-*` - fallback default `1Gi on 2 fast` StorageClasses are cluster-scoped and content-addressed by policy. They are shared across projects and intentionally retained when a project is removed. ## Building When a service declares `build`, the CLI: 1. snapshots the repository into a content-addressed workspace (committed git state, tracked changes, untracked files, and ignored `.env*` files), 2. negotiates with the server and uploads only the blobs it is missing, 3. submits a build request; the server materializes the workspace from the CAS onto a shared RWX PVC and runs a rootless BuildKit Job that builds and pushes the configured image with registry cache. Build containers are restricted: they run as non-root (`runAsUser`/`runAsGroup` `1000`), do not mount the service account token, and only read the workspace (read-only mount) and a writable BuildKit state `emptyDir`. After a push, the registry's manifest digest is captured and embedded into the rendered Deployment as an immutable `:latest@sha256:...` reference, so a changed image naturally triggers a rollout. `start` and `export` look up the currently published digest without rebuilding, and fail if a buildable service has no published image yet. `export` is side-effect-free: it refuses to render managed Postgres or S3 claims (because it cannot call the server to generate credentials) and instead tells you to run `kuber up` or remove the managed provider claims. ## Rollback `kuber rollback [deployment]` (alias `fuck`) rewinds managed Deployments to the previous release. ReplicaSets carry a `deployment.kubernetes.io/revision` annotation, and rollback restores the complete pod template from the next-older ReplicaSet via a JSON Patch, then waits for the rollout to complete. With no argument every managed Deployment is rolled back; pass a deployment name to target a single one. Notes and limitations: - Kubernetes only keeps its most recent ReplicaSets, so an older release may no longer be reachable after enough successful rollouts/rollbacks. - Rollback restores the pod template (including image and environment), not live Secret, ConfigMap, PVC, database, or S3 state. - A later `kuber up` or `kuber start` re-resolves `:latest` and returns the Deployment to the current desired state anyway, so rollback is the right tool for responding to a bad deploy, not for permanently pinning an old version. - Rollback only considers Deployments managed by kuber (`app.kubernetes.io/managed-by=kuber`) and only runs within a workspace whose namespace kuber owns. ## Workspace State and Operations The server persists per-workspace state, revisions, operations, and audit events as Secrets/ConfigMaps in `kuber-system`. Mutations are idempotent: - operations carry an idempotency key so retries do not double-apply, - resource deletion requires a UID precondition, - workspace replacement is guarded by If-Match. The CLI is built with the normal `build` script for distribution and local use: ```bash bun run build ``` ## Notes - Resource names and namespaces are derived from the current working directory. - The workspace snapshot is optimized for local iteration, not for producing a perfectly clean export of the repository. - Managed database support is Kubernetes-only. It injects `DATABASE_URL` into the generated app secret and does not rewrite local `.env` files. - `kuber` operates on managed resources in the namespace matching the current directory name. - Builds are scheduled, executed, and owned by the server. There is no local SSH/daemon builder configuration; `registry` and `rolloutTimeoutMs` remain CLI-facing settings.