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.

Tip

Prefer to explore a working example first? hyve-sample-repo is a complete, runnable state repository — modules, templates, workflows, and a cluster already wired together, using a fully local fake module so it works offline with zero cloud credentials. Clone it and run hyve reconcile --path . to see the whole lifecycle run immediately.

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

A directory for cluster state

Hyve reads and writes cluster YAML in a plain local directory — no database, no built-in git. A git repository is optional, only if you want version history and review (see Contexts).

Go 1.26+

Install Go 1.26 or higher to build and install Hyve.

Step 1 — Install Hyve

Install with Go

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

hyve --help

Step 2 — Point hyve at a directory

Hyve has no built-in git functionality — it just reads and writes plain files in whatever directory you register. If you want it version-controlled, clone it yourself first (using your own git credentials, however you normally authenticate — SSH key, token, whatever your provider needs):

git clone https://github.com/your-org/hyve-state.git
hyve context create production --path ./hyve-state

Don’t want git at all? Skip the clone — hyve context create --path works against any plain local directory:

mkdir my-hyve-config && hyve context create production --path ./my-hyve-config

Either way, hyve context create registers it and makes it active immediately — every command below operates against it. See Contexts.

Step 3 — Install a module

Modules implement cluster operations for a cloud provider — Hyve itself has no idea which one, it just calls whatever module a template references. Install one and lock it in hyve.lock:

hyve module add github.com/your-org/hyve-civo-module@v1.0.0

Note

This guide uses a Civo module as the example — github.com/your-org/hyve-civo-module is a placeholder for whichever module you use. Swap in any other module and every command below works identically; see Writing a Module to build your own.

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:

hyve template create my-civo-template \
  --driver github.com/your-org/hyve-civo-module \
  --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 — every module reads whichever credentials its own provider CLI expects, in whatever way that provider normally works.

Step 5 — Create a cluster

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

hyve cluster create my-cluster --template my-civo-template

This writes clusters/my-cluster.yaml to your context directory and runs reconciliation to provision the cluster. If that directory is git-backed, committing the new file is your own step (optional — see Version Control).

Step 6 — Authenticate (get kubeconfig)

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

hyve cluster auth my-cluster

Then use the cluster:

kubectl config use-context my-cluster
kubectl get nodes

Step 7 — Reconcile

Going forward, any change to a cluster definition is applied by running:

hyve reconcile

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

Note

For CI/CD pipelines, set reconcile.mode: cicd in hyve.yaml at your repo root. Then your pipeline calls hyve reconcile --path . after each push to apply changes.

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

Contexts

Point hyve at a plain local directory, no git required

Troubleshooting

Module not found after add

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

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:

# Civo
civo apikey list

# AWS
aws sts get-caller-identity

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

# Azure
az account show

No context configured

You need to register one first:

hyve context create my-project --path ./my-hyve-config

Cloning a private repository fails

That’s your own git clone step, before hyve context create — authenticate with git however you normally do (SSH key, a credential helper, a token in the URL). Hyve itself never touches the clone or its credentials.