Skip to content
Hyve
Docs

Quick Start

Overview

This guide walks you through creating your first Kubernetes cluster with Hyve using the module system. Hyve uses modules — versioned, self-contained packages — to provision clusters on any cloud provider.

Prerequisites

Cloud provider CLI

Hyve does not bundle cloud SDKs. Your credentials stay in your environment. Install the CLI for whichever provider you’re using:

  • Civo: Install the Civo CLI and authenticate with civo apikey save my-token <token> && civo apikey use my-token
  • AWS: Install the AWS CLI and run aws configure
  • GCP: Install the gcloud CLI and run gcloud auth application-default login
  • Azure: Install the Azure CLI and run az login
Git repository for state

Hyve stores all cluster definitions in a Git repository. You’ll need:

  • A Git repository (GitHub, GitLab, etc.) to store cluster state
  • The git binary installed and available in your PATH
Go 1.21+

Install Go 1.21 or higher to build and install Hyve.

Step 1 — Install Hyve

Install with Go

Terminal window
go install github.com/cbridges1/hyve@latest

This installs the hyve binary to your $GOPATH/bin. Ensure $(go env GOPATH)/bin is in your PATH.

Verify installation

Terminal window
hyve --help

Step 2 — Add a Git repository

Register a Git repository where Hyve will store your cluster YAML definitions:

Terminal window
hyve git add production --repo-url https://github.com/your-org/hyve-state.git

For private repositories, use SSH or set the HYVE_GIT_TOKEN environment variable:

Terminal window
export HYVE_GIT_TOKEN=ghp_xxxxxxxxxxxx
hyve git add production --repo-url https://github.com/your-org/hyve-state.git

Step 3 — Install a module

Modules implement cluster operations for a specific cloud provider. Install a module and lock it in hyve.lock:

Terminal window
hyve module add github.com/hyve-modules/civo@v1.0.0
Terminal window
hyve module add github.com/hyve-modules/eks@v1.0.0
Terminal window
hyve module add github.com/hyve-modules/gke@v1.0.0
Terminal window
hyve module add github.com/hyve-modules/aks@v1.0.0

Step 4 — Create a template

Templates define the shape of a cluster — driver, region, and module-specific params. Use --set KEY=VALUE to supply params:

Terminal window
hyve template create my-civo-template \
  --driver github.com/hyve-modules/civo \
  --driver-version v1.0.0 \
  --region PHX1 \
  --set node_size=g4s.kube.medium \
  --set node_count=3

Civo credentials are read automatically from the Civo CLI (~/.civo.json) or the CIVO_TOKEN environment variable.

Terminal window
hyve template create my-eks-template \
  --driver github.com/hyve-modules/eks \
  --driver-version v1.0.0 \
  --region us-east-1 \
  --set vpc_id=vpc-0abc123456789 \
  --set eks_role_arn=arn:aws:iam::123456789012:role/eks-role \
  --set node_role_arn=arn:aws:iam::123456789012:role/node-role \
  --set instance_type=t3.medium \
  --set node_count=3

AWS credentials are read from ~/.aws/credentials or environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).

Terminal window
hyve template create my-gke-template \
  --driver github.com/hyve-modules/gke \
  --driver-version v1.0.0 \
  --region us-central1 \
  --set project_id=my-gcp-project \
  --set machine_type=e2-standard-4 \
  --set node_count=3

GCP credentials are read from Application Default Credentials (gcloud auth application-default login).

Terminal window
hyve template create my-aks-template \
  --driver github.com/hyve-modules/aks \
  --driver-version v1.0.0 \
  --region eastus \
  --set subscription_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --set resource_group=my-rg \
  --set vm_size=Standard_DS2_v2 \
  --set node_count=3

Azure credentials are read from the Azure CLI session (az login) or service principal environment variables.

Step 5 — Create a cluster

Create a cluster from the template — this generates the cluster definition YAML and provisions the cluster:

Terminal window
hyve cluster create my-cluster --template my-civo-template

This writes clusters/my-cluster.yaml to your Git repository, commits it, and runs reconciliation to provision the cluster.

Step 6 — Authenticate (get kubeconfig)

Once the cluster is ready, run the module’s auth operation to merge the cluster into ~/.kube/config:

Terminal window
hyve cluster auth my-cluster

Then use the cluster:

Terminal window
kubectl config use-context my-cluster
kubectl get nodes

Step 7 — Reconcile

Going forward, any change to a cluster definition (committed to Git) is applied by running:

Terminal window
hyve reconcile

This reads all cluster YAMLs from Git, calls the appropriate module, and reconciles desired state with actual state.

Next Steps

Module System

Understand how modules work and how to write your own

Lifecycle Hooks

Attach workflows to cluster creation and deletion

Templates

Full template command reference

CI/CD Integration

Automate reconciliation in your pipeline

hyve-sample-repo

A complete, runnable example repository to clone and explore

Server Mode & Hyve Studio

Run hyve as an API server and drive it from a browser UI

Troubleshooting

Module not found after add

Run hyve module validate to confirm all template modules are locked and cached:

Terminal window
hyve module validate
Credentials not found

Modules read credentials from environment variables or the cloud CLI’s config files. Ensure the relevant CLI is authenticated before running Hyve:

Terminal window
# Civo
civo apikey list


# AWS
aws sts get-caller-identity


# GCP
gcloud auth application-default print-access-token


# Azure
az account show
No repository configured

You need to add a Git repository first:

Terminal window
hyve git add my-repo --repo-url https://github.com/user/repo.git
Git authentication fails

For private repositories, use SSH or set the token environment variable:

Terminal window
export HYVE_GIT_TOKEN=your_personal_access_token