Cluster Mode

Everything else in these docs describes local mode — hyve reconcile reading a directory on your own machine or CI runner. Hyve can also run as a deployed Kubernetes controller + API, for team or multi-tenant use, sharing the exact same reconcile engine and the exact same YAML. Nothing about how a cluster is defined changes between the two modes — only where the reconcile loop runs, and how you talk to it.

Local Mode

hyve reconcile on your machine or in CI. No prerequisites — this is how you bootstrap cluster #1, including a cluster that will later run hyve itself.

Cluster Mode

hyve deployed as a controller + API inside a Kubernetes cluster, reconciling continuously. The CLI becomes an HTTP client of that API once you hyve context login.

Two components, one Helm release

deploy/helm/hyve deploys two pieces together:

• The controller — a controller-runtime reconcile loop watching ClusterDefinition/HyveConfig CRDs, functionally the same job hyve reconcile does locally, just continuous instead of invoked.
• The API — a thin, authorized HTTP front door: local login, role-gated CRUD over ClusterDefinition/Template/Workflow/Resource, and a kubeconfig-minting endpoint. It’s a convenience layer, not a required gateway — plain kubectl against the CRDs always works too.

See Deploying Cluster Mode for the actual Helm chart walkthrough.

Everything is still real Kubernetes YAML

A ClusterDefinition is a real Custom Resource — the identical shape whether it’s a local file or a live object:

apiVersion: hyve.io/v1alpha1
kind: ClusterDefinition
metadata:
  name: production
  namespace: hyve-system
spec:
  region: us-central1
  driver:
    source: github.com/your-org/hyve-gke-module
    version: v1.2.0
  params:
    node_count: "3"

kubectl apply -f works on it unmodified once the CRDs are installed — cluster mode is not a different data model, just a different place for the reconcile loop and the CRUD surface to live.

Talking to it: hyve context login, not a different CLI

hyve context create prod-cluster --api-url https://hyve-api.example.com
hyve context login
hyve cluster list        # now an HTTP call, not a local file read

Note

The active context decides the mode: one with an API URL sends commands to that server, one without works on local files. Your login is a separate, machine-wide credential — switching contexts never logs you out. See Contexts & Environments.

Once logged in, every hyve cluster/template/workflow/resource command you already know works identically — same flags, same output shape — just talking to the API instead of local files. The same API also serves a web console at its root URL.

On the server, clusters belong to an organization and are grouped into environments (default, staging, …) selected with hyve environment use. Each organization’s resources reconcile on its own reconciling cluster or the install’s home cluster.

Access is real, not implied

Note

Cluster mode introduces genuinely new infrastructure, not just a network hop: identity (hyve context login, local username/password today), authorization (access bindings — admin/read-only/custom roles, resolved fresh on every request), and per-cluster spec.access options for how a managed cluster’s kubeconfig is minted (client-side module auth, server-side module auth, a stored tunnel kubeconfig, or hyve-agent proxying). See Access Control and Cluster Access.

Moving between modes

hyve migrate

Bootstrap a cluster from local files, or move the primary cluster itself

Deploying Cluster Mode

The Helm chart, values, and multi-tenant installs

Related

Contexts

Registering directories and cluster targets

hyve context login

Authentication and the session model

Access Control

Roles and access bindings

Cluster Access

How each cluster’s kubeconfig is minted