Skip to content
Hyve
Docs

'hyve cluster-config'

hyve cluster-config is the parent for hyve’s server-side components — the reconcile-loop controller and the HTTP API + auth layer. These are what deploy/helm/hyve actually runs inside its pods; you won’t run them by hand day-to-day. See Deploying Cluster Mode.

Commands

hyve cluster-config controller run

Starts the controller-runtime reconcile loop against ClusterDefinition/HyveConfig CRDs — the cluster-mode replacement for hyve reconcile running on a schedule.

Terminal window
hyve cluster-config controller run --namespace <ns> --config-name <name>
--namespace string default: hyve-system

Namespace to watch for ClusterDefinition/HyveConfig objects.

--config-name string default: hyve-config

Name of the singleton HyveConfig object within --namespace.

hyve cluster-config api run

Starts the HTTP API + auth layer — local login, role-gated ClusterDefinition/Template/Workflow/Resource CRUD, organization management, /proxy for the primary-cluster kubeconfig path.

Terminal window
hyve cluster-config api run --namespace <ns> --bind-address <addr> --db <sqlite|postgres> --db-dsn <dsn>
--namespace string default: hyve-system

The control plane’s own namespace — holds ClusterDefinitions and credentials Secrets, and doubles as the name of the control plane’s own organization.

--db string default: sqlite

Backend for hyve-api’s own organization/environment/access-binding datastore (internal/orgdb) — sqlite for a single-replica install, postgres once you’re running more than one API replica or using per-organization reconciling clusters at all (SQLite has no story for that kind of concurrent, cross-process access).

--db-dsn string

Data source name for --db — a file path for SQLite, a connection string for Postgres.

--home-cluster string

Which Kubernetes cluster this process itself has direct access to, if any — defaults to wherever it’s running. Pass none to run hyve-api with zero Kubernetes access of its own, relying entirely on organizations’ own reconciling clusters — useful for a plain Docker/container-platform deployment with no Kubernetes API server to reach at all.

--require-reconciling-cluster boolean default: false

Refuse to let any organization other than the control plane’s own ever land on (or migrate back to) the home cluster — see Multi-Tenancy.

hyve cluster-config api create-user

Bcrypt-hashes a password and writes the access grant directly to hyve-api’s own datastore (Postgres or SQLite, matching --db/--db-dsn to whatever that same install’s hyve-api process uses) — a real database write, not something kubectl apply -f - can create.

Terminal window
hyve cluster-config api create-user <username> --role admin --namespace <ns> [--password <pw>]
username string required

Local username.

--role string required

admin, read-only, superadmin, or custom. See Access Control.

--namespace string default: hyve-system

Namespace this binding is scoped to — the organization the user belongs to. Must match the target install’s own control-plane namespace for --role superadmin.

--env string

Environment within --namespace’s own organization, if it has more than one registered. Omit to default to that organization’s own environment when it has exactly one.

--password string

Omit to be prompted without echo — scripting/CI is the only real reason to pass it as a flag.

--db string default: sqlite

Backend for the datastore this binding is written to — must match the target install’s own --db.

--db-dsn string

Data source name for --db — must point at the same database the target install’s own hyve-api uses.

Terminal window
hyve cluster-config api create-user alice --role admin --namespace acme --db-dsn /data/orgdb.sqlite