Kubeconfig Management

Overview

Hyve manages kubeconfig access through module auth operations. When you run hyve cluster auth, Hyve executes the module’s auth workflow (for example, civo kubernetes config --save for Civo clusters), which writes the cluster’s kubeconfig directly into ~/.kube/config. There is no separate encrypted store — auth goes straight to your standard kubeconfig. After the module’s script runs, Hyve automatically removes any duplicate cluster/context/user entries left behind under the same name, so running hyve cluster auth repeatedly never leaves stale duplicates — even for modules whose underlying CLI tool doesn’t merge cleanly on its own.

Getting Cluster Access

Authenticate with a Cluster

To add a cluster to ~/.kube/config and set it as the active context:

hyve cluster auth my-cluster

This runs the module’s auth operation for that cluster. For Civo clusters, for example, the auth op calls civo kubernetes config --save, which merges the cluster’s kubeconfig into ~/.kube/config and sets the current context.

Example workflow:

# After a cluster is provisioned, authenticate
hyve cluster auth prod-cluster
kubectl get nodes

# Switch to a different cluster
hyve cluster auth staging-cluster
kubectl get pods -A

Verify the Active Context

kubectl config current-context
kubectl config get-contexts

Removing a Cluster from ~/.kube/config

After a cluster is deleted, remove its context entry from ~/.kube/config:

hyve cluster deauth my-cluster

Output:

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

Sync Stale Entries in Bulk

hyve cluster deauth removes one cluster at a time and requires you to remember to run it. If your local kubeconfig has accumulated entries for clusters that were deleted (or removed from the repo) without a matching deauth, run:

hyve cluster auth sync

This diffs the context names in ~/.kube/config against the cluster definitions currently in the repository and removes any context — plus its cluster and user entries — that doesn’t match a known cluster. Preview what would be removed first with --dry-run:

hyve cluster auth sync --dry-run

Output:

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

Common Workflows

Provision and Connect

# 1. Create a cluster from a template
hyve cluster create my-cluster --template my-template

# 2. Wait for the cluster to become active
hyve cluster show my-cluster

# 3. Authenticate — runs module auth op, merges into ~/.kube/config
hyve cluster auth my-cluster

# 4. Verify
kubectl get nodes

Clean Up After Deletion

# Delete the cluster
hyve cluster delete my-cluster

# Remove the stale context from ~/.kube/config
hyve cluster deauth my-cluster

# Verify remaining contexts
kubectl config get-contexts

Multi-Cluster Access

Since hyve cluster auth sets the active context, run it for each cluster you want to switch between, then use kubectl config use-context to switch:

# Authenticate against each cluster once
hyve cluster auth prod-cluster
hyve cluster auth staging-cluster
hyve cluster auth dev-cluster

# Switch between them with kubectl
kubectl config use-context prod-cluster
kubectl get nodes

kubectl config use-context staging-cluster
kubectl get nodes

Per-Terminal Isolation

kubectl config use-context modifies the shared ~/.kube/config, so switching in one terminal affects all terminals. For true per-terminal isolation, use a separate KUBECONFIG environment variable pointing to a copied or exported kubeconfig file:

# Terminal 1 - Production (isolated)
export KUBECONFIG=~/.kube/config-prod
kubectl get pods -n production

# Terminal 2 - Staging (isolated)
export KUBECONFIG=~/.kube/config-staging
kubectl get pods -n staging

Troubleshooting

Auth fails or kubeconfig not updated

Problem: hyve cluster auth returns an error or ~/.kube/config is not updated.

Solutions:

# Verify the cluster is active
hyve cluster show my-cluster

# Check that the module's required CLI tool is installed and authenticated
# (e.g. for Civo: civo apikey list)

# Re-run auth
hyve cluster auth my-cluster

Wrong Cluster Context

Problem: kubectl commands run against the wrong cluster.

Solutions:

# Check current context
kubectl config current-context

# Switch to the correct cluster
hyve cluster auth correct-cluster

# Verify
kubectl get nodes
kubectl cluster-info

Stale Context After Cluster Deletion

Problem: ~/.kube/config still contains a context for a deleted cluster.

Solution:

hyve cluster deauth deleted-cluster
kubectl config get-contexts

To clean up all stale entries at once instead of one cluster at a time, run hyve cluster auth sync — see Sync Stale Entries in Bulk.

Duplicate entries for the same cluster

Problem: ~/.kube/config has more than one cluster/context/user entry with the same name after running hyve cluster auth repeatedly.

Solution: Hyve deduplicates automatically after every auth run, keeping the latest entry — just re-run auth:

hyve cluster auth my-cluster
kubectl config get-contexts

If duplicates persist, check that Hyve is on a version that includes automatic kubeconfig deduplication.

Cluster Management

Create and manage clusters

Workflow Management

Run workflows on clusters

Git Management

Repository management

CLI: Cluster Commands

Complete hyve cluster command reference, including auth/deauth