Cluster Access

hyve cluster auth <name> merges a kubeconfig for a cluster into ~/.kube/config. Where that kubeconfig comes from is set per cluster by spec.access on its ClusterDefinition:

spec.access	Where the kubeconfig comes from	Modes
(unset — the default)	The driver module’s auth.yaml, run on your machine with your own credentials	Local and cluster
method: module-auth	The driver module’s auth.yaml, run inside the hyve-api pod	Cluster
agent: {enabled: true, proxy: true}	hyve-api, relaying traffic over hyve-agent’s outbound connection	Cluster
method: primary, no driver	hyve-api mints a token for the host cluster itself (superadmin only)	Cluster

Default: client-side module auth

With spec.access unset, the module’s auth.yaml runs locally, the same way in both modes — in cluster mode the CLI just fetches the driver details from hyve-api (GET /api/clusters/<name>/auth-context) instead of reading them from a local file. Your own cloud CLI config and credentials mint the kubeconfig, so access is exactly what the provider grants you.

hyve cluster auth prod
hyve cluster auth prod --method headless   # pick a named method from auth.yaml

module-auth: server-side module auth

spec:
  access:
    method: module-auth

The module’s auth.yaml runs inside the hyve-api pod on every request, using the pod’s own credentials rather than yours. hyve injects the caller’s identity (HYVE_CALLER_USERNAME, HYVE_CALLER_ROLE) so the module can decide what to mint for whom.

Caution

Only use this with a module written to run server-side and enforce its own authorization from those variables — otherwise every caller gets whatever the pod’s credentials can mint.

hyve-agent

spec:
  access:
    agent:
      enabled: true   # install hyve-agent and report live connection status
      proxy: true     # also route kubectl traffic through it

hyve installs hyve-agent on the cluster once it’s active. The agent dials out to hyve-api — an SSH session carried over a WebSocket at wss://<hyve-api's public host>/agent/tunnel, the same HTTPS address the console and CLI use — so the cluster never needs an inbound, reachable endpoint, and hyve-api needs no extra port: anything that proxies HTTPS to it (an Ingress, a load balancer, a tunnel like Pangolin) carries the agent too. Each agent’s identity is issued for its cluster’s organization.

With proxy: true, hyve cluster auth returns a kubeconfig whose server is hyve-api’s /api/agent-proxy/org/<organization>/<cluster> path, carrying your hyve session; hyve-api relays each request through the agent with Kubernetes impersonation derived from your role in that organization. agent is independent of method — a cluster can use both.

A cluster’s agent state is reported separately from the cluster’s own status, so “the cluster isn’t ready” and “the agent hasn’t connected” never look alike — in the console’s badges, hyve cluster list/show, and the Agent column of kubectl get clusterdefinitions:

Agent state	Meaning
waiting	The cluster itself isn’t active yet — the agent is installed once it is
installing	Being installed, or installed but not connected yet
connected	Connected
disconnected	Was connected, isn’t now

Note

The agent-proxy kubeconfig authenticates with your hyve session token, so hyve-api must be reachable over HTTPS — client-go drops bearer tokens sent to a plain http:// server. Set the chart’s api.publicBaseURL to the HTTPS address callers reach it on.

primary: the host cluster

The cluster hyve itself runs on. With no spec.driver, hyve cluster auth gets a short-lived cluster-admin token minted by hyve-api, served through hyve-api’s /proxy path — superadmin only. The kubeconfig trusts whatever certificate hyve-api’s public address has (the chart’s api.publicCABundle for a private CA; the system trust store otherwise). With a real driver, it authenticates like any other cluster. See Multi-Tenancy — The host cluster.

Related

Kubeconfig Management

Working with the merged kubeconfigs

Modules

Writing a module’s auth.yaml

Access Control

Roles and bindings inside hyve itself

Cluster Patterns

Creating clusters and host clusters, locally and in pipelines