Template Management

Overview

Templates capture a cluster’s shape — which module drives it, its region, and its params — once, so you can stamp out consistent clusters by name instead of retyping the same flags every time.

Template Basics

What are Templates?

A template combines:

• A driver — the module (spec.driver.source/version) that implements create/delete/status/auth for a specific provider
• A region and params — the module-specific settings (node_size, instance_type, whatever the module’s module.yaml declares)
• Lifecycle workflows — beforeCreate/onCreate/afterCreate/onDelete/afterDelete, run automatically at each stage
• Optionally, a schedule — a cron expression that auto-expires every cluster created from this template

Creating Templates

hyve template create prod-template \
  --driver github.com/your-org/hyve-civo-module \
  --driver-version v1.0.0 \
  --region NYC1 \
  --set node_size=g4s.kube.large \
  --set node_count=3

Note

There’s no interactive “quick create” shortcut beyond flags — every param the module needs goes through --set KEY=VALUE, repeatable.

Or write the YAML directly:

templates/prod-template.yaml

apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: prod-template
  description: Production cluster with monitoring
spec:
  driver:
    source: github.com/your-org/hyve-civo-module
    version: v1.0.0
  region: NYC1
  params:
    node_size: g4s.kube.large
    node_count: "3"
  workflows:
    onCreate:
      - setup-monitoring
      - deploy-app
    onDelete:
      - backup-data

Template Structure

Complete Template Example

apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: production-standard
  description: Standard production cluster with 3 large nodes and observability
spec:
  driver:
    source: github.com/your-org/hyve-civo-module
    version: v1.0.0
  region: NYC1
  params:
    node_size: g4s.kube.large
    node_count: "3"
  workflows:
    onCreate:
      - setup-monitoring
      - configure-logging
      - deploy-observability
      - setup-backups
    onDelete:
      - export-logs
      - final-backup

Template Fields

metadata:
  name: my-template                 # Required
  description: What it creates      # Optional

spec:
  driver:                           # Required — which module drives this cluster
    source: github.com/your-org/hyve-civo-module
    version: v1.0.0

  runner:                           # Optional — cluster-mode Job image override
    image: ""                       #   falls back to HyveConfig.spec.defaultModuleImage if unset

  region: NYC1                      # Passed to the module as part of cluster context

  params:                           # Arbitrary key/value pairs, module-specific — injected
    node_size: g4s.kube.large       #   as HYVE_PARAM_<KEY> env vars for every module operation
    node_count: "3"

  workflows:                        # Optional — lifecycle hooks
    beforeCreate:                   #   Before provisioning (no kubeconfig yet)
      - provision-prereqs
    onCreate:                       #   After the cluster is ready, before spec.resources applies
      - setup-monitoring
      - deploy-app
    afterCreate:                    #   After spec.resources has applied
      - notify-team
    onDelete:                       #   Before deletion
      - backup-data
    afterDelete:                    #   After deletion (no kubeconfig)
      - teardown-prereqs
    preReconcile:                   #   Every reconcile cycle, before drift is resolved
      - refresh-secrets

  resources: []                     # Optional — Kubernetes manifests hyve owns and re-applies;
                                     #   see /docs/concepts/resources

  schedule: "0 20 * * 5"            # Optional — cron expression. A cluster created from this
                                     #   template gets spec.expiresAt set to the next occurrence
                                     #   (e.g. every Friday at 20:00), computed at creation time.

  lockParams: []                    # Optional — param names whose values are hashed and locked
                                     #   at creation time, so `hyve cluster adopt`'s drift
                                     #   detection knows they were intentional, not drift

Note

params is a flat string map — its keys are entirely up to the module. Check the module’s own module.yaml/README for which params it expects (e.g. node_size/node_count for a Civo module, instance_type/node_count for an EKS module) — there’s no fixed, hyve-defined schema of provider-specific fields.

Executing Templates

Basic Execution

hyve cluster create prod-cluster-01 --template prod-template

This command:

1. Loads the template, applies any --region/--set overrides
2. Computes spec.expiresAt if the template has a schedule
3. Generates the cluster YAML
4. Runs reconciliation: beforeCreate → provision → wait for ACTIVE → merge kubeconfig → onCreate → apply spec.resources → afterCreate

# Override region and a param for this specific cluster
hyve cluster create eu-cluster-01 --template prod-template \
  --region FRA1 \
  --set node_count=5

Output:

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

Driver: github.com/your-org/hyve-civo-module@v1.0.0
Region: NYC1
Params: node_size=g4s.kube.large, node_count=3

Cluster definition created: clusters/prod-cluster-01.yaml

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.

Template Management

Listing Templates

hyve template list

Showing Template Details

hyve template show production-standard

Prints the full template YAML.

Deleting Templates

hyve template delete old-template

Note

Deleting a template doesn’t touch clusters already created from it — a cluster’s YAML is a full, independent copy of what the template generated, not a live reference back to it.

Validating Templates

hyve template validate production-standard

Checks the template’s structure — required fields, that referenced workflows exist, that schedule (if set) is a valid cron expression. It does not validate the module’s own params against a schema (there isn’t one to check against) or reach out to the cloud provider.

Template Examples

Development — small, no schedule

apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: dev-template
  description: Small development cluster
spec:
  driver:
    source: github.com/your-org/hyve-civo-module
    version: v1.0.0
  region: PHX1
  params:
    node_size: g4s.kube.small
    node_count: "1"

Ephemeral — auto-expires

apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: feature-env
  description: Short-lived feature-branch cluster, auto-deleted weekly
spec:
  driver:
    source: github.com/your-org/hyve-civo-module
    version: v1.0.0
  region: PHX1
  params:
    node_size: g4s.kube.small
  schedule: "0 20 * * 5"   # every Friday at 20:00
  workflows:
    onCreate:
      - deploy-app
      - seed-data
    onDelete:
      - notify-team

AWS EKS — a different module, same shape

apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: aws-eks-template
  description: Production EKS cluster
spec:
  driver:
    source: github.com/your-org/hyve-eks-module
    version: v2.1.3
  region: us-east-1
  params:
    instance_type: t3.medium
    node_count: "3"
    vpc_id: vpc-0abc123456789
    eks_role_arn: arn:aws:iam::123456789012:role/eks-role
    node_role_arn: arn:aws:iam::123456789012:role/node-role
  workflows:
    onCreate:
      - deploy-app

Note

Every provider is the same template shape — only driver.source, region, and which params keys the module expects change. If a param (like a VPC ID) needs to come from a beforeCreate workflow instead of being hardcoded, have that workflow emit it as a HYVE_KEY=value output line and reference ${HYVE_KEY} in a downstream step or resource — see Workflow Variables.

Use Cases

Rapid Environment Provisioning

Create the template once

hyve template create feature-env \
  --driver github.com/your-org/hyve-civo-module --driver-version v1.0.0 \
  --region PHX1 --set node_size=g4s.kube.small

Spin up environments on demand

hyve cluster create feature-auth --template feature-env
hyve cluster create feature-payments --template feature-env

Clean up when done

hyve cluster delete feature-auth
hyve cluster delete feature-payments

Standardized Production Clusters

hyve cluster create prod-api-01 --template production-template
hyve cluster create prod-api-02 --template production-template
hyve cluster create prod-web-01 --template production-template
# Same driver, same params, same workflows — every time

Testing Different Drivers

hyve template create test-k3s --driver github.com/your-org/hyve-civo-module --driver-version v1.0.0 --region PHX1 --set node_size=g4s.kube.medium
hyve template create test-talos --driver github.com/your-org/hyve-civo-talos-module --driver-version v1.0.0 --region PHX1 --set node_size=g4s.kube.medium

hyve cluster create test-k3s-cluster --template test-k3s
hyve cluster create test-talos-cluster --template test-talos

Best Practices

Name templates by purpose

# Clear
hyve template create production-ha --driver ... --region ...
hyve template create staging-standard --driver ... --region ...

# Unclear — avoid
hyve template create template1 --driver ... --region ...

Write a description

metadata:
  name: production-standard
  description: Standard production cluster with HA, monitoring, and backups

Include essential workflows

spec:
  workflows:
    onCreate:
      - setup-monitoring
      - configure-logging
      - setup-backups
      - deploy-app
    onDelete:
      - export-logs
      - final-backup

One template per environment tier

hyve template create dev-template --driver ... --region PHX1 --set node_size=g4s.kube.small
hyve template create staging-template --driver ... --region PHX1 --set node_size=g4s.kube.medium
hyve template create prod-template --driver ... --region NYC1 --set node_size=g4s.kube.large

Version control templates

If your context directory is git-backed (optional — see Version Control), commit template changes with descriptive messages, same as any other file:

git commit -am "Add production-ha template with 5-node configuration"
git log templates/production-standard.yaml

Validate before creating a cluster from it

hyve template validate my-template
hyve cluster create new-cluster --template my-template

Troubleshooting

Cluster creation from a template fails

# 1. Validate the template first
hyve template validate my-template

# 2. Check the module's own credential requirements are met
#    (e.g. for Civo: civo apikey list)

# 3. Review the template
hyve template show my-template

Workflows fail after the cluster is created

The cluster still exists — re-run workflows manually once you’ve fixed the underlying issue:

hyve cluster auth my-cluster
hyve workflow run setup-monitoring --cluster my-cluster
hyve workflow validate setup-monitoring

Template not found

hyve template list
ls "$(hyve context path)/templates/"

# If git-backed, pull the latest first
git pull

# Create it if it's genuinely missing
hyve template create my-template \
  --driver github.com/your-org/hyve-civo-module --driver-version v1.0.0 \
  --region PHX1 --set node_size=g4s.kube.medium

Cluster name already exists

hyve cluster create prod-cluster-02 --template prod-template
# or
hyve cluster delete prod-cluster-01
hyve cluster create prod-cluster-01 --template prod-template

Related

Cluster Management

Learn about cluster operations

Workflow Management

Create workflows for templates

Contexts

Where templates actually live

CLI: Template Commands

Complete template command reference