venue

Overview ¶

Package venue is bring your own cloud: link a DigitalOcean, AWS or GCP account and its clusters show up ready to run work.

It is the org-scoped "connect a cloud account" seam: an org links its native cloud-provider accounts, and Hanzo DISCOVERS the Kubernetes clusters in each account and FOLDS them into the ONE fleet (apps/fleet) — the same registry apps/visor surfaces at /v1/clusters and apps/ml federates workloads onto. There is no second cluster registry: discovery ends at fleet.Register, exactly where a hand-pasted BYO kubeconfig (visor.attachCluster) ends, so a discovered cluster appears in /v1/clusters and can run work like any managed or BYO cluster.

Surface (subsystem "venue", prefix /v1/cloud — NOT /api/):

GET    /v1/cloud                               provider cards (what each needs)      -> {providers:[...]}
GET    /v1/cloud/accounts                      this org's linked cloud accounts       -> {accounts:[...]}
POST   /v1/cloud/:provider/accounts            link a labeled account: verify→seal→   -> {account, clusters:[...]}
                                               discover→fold                          (201)
POST   /v1/cloud/:provider/accounts/:label/sync re-discover + re-fold that account     -> {account, clusters:[...]}
DELETE /v1/cloud/:provider/accounts/:label     unlink: detach folded clusters +       -> {unlinked:true}
                                               forget the sealed credential

MULTI-CREDENTIAL, PER ORG. An org may link MANY labeled accounts per provider (3 DO teams, 2 AWS accounts …). id = provider + label; the label is org-chosen (default "default"). Each credential is verified LIVE before anything is stored, sealed in the org's KMS namespace (/orgs/{org}/cloud/{provider}/{label}), and recorded in the org's account index (metadata only — the credential is never in the index, a response, or a log line). This is DISTINCT from the platform's own house DO key (apps/do, one DO_API_TOKEN for Hanzo's own VPCs/LBs): a venue account is the CUSTOMER's cloud account, org-scoped and isolated.

TENANT ISOLATION. org is principal.Org (the ZAP-propagated, gateway-validated owner) — never a client field. Every KMS path, index, and fleet.Register call is scoped by that org, so one org can neither see, sync, nor unlink another's accounts, and its discovered clusters fold only into its own fleet shard. The fold target project is recorded per account (the caller's X-Project-Id at link time) so sync/unlink act on the same fleet shard deterministically.

KEYLESS WHERE POSSIBLE. AWS uses cross-account role assumption (role ARN + external id via STS — no stored access keys); GCP prefers Workload Identity Federation (an external_account config, no service-account private key). Only DigitalOcean requires a stored secret (a PAT), sealed in KMS.