@dmgnr/kuber 2.0.0 → 2.2.0

package/README.md

@@ -28,6 +28,20 @@ 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
@@ -357,7 +371,8 @@ your shell configuration. Fish and PowerShell are also supported through
 - `exec <deployment> <command...>`: execute a command inside a running
   deployment pod over an interactive WebSocket
 - `restart [deployment]`: roll out a restart across managed deployments
-- `stop`: scale managed deployments to zero
+- `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
@@ -485,6 +500,39 @@ Translation rules:
 - `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: