Configuration

Overview

Hyve’s configuration model is intentionally minimal. There are no embedded credential stores or cloud-provider config files. Everything lives in three places:

1. hyve.yaml at your repository root — reconciliation behaviour
2. hyve.lock at your repository root — locked module versions (auto-managed)
3. Your environment — credentials passed as module params or standard env vars

hyve.yaml

Place hyve.yaml at the root of your Hyve state repository to control reconciliation behaviour.

# hyve.yaml — placed at the root of your Hyve state repository
reconcile:
  mode: local                  # "local" (default) or "cicd"
  strictDelete: false          # set to true to warn about untracked cloud clusters
  strictResourceDelete: false  # set to true to auto-prune orphaned spec.resources entries

Field	Type	Default	Description
reconcile.mode	string	local	local — Hyve provisions clusters directly from the machine running hyve reconcile. cicd — Hyve validates and pushes desired state to Git; a CI/CD pipeline calls hyve reconcile --path . to provision.
reconcile.strictDelete	bool	false	When true, after each reconcile Hyve scans the cloud provider for clusters with no matching YAML in clusters/ and logs a warning naming each one — it does not delete anything automatically. See Provider Scan for what the scan can and can’t see.
reconcile.strictResourceDelete	bool	false	When true, a spec.resources entry removed from a cluster’s YAML without delete: true is pruned automatically instead of just logged as orphaned.

Note

If hyve.yaml is absent or a field is not set, Hyve uses the defaults shown above.

Caution

strictDelete and strictResourceDelete are not symmetric despite the similar name — strictResourceDelete auto-prunes; strictDelete only warns. A whole cluster is too large a blast radius to delete automatically off a provider scan that can itself have blind spots (see the linked section) — it surfaces the drift for a human to act on instead.

See the CI/CD Workflow Guide for a complete walkthrough of CI/CD mode with GitHub Actions.

env (optional)

Add an env block to point hyve at a local, gitignored file of environment variables — loaded before every reconcile and workflow run:

env:
  file: local.env   # relative to the repo root

Field	Default	Description
env.file	hyve.env	Path, relative to the repo root (or absolute), to a .env-style file loaded into the process environment before every command. Loaded from both the current directory and the active context’s directory, so it works wherever you run hyve.

Set it by editing hyve.yaml directly — there’s no CLI command for this anymore:

hyve.yaml

env:
  file: local.env

Tip

Add local.env (or whatever you name it) to .gitignore yourself — hyve doesn’t do this for you.

# local.env — never committed
CIVO_TOKEN=your-token
SOME_APP_SECRET=whatever

# clusters/my-cluster.yaml — reads from local.env, the real process
# environment, or CI secrets, in that order
spec:
  resources:
    - name: my-app
      source: ./resource-files/my-app.yaml
      values:
        token: ${SOME_APP_SECRET}

Note

Additive, not overriding: a variable already present in the real process environment (a CI secret, or something your shell already exported) always wins over env.file — the file only fills gaps. This is the same precedence hyve’s own bootstrap .env loading already uses, and matches workflow step env’s own inherited-environment-wins convention.

Note

A relative path resolves against the directory hyve.yaml lives in; an absolute path is used as-is. Keep the file out of git (add it to .gitignore) — it usually holds credentials.

See hyve.yaml above for every field.

hyve.lock

hyve.lock is a content-addressed YAML lock file at the root of your state repository. It is auto-managed by the hyve module and hyve workflow commands and should be committed to Git.

version: 1
modules:
  github.com/your-org/hyve-civo-module@v1.0.0:
    source: github.com/your-org/hyve-civo-module@v1.0.0
    resolved: https://github.com/your-org/hyve-civo-module/archive/v1.0.0.tar.gz
    sha256: "abc123..."
workflows:
  github.com/myorg/shared-workflows//setup-monitoring.yaml@v1.2.0:
    name: setup-monitoring
    source: github.com/myorg/shared-workflows//setup-monitoring.yaml@v1.2.0
    resolved: https://raw.githubusercontent.com/myorg/shared-workflows/v1.2.0/setup-monitoring.yaml
    sha256: "def456..."

The workflows key only appears once a template or cluster references a remote workflow — repositories using only local workflows in workflows/ don’t have it at all.

You should never edit hyve.lock directly. Use the module and workflow commands to manage it:

hyve module add github.com/your-org/hyve-civo-module@v1.0.0    # add and lock a module
hyve module update github.com/your-org/hyve-civo-module         # update a module to latest
hyve module install                                      # install all locked modules
hyve module list                                         # show locked modules

hyve workflow install                                    # lock all remote workflow refs
hyve workflow update github.com/myorg/shared-workflows//setup-monitoring.yaml
hyve workflow verify                                      # confirm cached content matches sha256

Credentials

Hyve does not store cloud credentials. Modules read credentials from:

1. Module params passed as --set KEY=VALUE when creating a template
2. Standard cloud CLI config files (~/.civo.json, ~/.aws/credentials, GCP ADC, az login session)
3. Environment variables (CIVO_TOKEN, AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.)

Passing credentials as params

When a module expects a credential (like a Civo API token), you can pass it directly as a template param. This value is stored in cluster.spec.params in the cluster YAML and injected as HYVE_PARAM_<KEY> on every reconcile.

hyve template create my-template \
  --driver github.com/your-org/hyve-civo-module \
  --driver-version v1.0.0 \
  --region PHX1 \
  --set api_key=${CIVO_TOKEN}

Caution

Params stored in cluster.spec.params are committed to Git in plaintext. For sensitive values like API tokens, prefer environment variables over --set so the value is never written to the YAML file.

Environment variables

Most modules support reading credentials directly from the environment, matching their underlying cloud CLI conventions:

# Civo
export CIVO_TOKEN=your-token

# AWS
export AWS_ACCESS_KEY_ID=your-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

# GCP
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Azure
export AZURE_TENANT_ID=your-tenant-id
export AZURE_CLIENT_ID=your-client-id
export AZURE_CLIENT_SECRET=your-client-secret

For CI/CD pipelines, store credentials as pipeline secrets (e.g., GitHub Actions secrets) and export them before running hyve reconcile.

Git Credentials

Hyve never clones or authenticates against git itself — if your context directory is git-backed, cloning and authenticating is your own git step, using whatever you’d normally use (SSH key, a credential helper, a token in the URL):

# SSH
eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa
git clone git@github.com:company/hyve-prod.git

# HTTPS with a token
git clone https://<token>@github.com/company/hyve-prod.git

hyve context create production --path ./hyve-prod

See Contexts and Version Control for the full picture.

Directory Structure

Your registered context directory lives wherever you put it — hyve never copies or clones it anywhere:

<your registered directory>/
├── clusters/       # Cluster YAML definitions
├── workflows/      # Workflow YAML definitions
├── templates/      # Template YAML definitions
├── hyve.yaml       # Reconciliation config (optional)
└── hyve.lock       # Module + remote workflow lock file (auto-managed)

Hyve’s own data — the context registry, cached secrets, cluster-mode sessions — lives separately, under $HYVE_HOME (default ~/.hyve):

~/.hyve/
├── hyve.db          # SQLite — registered contexts, cached secrets, sessions
└── kubeconfigs/     # Per-cluster kubeconfig cache written by `hyve cluster auth`

Configuration Priority

Hyve resolves values in this order:

Command-line flags

Highest priority — overrides all other sources

hyve cluster auth my-cluster

Environment variables

Second priority — from shell or CI/CD pipeline secrets

export CIVO_TOKEN=token

Cloud CLI credential stores

Third priority — ~/.civo.json, ~/.aws/credentials, GCP ADC, az login session

Default values

Lowest priority — built-in defaults from hyve.yaml or the module manifest

Security Best Practices

Use environment variables for secrets

Pass sensitive values like API tokens as environment variables rather than --set params. Environment variables are never written to Git.

export CIVO_TOKEN=your-token
# The module reads CIVO_TOKEN automatically — no --set needed
hyve template create my-template \
  --driver github.com/your-org/hyve-civo-module \
  --driver-version v1.0.0 \
  --region PHX1

Commit hyve.lock to Git

The hyve.lock file ensures reproducible module installs. Always commit it to your state repository:

git add hyve.lock
git commit -m "Lock module versions"

Use separate environments per stage

Keep production and development state in separate directories/repositories:

hyve context create production --path ~/repos/hyve-prod
hyve context create development --path ~/repos/hyve-dev

Never commit secrets

If you use .env files for local development, add them to .gitignore:

.gitignore

.env
.env.*
!.env.example

If you set env.file in hyve.yaml (see env (optional)), add that filename to .gitignore yourself too — hyve doesn’t do this automatically.

Related

Quick Start

Complete setup walkthrough

Module System

How modules work and how to add them

CI/CD Guide

Automate reconciliation in pipelines

Contexts

Registering directories and cluster targets