mirror of https://github.com/hanzo-apps/HIPs.git synced 2026-10-30 14:47:28 +00:00

Files

T

zeekay ad5a010f79 Three words for what a proposal is, and a generator that refuses

The same fact lived in nine hand-kept places and they disagreed about 58
proposals. This makes the file the only authority and everything else a
projection of it.

ONE VOCABULARY, in vocabulary.json, read by the lint, the generator and the
doc site. Three words, each answering "can I rely on this?" and nothing else:

    Draft    nothing implements it yet, or its own text says the work is ahead
    Final    the thing it specifies exists in the code
    Living   governance and process: amended in place, never finished

Eight spellings folded in. `Active` was the one doing real damage: on four Meta
and Process HIPs it meant living, on 48 others it meant shipped, and one word
doing two jobs is why nothing agreed. `Review` and `Last Call` described a
queue rather than a document, and a proposal under review is still one you
cannot build against.

STATUS IS EARNED, not declared. Every Standards Track proposal was checked
against the estate: 235 have their implementation, and eight do not and say so.
HIP-0095 carries a twelve-week plan ending at "mainnet launch" and has no code.
HIP-0525 specifies an all-machine meeting while apps/meet refuses a machine a
seat. HIP-0078 names a prover at a "planned location" that does not exist.
HIP-0114 is the cog.* procedure set, and that procedure set returns nothing.
HIP-0003, HIP-0102, HIP-0305 and HIP-0901 likewise: looked, found nothing.

SIXTEEN TOMBSTONES DELETED rather than statused. A dead document kept alive in
the index is one concept wearing two names. Each successor exists and carries
the text, and the 90 references that pointed at a tombstone now point at it --
whole markdown links at once, so link text cannot outlive its target. Three of
the sixteen were pure compatibility: HIP-0028 specified a migration off a
Bitnami chart, HIP-0029 dual-engine MySQL, HIP-0030 a schema-deprecation
policy. We ship no backwards compatibility, so we do not specify it.

Nine links were already broken and had been since the corpus was renumbered:
short-form ./hip-5.md paths that never existed. Two named the wrong proposal --
one cited "HIP-1: Hanzo Multimodal Models" where multimodal is HIP-0003.

THE GENERATOR REFUSES more often than it writes, because a short table looks
exactly as authoritative as a complete one. Rows must equal files; a shrinking
index must say by how much; a section whose input is missing is an error, not
an omission; nothing is written until all of it validates. Its self-test breaks
the corpus eleven ways and requires each to refuse AND leave README byte-
identical -- a guard that reports after half-writing has protected nothing.
The lint's second implementation of the same comparison is gone.

The site rendered 52 proposals with a fallback grey badge and counted them
toward none of its three stat tiles, because docs/lib/source.ts declared a
status union by hand: it admitted a `Stagnant` no file has ever carried and
omitted the one 52 files did. Five components each kept their own copy of the
colours. All six now read vocabulary.json.

2026-08-28 18:05:41 -07:00

7.4 KiB

Raw Permalink Blame History

hip, title, author, type, category, status, created, updated, requires

hip	title	author	type	category	status	created	updated	requires
0117	Cloud-in-a-Box — One Binary, Three Modes	Hanzo AI Team	Standards Track	Infrastructure	Final	2026-07-07	2026-07-08	HIP-0036, HIP-0106, HIP-0400

HIP-0117: Cloud-in-a-Box — One Binary, Three Modes

Abstract

This proposal defines the three deployment topologies of the ONE cloud binary (HIP-0106) — from a laptop to an HA cluster without changing the artifact:

cloud serve — single process, no Kubernetes: every subsystem in-process, per-tenant SQLite, datastore as a subprocess or gracefully absent. The true cloud-in-a-box for laptop, edge, and single-node installs.
cloud cluster init — the binary fetches k3s (it does NOT embed it), bootstraps a Kubernetes cluster, installs the operator, and hands reconciliation to services.hanzo.ai CRs (HIP-0400). Single command from bare metal to HA.
helm install — bring your own Kubernetes: the charts at cloud/helm/cloud deploy the same image into an existing cluster.

The mode is topology, not identity: same bits, same config surface, same product behavior. What runs is decided by HIP-0106 (plugins / enabled subsystems); where it runs is decided here — and nowhere else.

Motivation

An OSS AI cloud must install like a tool, not like a platform team. The competition for the first five minutes is docker run and curl | sh, not a 40-page Helm values reference. At the same time the production shape is an operator-reconciled Kubernetes estate (HIP-0400 CRs, HIP-0036 CI/CD). Historically these were different software: a "dev mode" binary and a "real" set of manifests that drifted apart.

HIP-0106 removed the reason for that split. The unified binary already runs every subsystem in one process against SQLite; Kubernetes adds scale-out and self-healing, not features. So the deployment story collapses to one artifact with three entry points, and the only real design question left is: does the binary embed the orchestrator?

The answer is no. Embedding k3s into cloud was considered and rejected:

App ≠ orchestrator. k3s is a cluster lifecycle concern with its own release cadence, CVE stream, and kernel-facing surface. Baking it into the app binary conflates two lifecycles that must upgrade independently.
Bloat. The one-binary measured ~303.6 MiB (HIP-0106 realized state); a k3s payload roughly triples it for a code path most deployments never execute.
Precedent. k3sup and Coder ship exactly this shape — a binary that fetches and bootstraps the orchestrator on demand — and it is the right separation: the app binary orchestrates the bootstrap; it is not the orchestrator.

Specification

Mode 1 — `cloud serve` (single process, no Kubernetes)

The binary IS the cloud:

All enabled subsystems mount in-process per HIP-0106 (registry + fail-closed embeds). Disabled-by-default activation and 503 blast-radius isolation apply unchanged.
Storage is per-tenant SQLite (HIP-1104, HIP-0302) under --data-dir. No external database exists in this mode — SQLite is the default, not the fallback.
datastore (columnar analytics store; the one non-Go exception per HIP-0106) runs as a locally supervised subprocess when present. When absent, analytics-dependent surfaces degrade fail-closed (503 on their prefixes) while everything else serves — the same isolation rule as any broken subsystem.
The IAM single-replica guard (HIP-0106 realized state) is trivially satisfied: there is exactly one replica.
Consensus/replication state per HIP-0106 runs in its single-node, in-memory shape: instant finality, zero configuration.

This mode is shipped: it is cloud.Serve — the same entry the SaaS runs — pointed at local storage. Edge and laptop installs are not a port; they are a smaller instance of production.

Mode 2 — `cloud cluster init` (the binary bootstraps its own cluster)

For bare metal / VM fleets with no existing Kubernetes:

Fetch k3s. The binary downloads a pinned k3s release and verifies its checksum before executing anything. The pin lives in the cloud release, so cloud version N always bootstraps a known orchestrator version — reproducible clusters, no latest.
Bootstrap. Install/start k3s (server on the first node; cluster join adds agents), write the kubeconfig.
Install the operator. Apply hanzoai/operator and the services.hanzo.ai CRDs (HIP-0400 family).
Reconcile. Apply the deployment's CRs; the operator pulls ghcr.io/hanzoai/<service> images (built by HIP-0036 lanes), creates the datastore as a StatefulSet, and converges the estate. From here on, day-2 is GitOps against CRs — cluster init is a bootstrapper, not a parallel management plane.

HA and scale-out are properties of this mode: multiple nodes, replica counts on CRs, and the durable Quasar/ZapDB substrate shape from HIP-0106.

Airgapped variant: an optional cloud-fat build go:embeds the pinned k3s binary for networks that cannot fetch. It is a separate build target, never the default — the default binary never carries an orchestrator. This is the ONLY sanctioned embedding of k3s.

Status: decided; staged behind the SaaS-first cutover. The operator, CRDs, and images it composes all exist and run production today (HIP-0400, HIP-0036); cluster init sequences them from the binary.

Mode 3 — `helm install` (bring your own Kubernetes)

For teams that already operate Kubernetes:

helm install cloud ./helm/cloud   # charts at hanzoai/cloud helm/cloud

The chart deploys the same ghcr.io/hanzoai/cloud image with the same config surface (--enable / CLOUD_* per HIP-0106) and pins replicas=1 while the embedded IAM is enabled (the session single-replica guard). BYO ingress-controller integration follows the estate topology of HIP-0112. Shipped: the chart exists in-tree at cloud/helm/cloud.

Mode invariants

One artifact. All three modes run the identical binary/image. A mode is a command-line entry point, never a fork or a build flag (the cloud-fat airgap variant differs only by the embedded k3s payload, not by application code).
One config surface. Enabled subsystems, brand, domain, IAM issuer, and data dir mean the same thing in every mode.
Same product in every mode. Per-product metering and balance-floor gating (HIP-0106 realized state; HIP-0018) apply identically — a single-node install bills like the SaaS.
Graduation is data motion, not migration. serve → cluster is: stand up the cluster, replicate the SQLite/ZapDB state (HIP-0107 / HIP-0302), repoint DNS. No schema rewrite, no "export".

References

HIP-0106 — Cloud — Unified Hanzo Binary (the artifact all three modes run and the product surface it serves; realized state documents cloud.Serve, the embeds, and the measured binary)
HIP-0106 — Hanzo Plugin & VM Model (what runs: plugins/subsystems + the single-node vs HA state substrate)
HIP-0400 — Service CRD (the operator/CR family cluster init installs and defers to)
HIP-0036 — CI/CD Build System Standard (the lanes that build the images the operator pulls)
HIP-0112 — Cloud Infrastructure Topology Standard (the estate shape Mode 2/3 converge to)
HIP-0107 / HIP-0302 — replication used for serve→cluster graduation concern)
k3sup, Coder — prior art for fetch-on-bootstrap orchestrator installation

7.4 KiB Raw Permalink Blame History