platform

Overview ¶

applylive.go — the ONE version-monotonic deploy mechanic shared by the image-source path (deployImage) and the git build reconciler.

Both paths must write the operator Service CR (applyService) AND advance the app's live pointer (FinalizeLive). FinalizeLive is already an atomic, monotonic CAS so the recorded live version can never regress. The remaining gap (RED LOW-1) is the CR write itself: two concurrent deploys of the SAME app could interleave so that an OLDER deploy's applyService lands AFTER a NEWER one already went live, leaving the live Service CR image lagging the recorded live version. applyLive closes that gap by running supersede-check → applyService → FinalizeLive as one per-app-serialized critical section: an older deploy that loses the race is superseded and never writes its (older) CR.

console.go — the flat, top-level console aggregates that the Hanzo Cloud Console's Environments / Pipelines / Builds / Releases pages render. They are NOT a new data model: every row is DERIVED from the SAME per-org project / application / deployment / build records the /v1/platform surface already owns (platform.go, deploy.go, store.go). One store, one deploy mechanic, four read-only projections:

• environment → a deploy target: the distinct Application.Environment values across the org's apps, each aggregating the apps that target it.
• pipeline → an app's build/deploy configuration + its latest run (one pipeline per application).
• build → a REAL arcd BuildKit build record (platform_builds); the git build step of a deploy. Never fabricated — real records or an honest empty.
• release → a deployment that was actually applied to the cluster (status deploying|live): a released image tag on an app/environment.

All four are GET-only. A pipeline/build/release is CREATED only through the ONE existing write path — POST /v1/platform/projects/{p}/apps (create app) and .../deploy (trigger a build+deploy) — so there is exactly one way to make them, never a duplicate trigger here. Environments are a scope derived from apps, not a standalone record, so there is nothing to create/delete independently either.

Every handler is org-scoped through the SAME validated-principal gate as the rest of the platform surface (s.tenant → requires c.User(); org is the only tenancy key). The response is a `{ "<plural>": [...] }` object — the exact shape the console FE normalizers read (r.environments / r.pipelines / r.builds / r.releases).

deploy.go — the deploy lifecycle for /v1/platform: build (arcd BuildKit) + deploy (operator Service CR) + start/stop + deployment history/logs.

Two source kinds, ONE deploy mechanic (write the operator Service CR into tenant-<org>; the operator reconciles):

• source=image — no build. The CR is applied immediately with the requested image tag; the operator rolls it. This is the fully end-to-end path.
• source=git — a build is required. An in-cluster BuildKit Job is launched (client-go, the arcd model) to build the repo and push the per-tenant image; the deployment lands "building". The build watcher that flips "building"→"live" by applying the CR with the built image is phase 2 (paas-in-cloud.md §4) — until then the git path stops honestly at "building" with the real Job reference, never a fabricated "live".

Every handler is org-scoped (s.tenant) and every cluster write targets tenant-<org> derived from the validated org — never a request value.

domains.go — customer-self-serve domain management for /v1/platform apps: the default host, org-subtree hosts, and VERIFIED BYO custom domains (`yourco.com`), all rendered into the app's operator Service CR ingress so the operator materializes the Ingress + cert-manager TLS. Two host classes, one render source (the app's DomainsJSON):

• default / org-subtree host (`*.<org>.<sitesHost>`) — STRUCTURAL: the org owns its whole subtree by construction, so these are active the moment they are added; no ownership proof is possible or needed.
• BYO custom host (arbitrary `yourco.com`) — needs an OWNERSHIP proof before it can be rendered, or a tenant could claim a host it does not control (the RED hijack boundary). The customer publishes a per-claim TXT token at `_hanzo-challenge.<host>`; only someone who controls that zone's DNS can, so a matching token proves control (the DNS-01 model). Until verified, the claim is a pending row that is NEVER in the ingress. Global uniqueness (one org per host) is the `platform_domains.host` PRIMARY KEY.

Every handler is org-scoped through s.tenant and mutates only tenant-<org>.

k8s.go — the cluster-facing half of /v1/platform: the ONE deploy path.

A user application is deployed by writing an operator hanzo.ai/v1 `Service` CR into the caller's OWN tenant namespace; the Hanzo operator reconciles it into a Deployment + Service + Ingress (+ HPA/PDB) on DOKS. cloud never reimplements a deployer — it writes one CR, exactly like clients/paas patches system CRs, but here every object lives in `tenant-<org>` where the org is the gateway-minted, IAM-VALIDATED tenant (c.Org()), never a value from the request body or path. That derivation is the whole cross-tenant isolation boundary: a caller cannot name another org's namespace because the namespace is not an input.

Builds (git-source apps) launch an in-cluster BuildKit Job (the arcd model, buildkit-job.ts) via client-go — no GitHub builders. When the cluster / CI prerequisites are absent the subsystem fails CLOSED with the real reason (never status-theater), matching paas.

logs.go — REAL deployment logs for /v1/platform (the deploy.go phase-2 gap).

deploymentLogs previously returned only the recorded status timeline + a Job reference, ending with a "(live BuildKit Job logs stream in phase 2)" note. This closes that gap: it streams the ACTUAL pod logs from the cluster — the BuildKit Job's pod for a git build, and the running app's pod for a deployed app — via the typed CoreV1 client's Pods().GetLogs subresource. Everything stays operator- consistent and org-scoped: the app's pods are read from tenant-<org> (the same isolation namespace the Service CR lives in), the build pod from the central build namespace by the deterministic job-name label. It NEVER fabricates output — an unreachable cluster or an absent pod yields the honest recorded timeline instead, exactly as the rest of the subsystem degrades.

Package platform is the Hanzo Cloud PaaS control plane: the per-org, user-facing Platform-as-a-Service, mounted natively in the unified cloud binary at /v1/platform (HIP-0106). It is the Go port of the standalone Dokploy (platform.hanzo.ai) tRPC backend — the culmination of "one binary ships all of Hanzo Cloud."

Relationship to the sibling subsystems:

• clients/paas (/v1/paas) — the ADMIN fleet drift board: observes + deploys SYSTEM Service CRs across the platform namespaces, global-admin only. It answers "what is the fleet running, and roll a tag."
• clients/projects (/v1/projects) — per-org STATIC sites (S3 hosting).
• clients/platform (/v1/platform) — THIS: per-org CONTAINER apps. Users create projects + applications, build them (arcd BuildKit) and deploy them (operator hanzo.ai/v1 Service CR into their OWN tenant-<org> namespace).

All three share the ONE deploy mechanic — write an operator CR, let the operator reconcile — but /v1/platform is per-tenant: every route is scoped to the gateway-minted, IAM-VALIDATED X-Org-Id (c.Org()); the deploy namespace is DERIVED from that org (tenant-<org>), never taken from the request. A tenant can never read, build, or deploy into another org's namespace. That is the red-team bar and it is structural: cross-tenant identifiers are simply not inputs to any handler.

The API is designed-first in Goa (clients/platform/design; `goa gen` emits the OpenAPI 3 contract at clients/platform/design/gen/http/openapi3.*). The runtime handlers below implement that contract natively on zip so the binary keeps ONE router and stays behind the SanitizeIdentity trust boundary.

reconcile.go — the git build→deploy handoff (formerly deploy.go's "phase 2").

deployGit launches an in-cluster BuildKit Job and lands the deployment "building"; it does NOT block the HTTP request waiting for the build. This reconciler is the ONE owner of what happens next: it periodically scans every deployment still "building", checks its Job, and on success applies the operator Service CR with the built image — the SAME applyService the image-source path uses — flipping build→succeeded, deployment→deploying, app→live. The operator then reconciles the rollout.

Why a reconciler and not a per-deploy goroutine: state lives in the store, not in memory, so a cloud restart mid-build RESUMES cleanly (the next tick re-reads "building" rows). It is idempotent (applyService is create-or-update; a row is advanced off "building" once handled) and org-scoped (every write targets tenant-<row.Org>, derived from the row, never a request value).

secrets.go — KMS-sealed secret env vars for /v1/platform apps (closes the createApp/setEnv 501). A user env var flagged `secret:true` is NEVER stored in platform.db and NEVER rendered inline into the operator Service CR. Instead the ONE secret invariant holds end-to-end: a secret value lives ONLY in KMS and the operator-materialized k8s Secret; cloud's control-plane DB holds a masked placeholder and cloud never handles the plaintext at deploy time.

The path a secret takes:

1. SEAL — cloud seals the value into its embedded KMS (deps.KMS, AES-256-GCM envelope, clients/kms) at the ORG-SCOPED coordinate /orgs/<org>/platform/ <app>/<KEY> (kmsSecretRef). Plaintext is sealed before it touches disk, never logged, never echoed back over the API (toAppView masks it). If KMS is unavailable the write FAILS CLOSED — plaintext never lands in the DB.
2. PROVISION — on app-create/deploy, cloud ensures the tenant's PER-TENANT KMS credential exists (ensureTenantKMSAuth): a machine identity whose token carries owner=<org>, projected into tenant-<org> as the creds Secret the CR references. It is the ONE privileged step; when unavailable it degrades to an honest "pending" (never a shared reader), so no cross-tenant identity is ever created.
3. DECLARE — cloud writes a canonical KMSSecret CR (secrets.lux.network/ v1alpha1) into tenant-<org> pointing the operator at /v1/kms/orgs/<org>/ secrets/platform/<app> (projectSlug=<org>, explicit keys). The operator logs in with the per-tenant creds (/v1/kms/auth/login → IAM), reads each key back from cloud's KMS, and materializes the managed Secret `<app>-env`. Cloud's org-scope guard admits the read ONLY for owner==<org>, so a tenant can read ONLY its own scope. Best-effort: a missing CRD/RBAC/credential degrades to a "pending" status, never a failed deploy.
4. MOUNT — the Service CR renders each secret env as `valueFrom.secretKeyRef` → that Secret (optional, so the pod boots even before the sync lands); the hanzo operator mounts it into the Deployment env. The pod reads the secret from the k8s Secret — cloud is never in the plaintext path at runtime.

Everything is org-scoped: the KMS coordinate, the auth identity, the KMSSecret CR, and the managed Secret all live under the VALIDATED tenant, never a request value — the same cross-tenant boundary as the rest of /v1/platform, enforced at cloud's ONE auth boundary (SanitizeIdentity + the kms org-scope guard).

validate.go — the boundary validators + resource-bound policy for /v1/platform.

Three concerns, one home (DRY), because all three feed the SAME privileged cluster path (a BuildKit Job + operator Service CR in tenant-<org>):

1. build-input validation — repo.url / dockerfile / git-ref are the ONLY free-form strings that flow into the in-cluster build. They are validated here so they can never be misread as a separate buildctl argument, a shell token, a path escape, or a git-context fragment break. Combined with the exec-form argv in launchBuildJob (no `sh -c`), this closes OS command injection AND the `--output`/`--opt` override class (CRIT-1).
2. replica bounds — clampReplicas caps a tenant's requested replica count so a single app cannot request an unbounded Deployment (part of MED-3).
3. namespace resource bounds — a ResourceQuota + LimitRange are applied to every tenant namespace so a tenant's TOTAL footprint is capped in the cluster regardless of what slipped past the per-object clamp (defense in depth for MED-3). Concurrent build fan-out is capped in k8s.go using resourceLimits.maxConcurrentBuilds below.

Every bound is a hard-coded safe default, operator-overridable via env — the values are resolved ONCE at k8sClient construction so a request path never re-reads the environment and the tests are deterministic.