Template Concepts

Overview

Templates in Hyve are reusable cluster configurations that combine a driver/region/params with automated post-deployment workflows. They enable consistent cluster creation with standardized configurations and deployment processes.

Reusable Patterns

Define once, use multiple times

Workflow Integration

Automatic workflow execution after cluster creation

Consistency

Ensure all clusters follow the same pattern

Version Controlled

Plain YAML in your context directory — add git for full history, entirely optional

Template Structure

Templates are YAML files that define a driver, region, params, and optional lifecycle workflows:

apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: prod-template
  description: Production cluster template 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"
  schedule: "0 20 * * 5"   # optional: auto-expire clusters every Friday at 20:00
  workflows:
    onCreate:
      - setup-monitoring
      - deploy-base-apps
    onDelete:
      - backup-data

Metadata

metadata.name string required

Unique template identifier

metadata.description string

Human-readable description of the template

Spec

spec.driver.source string required

Module source string (e.g. github.com/your-org/hyve-civo-module)

spec.driver.version string required

Module version. Must be locked in hyve.lock.

spec.region string

Passed to the module as part of cluster context. Can be overridden at cluster-creation time with --region.

spec.mgmtCluster string

The cluster the driver module uses as its management cluster, copied onto every cluster created from the template.

spec.params object

Arbitrary key/value pairs, entirely module-specific — there’s no hyve-defined schema of provider fields. Check the module’s own module.yaml/README for what it expects. Injected as HYVE_PARAM_<KEY> env vars for every module operation; values can be overridden at cluster-creation time with --set.

spec.workflows.beforeCreate array

List of workflow names to execute before the cluster is created. No kubeconfig — the cluster does not exist yet. Output variables in HYVE_KEY=value format are captured and applied to the cluster definition.

spec.workflows.onCreate array

List of workflow names to execute after cluster creation, before spec.resources applies for this cycle. Kubeconfig is available.

spec.workflows.afterCreate array

List of workflow names to execute after cluster creation, after spec.resources has applied for this cycle. Kubeconfig is available. Use instead of onCreate when a workflow depends on something spec.resources creates.

spec.workflows.onDelete array

List of workflow names to execute before cluster deletion. Cluster is still running; kubeconfig is available.

spec.workflows.afterDelete array

List of workflow names to execute after the cluster has been deleted. No kubeconfig — the cluster no longer exists. Use to tear down infrastructure provisioned by beforeCreate.

spec.workflows.preReconcile array

List of workflow names to execute at the start of every reconcile loop for this cluster, before any create/update/delete decisions are made.

spec.resources array

Kubernetes manifests hyve owns, drift-checks, and re-applies — see Resources.

spec.lockParams string[]

Names of params whose values, once a cluster is created from this template, get hashed and recorded — not a permission lock. This is what hyve cluster adopt’s drift detection uses to tell “set intentionally at creation” apart from “looks like drift,” for exactly the params listed here.

spec:
  lockParams: [node_size, node_count]

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

hyve template create sets everything above through flags (--set, --schedule, --on-create, --mgmt-cluster, … — see hyve template). Resources have no flag; for those, edit the generated YAML afterward, or write the file directly:

cat > templates/prod-template.yaml <<EOF
apiVersion: hyve.io/v1alpha1
kind: Template
metadata:
  name: prod-template
  description: Production cluster with 3 large nodes
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-base-apps
    onDelete:
      - backup-data
EOF

If your context directory is git-backed (optional — see Version Control), commit it like any other file.

Executing Templates

hyve cluster create my-prod-cluster --template prod-template

Load template

Read the template YAML from the active context.

Generate + provision

Generate the cluster definition, then run reconciliation: beforeCreate → provision via the driver module → wait for ACTIVE.

Merge kubeconfig

Merge the new cluster’s kubeconfig into ~/.kube/config.

Run onCreate / afterCreate

Run onCreate workflows, apply spec.resources, then run afterCreate workflows.

onDelete/afterDelete run later, when the cluster is deleted.

Lifecycle Events

Event	When It Runs	Kubeconfig	Use Cases
beforeCreate	Before the cluster is provisioned	No	Provision VPC, IAM roles, DNS zones
onCreate	After cluster is ready, before spec.resources applies	Yes	Setup monitoring, deploy apps, configure ingress
afterCreate	After cluster is ready, after spec.resources has applied	Yes	Create a Secret a resource-managed Deployment references, DNS pointing at a now-deployed app
onDelete	Before cluster deletion	Yes	Backup data, drain workloads, notify teams
afterDelete	After the cluster is deleted	No	Tear down VPC, IAM roles, DNS zones

Note

Workflows referenced in a template must exist in the same context’s workflows/ directory (or as real Workflow objects, in cluster mode).

Managing Templates

hyve template list
hyve template show prod-template
hyve template delete old-template

Note

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

Use Cases

Rapid Environment Creation

hyve cluster create prod-cluster-01 --template prod-template
hyve cluster create prod-cluster-02 --template prod-template
# Both identical: same driver, region, params, and workflows

Multi-Region Deployment

hyve cluster create us-east-prod --template prod-template --region NYC1
hyve cluster create us-west-prod --template prod-template --region PHX1
hyve cluster create eu-prod --template prod-template --region FRA1

Testing Infrastructure Changes

hyve context use development
hyve cluster create test-new-config --template prod-template

# If successful
hyve context use production
hyve cluster create prod-new-cluster --template prod-template

Best Practices

Use descriptive names

# Good
metadata:
  name: production-ha-template
  description: Production HA cluster with monitoring and logging

# Avoid
metadata:
  name: template1

Include essential workflows

workflows:
  onCreate:
    - setup-monitoring
    - configure-security
    - setup-backup
    - deploy-core-services
  onDelete:
    - export-logs
    - backup-final-state

Test templates in development first

hyve context use development
hyve cluster create test-cluster --template new-template
# Verify workflows run successfully, then:
hyve context use production
hyve cluster create prod-cluster --template new-template

Version control templates (optional)

If your context directory is git-backed, commit template changes with descriptive messages — tags work fine too for marking a template version you want to be able to return to:

git commit -am "Update production template: add cert-manager to onCreate"
git tag -a prod-template-v1.1 -m "Add cert-manager"

Related

Template Management

The full command-by-command guide

CLI: Template Commands

Complete command reference

Modules

What a driver actually is

Workflows

Lifecycle hooks in depth