'hyve cluster'

The hyve cluster command group manages Kubernetes cluster definitions stored in your Git state repository, and provides access to cluster authentication.

Overview

Clusters are defined as YAML files in the clusters/ directory of your Git state repository. They specify a driver (module), region, params, and optional lifecycle workflows. The hyve cluster commands let you create, list, inspect, mark for deletion, and authenticate into clusters.

To create a cluster, use hyve cluster create <cluster-name> --template <template-name> — it generates the cluster YAML from the named template and triggers reconciliation.

Note

The old hyve cluster add and hyve cluster modify commands have been removed, and cluster creation moved from hyve template execute to hyve cluster create (a template is still required — pass it with --template). To change cluster params, edit the YAML directly or update the template and re-run hyve cluster create.

Commands

hyve cluster create

Create a cluster from a template. Generates the cluster YAML, commits it to Git, and runs reconciliation.

hyve cluster create <cluster-name> --template <template-name> [flags]

cluster-name string required

Name for the new cluster

--template string required

Name of the template to create the cluster from

--region string

Override the template’s default region for this cluster

--set string (repeatable)

Override or supply a param value for this specific cluster. Takes precedence over template defaults.

--set node_count=5 --set instance_type=t3.large

Examples:

# Create with template defaults
hyve cluster create prod-cluster-01 --template my-civo-template

# Override region and a param
hyve cluster create eu-cluster-01 --template my-civo-template \
  --region FRA1 \
  --set node_count=5

# Override multiple params
hyve cluster create staging-eks-01 --template prod-eks \
  --region us-west-2 \
  --set node_count=2 \
  --set instance_type=t3.small

Creation process:

1. Load the template YAML
2. Apply any --region and --set overrides
3. Compute spec.expiresAt if the template has a schedule
4. Generate the cluster YAML at clusters/<cluster-name>.yaml
5. Commit the cluster YAML to Git
6. Run reconciliation (create cluster via module, then run lifecycle workflows)

Output:

🚀 Creating cluster 'prod-cluster-01' from template 'my-civo-template'...

Driver: github.com/hyve-modules/civo@v1.0.0
Region: PHX1
Params: node_size=g4s.kube.medium, node_count=3

Cluster definition created: clusters/prod-cluster-01.yaml
Committed and pushed to Git.

Running reconciliation...
[create] Provisioning cluster 'prod-cluster-01'...
[status] Waiting for cluster to become active...
[status] Cluster is active.
[auth]   Updating kubeconfig...
[onCreate] Running workflow: setup-monitoring
[onCreate] setup-monitoring completed.

Cluster 'prod-cluster-01' is ready.
Run 'hyve cluster auth prod-cluster-01' to merge the kubeconfig.

---

hyve cluster list

List all cluster definitions in the current repository.

hyve cluster list

Output:

Clusters in repository 'production' (3):

  my-cluster
    Driver:  github.com/hyve-modules/civo@v1.0.0
    Region:  PHX1
    Status:  active

  staging-eks
    Driver:  github.com/hyve-modules/eks@v2.1.3
    Region:  us-east-1
    Status:  provisioning

  dev-gke
    Driver:  github.com/hyve-modules/gke@v1.2.0
    Region:  us-central1
    Status:  active

---

hyve cluster show

Show the full cluster definition YAML and a human-readable summary.

hyve cluster show <name>

name string required

Name of the cluster to show

Example:

hyve cluster show my-cluster

Output:

apiVersion: v1
kind: Cluster
metadata:
  name: my-cluster
  region: PHX1
spec:
  driver:
    source: github.com/hyve-modules/civo
    version: v1.0.0
  params:
    node_size: g4s.kube.medium
    node_count: "3"
  driverOutputs:
    HYVE_CLUSTER_ID: abc-123
    HYVE_CLUSTER_STATUS: active
  workflows:
    onCreate:
      - setup-monitoring
  delete: false
  pause: false

---

hyve cluster delete

Mark a cluster for deletion by setting spec.delete: true in the cluster YAML.

hyve cluster delete <name>

name string required

Name of the cluster to mark for deletion

Example:

hyve cluster delete my-cluster

This sets spec.delete: true in the cluster YAML, commits the change to Git, and (in local mode) immediately runs reconciliation. The reconciler will:

1. Run any onDelete lifecycle workflows
2. Call the module’s delete operation to deprovision the cluster
3. Run any afterDelete lifecycle workflows
4. Remove the cluster YAML from the repository

Output:

Marked cluster 'my-cluster' for deletion.
Committed: set spec.delete=true in clusters/my-cluster.yaml
Running reconciliation...
[onDelete] Running workflow: backup-data
[onDelete] backup-data completed successfully
Deleting cluster 'my-cluster' via github.com/hyve-modules/civo@v1.0.0...
Cluster 'my-cluster' deleted.
[afterDelete] Running workflow: cleanup-dns
[afterDelete] cleanup-dns completed successfully
Removed clusters/my-cluster.yaml from repository.

Note

Using spec.delete: true ensures lifecycle workflows (onDelete, afterDelete) run before the cluster is removed. Deleting the YAML file directly bypasses these hooks.

Caution

In CI/CD mode (reconcile.mode: cicd), setting spec.delete: true commits the change and exits. The actual deletion happens when your CI/CD pipeline runs hyve reconcile --path ..

---

hyve cluster auth

Run the module’s auth operation to merge the cluster’s kubeconfig into ~/.kube/config.

hyve cluster auth <name> [--method <method-name>]

name string required

Name of the cluster to authenticate into

--method string

Name of the auth method to use. When omitted, Hyve runs the first method defined in the module’s auth.yaml. Use this flag when a module declares multiple auth methods and you need a specific one.

Examples:

# Default — runs the first method in the module's auth.yaml
hyve cluster auth my-cluster

# Explicitly select a named method
hyve cluster auth my-cluster --method headless
hyve cluster auth my-cluster --method local

Output:

Running auth operation for 'my-cluster'...
Module: github.com/hyve-modules/civo@v1.0.0
Updated context 'my-cluster' in ~/.kube/config

After running this command, you can use kubectl with the merged context:

kubectl config use-context my-cluster
kubectl get nodes

Note

Auth is implemented by the module — specifically the auth.yaml file in the module directory. A module can declare multiple named auth methods (e.g. local for interactive flows, headless for non-interactive environments). See Modules for the auth.yaml schema.

Note

After every auth run, Hyve automatically removes duplicate cluster/context/user entries sharing the same name in ~/.kube/config, keeping only the one the module’s tool just wrote. This prevents the duplicate entries some tools leave behind when run repeatedly without their own merge flag (e.g. civo kubernetes config without --merge).

---

hyve cluster auth sync

Remove stale local kubeconfig entries for clusters that no longer exist in the repository — a bulk cleanup, in contrast to hyve cluster deauth which targets one cluster at a time.

hyve cluster auth sync [--dry-run]

--dry-run boolean default: false

Report which contexts would be removed without modifying ~/.kube/config.

How it works: loads every cluster definition from clusters/ in the current repository, reads the context names in ~/.kube/config, and removes any context (plus its associated cluster and user entries) whose name doesn’t match a known cluster.

Examples:

# Preview what would be removed
hyve cluster auth sync --dry-run

# Remove stale entries
hyve cluster auth sync

Output:

Removed stale context 'old-cluster'
Removed stale context 'decommissioned-eks'

No stale kubeconfig entries found

---

hyve cluster deauth

Remove a cluster’s context, cluster, and user entries from ~/.kube/config — the inverse of hyve cluster auth. Use this after a cluster has been deleted to keep your local kubeconfig tidy.

hyve cluster deauth <name>

name string required

Name of the cluster context to remove

Example:

hyve cluster deauth my-cluster

Output:

Removed cluster 'my-cluster' from /Users/username/.kube/config

If no kubeconfig file exists yet, this is a no-op:

No kubeconfig found at /Users/username/.kube/config

---

hyve cluster resources

Show the resources Hyve currently tracks for a cluster — read-only, no live cluster calls.

hyve cluster resources <name>

name string required

Name of the cluster to inspect

Example:

hyve cluster resources production

Output:

Declared (spec.resources):
  nginx-ingress  source=./resource-files/nginx-ingress.yaml namespace=ingress-nginx
  cert-manager  helm chart=cert-manager version=v1.14.0 namespace=cert-manager
  github-secrets  secret namespace=default keys=[PANGOLIN_ENDPOINT NEWT_ID NEWT_SECRET]

Tracked (spec.appliedResources):
  cert-manager  [helm]  appliedAt=2026-07-03T10:00:00Z  sha256=a1b2c3d4e5f6…  objects=6
  github-secrets  [manifest]  appliedAt=2026-07-03T09:59:01Z  sha256=7c6d5e4f3a2b…  objects=1
  nginx-ingress  [manifest]  appliedAt=2026-07-03T09:58:12Z  sha256=9f8e7d6c5b4a…  objects=2

Note

A Secret resource shows up as [manifest] in the tracked section, not [secret] — it’s cleaned up through the exact same tracked-object path a raw manifest resource uses, so the reconciler doesn’t distinguish them for deletion purposes. Cosmetic only.

Note

This reads spec.resources (from clusters/<name>.yaml) and spec.appliedResources (from its cluster-state/<name>.state.yaml sidecar) directly off disk — it does not run kubectl diff or contact the live cluster, so it works even offline. Use hyve reconcile --dry-run for a live drift preview. See Cluster Resources.

---

Cluster definition format

Clusters are stored as YAML files in clusters/<name>.yaml:

apiVersion: v1
kind: Cluster
metadata:
  name: my-cluster
  region: us-east-1
spec:
  driver:
    source: github.com/hyve-modules/eks
    version: v1.0.0
  params:
    vpc_id: vpc-0abc123456789
    eks_role_arn: arn:aws:iam::123456789012:role/eks-role
    node_role_arn: arn:aws:iam::123456789012:role/node-role
    instance_type: t3.medium
    node_count: "3"
  workflows:
    beforeCreate:
      - provision-network
    onCreate:
      - deploy-monitoring
    afterCreate:
      - create-app-secrets
    onDelete:
      - drain-workloads
    afterDelete:
      - cleanup-network
  resources:
    - name: nginx-ingress
      source: ./resource-files/nginx-ingress.yaml
      namespace: ingress-nginx
    - name: cert-manager
      helm:
        chart: cert-manager
        repo: https://charts.jetstack.io
        version: v1.14.0
        namespace: cert-manager
        values:
          installCRDs: "true"
    - name: github-secrets
      secret:
        namespace: default
        keys: [PANGOLIN_ENDPOINT, NEWT_ID, NEWT_SECRET]
  delete: false                 # set to true to mark for deletion
  pause: false                  # set to true to skip reconciliation
  expiresAt: ""                 # RFC 3339 auto-delete timestamp
  pendingWorkflows: []          # managed by reconciler
  workflowSchedules: []         # managed by reconciler

driverOutputs and appliedResources are deliberately not shown here — they’re reconciler-owned and live in a separate sidecar file, cluster-state/my-cluster.state.yaml, never inline in this one. See Reconciler state file.

# cluster-state/my-cluster.state.yaml — populated by reconciler, do not edit manually
driverOutputs:
  HYVE_EKS_CLUSTER_ENDPOINT: https://abc123.gr7.us-east-1.eks.amazonaws.com
  HYVE_LAST_PARAMS_HASH: abc123...
appliedResources: {}

Field reference

metadata.name string required

Unique cluster identifier. Used as the filename (clusters/<name>.yaml) and as HYVE_CLUSTER_NAME in module operations.

metadata.region string required

Cloud provider region. Passed to module operations as HYVE_CLUSTER_REGION.

spec.driver.source string required

Module source string. Examples: github.com/hyve-modules/civo, ./my-local-module

spec.driver.version string required

Module version. Must be locked in hyve.lock. Examples: v1.0.0, local

spec.params object

Module-specific key-value params. Each key is uppercased and injected as HYVE_PARAM_<KEY>. Refer to the module’s module.yaml for the list of accepted params.

spec.driverOutputs object

Populated by the reconciler after successful create/update operations. Do not edit manually. All keys are re-injected verbatim as environment variables on the next reconcile. Physically stored in cluster-state/<name>.state.yaml, not this file — see Reconciler state file.

spec.workflows.beforeCreate string[]

Workflows to run before the cluster is provisioned. No kubeconfig is available — the cluster does not exist yet. Use for provisioning cloud prerequisites (VPCs, IAM roles, etc.).

spec.workflows.onCreate string[]

Workflows to run after the cluster is created and ready, before spec.resources applies for this cycle. Kubeconfig is available (after auth is run).

spec.workflows.afterCreate string[]

Workflows to run after the cluster is created and ready, after spec.resources has applied for this cycle. Kubeconfig is available. Use this instead of onCreate when a workflow depends on something spec.resources creates — e.g. a Kubernetes Secret whose values can’t be committed to Git, but which a resource-managed Deployment already expects to exist.

spec.workflows.onDelete string[]

Workflows to run before the cluster is deleted. Cluster is still running; kubeconfig is available.

spec.workflows.afterDelete string[]

Workflows to run after the cluster is deleted. No kubeconfig available. Use for tearing down cloud prerequisites provisioned by beforeCreate workflows.

spec.workflows.preReconcile string[]

Workflows to run when the reconciler detects param drift on an already-ACTIVE cluster (i.e. spec.params changed since the last successful reconcile), immediately before the module’s scale operation. Not run on every reconcile cycle — only when param drift is detected. Kubeconfig is available.

spec.resources array

Kubernetes manifests, Helm releases, or Secrets rendered from Hyve’s own environment that Hyve should own, drift-check, and re-apply on every reconcile cycle for an ACTIVE cluster — unconditionally, not gated by param drift. See Cluster Resources for the full schema.

spec.appliedResources object

Populated by the reconciler after successfully applying a resource. Do not edit manually — mirrors driverOutputs at resource granularity, and lives alongside it in cluster-state/<name>.state.yaml, not this file. Use hyve cluster resources <name> to inspect it.

spec.delete boolean default: false

When true, the reconciler runs onDelete workflows, calls the module’s delete operation, runs afterDelete workflows, and removes the YAML file. Set this field (do not delete the file directly) to ensure lifecycle hooks run.

spec.pause boolean default: false

When true, the reconciler skips this cluster entirely. The cloud cluster continues running; Hyve does not compare or modify it until pause is set back to false.

spec.expiresAt string

RFC 3339 timestamp (e.g. "2026-09-01T00:00:00Z"). When the current time passes this value, the reconciler automatically treats the cluster as if spec.delete: true is set — running lifecycle hooks, deleting from the cloud, and removing the YAML file.

Reconciliation

After marking a cluster for deletion or editing a cluster’s params, run hyve reconcile to apply changes:

# Apply all pending changes
hyve reconcile

# CI/CD pipeline mode (use checked-out repo directly)
hyve reconcile --path .

# Preview without changing anything
hyve reconcile --dry-run

--dry-run boolean default: false

Makes the entire reconcile cycle read-only: cluster create/delete/scale, lifecycle workflows, and resource apply/delete are all skipped and logged as “would run” instead of executed. spec.resources drift is still resolved and diffed for real (both read-only operations) so it can be reported accurately — see Cluster Resources for the report format. Nothing is committed to Git in dry-run mode.

See the CI/CD guide for a full pipeline example.

Related Commands

• hyve module — Manage the modules that power cluster operations
• hyve template — Create cluster definitions from templates
• hyve workflow — Define and run lifecycle workflows
• hyve git — Manage Git repositories that store cluster definitions