Skip to content
Docs

Template Management

Overview

Templates in Hyve enable reusable cluster configurations with automated workflow execution. Create standardized cluster patterns once and deploy them consistently across environments.

Template Basics

What are Templates?

Templates combine:

  • Cluster specifications (provider, region, nodes or node groups)
  • Ingress configuration
  • Lifecycle workflows (onCreate runs after cluster creation, onDelete runs before deletion)
  • Node group definitions for multi-pool AWS EKS, GCP GKE, and Azure AKS clusters
  • Reusable patterns for consistent deployments

Creating Templates

Terminal window
hyve template create prod-template \
--region NYC1 \
--nodes g4s.kube.large,g4s.kube.large,g4s.kube.large \
--on-create setup-monitoring,deploy-app
Terminal window
hyve template create prod-template \
--description "Production cluster template" \
--provider civo \
--region NYC1 \
--nodes g4s.kube.large,g4s.kube.large,g4s.kube.large \
--cluster-type k3s \
--ingress \
--load-balancer \
--on-create setup-monitoring,deploy-app,configure-backups \
--on-delete backup-data,cleanup \
--schedule "0 20 * * 5"

Create ~/.hyve/repositories/<repo>/templates/my-template.yaml:

apiVersion: v1
kind: Template
metadata:
name: prod-template
description: Production cluster with monitoring
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.large
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- deploy-app
onDelete:
- backup-data

VPC and IAM roles already exist — set them directly in the template:

apiVersion: v1
kind: Template
metadata:
name: aws-eks-template
description: AWS EKS cluster with managed node groups
spec:
provider: aws
region: us-east-1
nodeGroups:
- name: workers
instanceType: t3.medium
count: 3
minCount: 1
maxCount: 5
clusterType: eks
awsAccount: main-account # alias from hyve config aws account add
awsVpcId: vpc-0abc123456789 # existing VPC ID
awsEksRoleName: k8srole # existing EKS cluster role name
awsNodeRoleName: k8snoderole # existing EKS node role name
ingress:
enabled: false
loadBalancer: false
workflows:
onCreate:
- deploy-app

VPC and IAM roles created by a beforeCreate workflow. List them in dynamicFields so the TUI skips the prompts:

apiVersion: v1
kind: Template
metadata:
name: aws-eks-automated
description: EKS cluster with workflow-provisioned VPC and IAM roles
spec:
provider: aws
region: us-east-1
nodeGroups:
- name: system
instanceType: t3.medium
count: 2
minCount: 1
maxCount: 4
clusterType: eks
awsAccount: main-account
dynamicFields:
- awsVpcId # set from HYVE_VPC_ID
- awsEksRoleName # set from HYVE_EKS_ROLE_NAME / HYVE_EKS_ROLE_ARN
- awsNodeRoleName # set from HYVE_NODE_ROLE_NAME / HYVE_NODE_ROLE_ARN
ingress:
enabled: false
loadBalancer: false
workflows:
beforeCreate:
- provision-eks-prereqs
onCreate:
- deploy-app
afterDelete:
- teardown-eks-prereqs

Template Structure

Complete Template Example

apiVersion: v1
kind: Template
metadata:
name: production-standard
description: Standard production cluster with 3 large nodes, monitoring, and observability
labels:
environment: production
tier: standard
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.large
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- configure-logging
- deploy-observability
- setup-backups
onDelete:
- export-logs
- final-backup

Template Fields

Metadata

metadata:
name: my-template # Required: Unique template name
description: What it creates # Optional: Human-readable description
labels: # Optional: Key-value labels
environment: production
cost-center: engineering

Spec

spec:
provider: civo # Required: Cloud provider (civo, aws, gcp, azure)
region: NYC1 # Required: Deployment region
nodes: # Optional: Simple node list (Civo single-pool clusters)
- g4s.kube.large
- g4s.kube.large
nodeGroups: # Optional: Named node pools (AWS EKS, GCP GKE, Azure AKS)
- name: workers # Pool name
instanceType: t3.medium # Node instance/machine type
count: 3 # Desired node count
minCount: 1 # Minimum nodes (enables autoscaling)
maxCount: 5 # Maximum nodes (enables autoscaling)
diskSize: 50 # Root disk size in GB (optional)
spot: false # Use spot/preemptible instances (optional)
mode: System # Azure only: System or User pool (optional)
labels: # Node labels (optional)
role: worker
taints: # Node taints (optional)
- key: dedicated
value: gpu
effect: NoSchedule
clusterType: k3s # Optional: k3s, talos, or eks (default: k3s)
ingress: # Optional: Ingress configuration
enabled: true
loadBalancer: true
workflows: # Optional: Lifecycle workflows
beforeCreate: # Run before the cluster is provisioned (no kubeconfig)
- provision-prereqs
onCreate: # Run after cluster is ready, before spec.resources applies (kubeconfig injected)
- workflow-name-1
- workflow-name-2
afterCreate: # Run after cluster is ready, after spec.resources applies (kubeconfig injected)
- workflow-name-3
onDelete: # Run before cluster deletion (kubeconfig injected)
- cleanup-workflow
afterDelete: # Run after the cluster is deleted (no kubeconfig)
- teardown-prereqs
schedule: "0 20 * * 5" # Optional: cron expression — auto-expire each cluster
# created from this template at the next occurrence
# (e.g. every Friday at 20:00). The next occurrence
# is computed at cluster-creation time and written to
# spec.expiresAt on the generated cluster.
# AWS-specific fields (only when provider: aws)
awsAccount: main-account # Account alias from hyve config aws account add
awsVpcId: vpc-0abc123456789 # VPC ID (set here or override at cluster-creation time)
awsEksRoleName: k8srole # EKS cluster role name
awsNodeRoleName: k8snoderole # EKS node role name
# dynamicFields — list fields to be populated by a beforeCreate workflow.
# The TUI skips the prompt for each listed field; the reconciler reads the
# value from the workflow's HYVE_* output variable after the workflow runs.
dynamicFields:
- awsVpcId # populated from HYVE_VPC_ID
- awsEksRoleName # populated from HYVE_EKS_ROLE_NAME / HYVE_EKS_ROLE_ARN
- awsNodeRoleName # populated from HYVE_NODE_ROLE_NAME / HYVE_NODE_ROLE_ARN
# Azure: azureResourceGroup — populated from HYVE_RESOURCE_GROUP_NAME

Executing Templates

Basic Execution

Execute a template to create a new cluster:

Terminal window
hyve cluster create prod-cluster-01 --template prod-template

This command:

  1. Creates cluster definition from template
  2. Runs any beforeCreate workflows (before the cluster is provisioned)
  3. Provisions cluster in cloud provider
  4. Waits for cluster to be ready
  5. Syncs kubeconfig
  6. Executes all onCreate workflows in order
  7. Applies spec.resources, if any
  8. Executes all afterCreate workflows in order
  9. Note: onDelete and afterDelete workflows run when the cluster is deleted

Execution Output

🚀 Executing template 'prod-template' to create cluster 'prod-cluster-01'...
📋 Template Details:
Provider: civo
Region: NYC1
Nodes: g4s.kube.large, g4s.kube.large, g4s.kube.large
Cluster Type: k3s
OnCreate Workflows: setup-monitoring, deploy-app
OnDestroy Workflows: backup-data
✅ Cluster definition created: /Users/user/.hyve/repositories/production/clusters/prod-cluster-01.yaml
1️⃣ Creating cluster...
✅ Cluster 'prod-cluster-01' created successfully (ID: abc123)
2️⃣ Waiting for cluster to be ready...
Polling cluster status (this may take several minutes)...
✅ Cluster 'prod-cluster-01' is ready
3️⃣ Authenticating...
✅ Merged 'prod-cluster-01' context into ~/.kube/config
4️⃣ Executing 2 onCreate workflow(s)...
[1/2] Running workflow: setup-monitoring
✅ Workflow 'setup-monitoring' completed successfully
[2/2] Running workflow: deploy-app
✅ Workflow 'deploy-app' completed successfully
✅ Template execution completed!
💡 Cluster 'prod-cluster-01' is now available
💡 Use 'hyve cluster auth prod-cluster-01' to (re-)configure kubeconfig access
💡 OnDestroy workflows will run when the cluster is deleted

Template Management

Listing Templates

Terminal window
hyve template list

Output:

📋 Available templates (4):
production-standard
Description: Standard production cluster with 3 large nodes
Region: NYC1 | Nodes: g4s.kube.large, g4s.kube.large, g4s.kube.large | Type: k3s
OnCreate Workflows: setup-monitoring, deploy-app, configure-backups
OnDestroy Workflows: backup-data
staging-template
Description: Staging environment cluster
Region: PHX1 | Nodes: g4s.kube.medium, g4s.kube.medium | Type: k3s
OnCreate Workflows: deploy-app
dev-template
Description: Development cluster template
Region: PHX1 | Nodes: g4s.kube.small | Type: k3s
edge-template
Description: Edge computing cluster
Region: LON1 | Nodes: g4s.kube.medium | Type: k3s
OnCreate Workflows: edge-setup
💡 Execute a template with:
hyve cluster create <cluster-name> --template <template-name>

Showing Template Details

Terminal window
hyve template show production-standard

Output:

📋 Template: production-standard
apiVersion: v1
kind: Template
metadata:
name: production-standard
description: Standard production cluster with 3 large nodes, monitoring, and observability
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.large
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- deploy-app
- configure-backups
onDelete:
- backup-data

Deleting Templates

Terminal window
hyve template delete old-template

Output:

✅ Template 'old-template' deleted successfully

Validating Templates

Run Validation

Terminal window
hyve template validate production-standard

Validation checks:

  • Required fields (apiVersion, kind, metadata, spec)
  • Valid provider name
  • Valid region for provider
  • Valid node sizes
  • Valid cluster type
  • Workflow existence

Validation Output

🔍 Validating template 'production-standard'...
✅ Template is valid
📋 Provider: civo
📋 Region: NYC1
📋 Nodes: 3 (g4s.kube.large, g4s.kube.large, g4s.kube.large)
📋 Cluster Type: k3s
📋 Ingress: true
📋 OnCreate Workflows: 2 (setup-monitoring, deploy-app)
📋 OnDestroy Workflows: 1 (backup-data)
✨ No warnings
🔍 Validating template 'broken-template'...
❌ Validation Failed
Errors:
• Missing spec.provider
• Missing spec.region
• Missing spec.nodes or spec.nodeGroups (at least one required)
• Invalid kind 'ClusterTemplate', expected 'Template'
🔍 Validating template 'my-template'...
⚠️ Warnings:
• Node size 'g4s.kube.custom' may not be valid for Civo
• OnCreate workflow 'deploy-app' not found in repository
• Unexpected apiVersion 'v2', expected 'v1'
✅ Template is valid
📋 Provider: civo
📋 Region: PHX1
📋 Nodes: 2 (g4s.kube.custom, g4s.kube.medium)
📋 Cluster Type: k3s
📋 Ingress: true
📋 OnCreate Workflows: 1 (deploy-app)
📋 OnDestroy Workflows: none

Template Examples

Development Template

Small, cost-effective cluster for development:

apiVersion: v1
kind: Template
metadata:
name: dev-template
description: Single-node development cluster
spec:
provider: civo
region: PHX1
nodes:
- g4s.kube.small
clusterType: k3s
ingress:
enabled: true
loadBalancer: false

Usage:

Terminal window
hyve cluster create dev-feature-auth --template dev-template
hyve cluster create dev-feature-payments --template dev-template

Staging Template

Production-like environment for testing:

apiVersion: v1
kind: Template
metadata:
name: staging-template
description: Staging environment matching production
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.medium
- g4s.kube.medium
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- deploy-app
- seed-test-data

Usage:

Terminal window
hyve cluster create staging-v2 --template staging-template

Production Template

High-availability production cluster:

apiVersion: v1
kind: Template
metadata:
name: production-template
description: Production HA cluster with full observability
labels:
environment: production
tier: high-availability
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.large
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- configure-logging
- deploy-observability
- setup-backups
- configure-alerting
- deploy-app
onDelete:
- export-logs
- final-backup
- notify-team

Usage:

Terminal window
hyve cluster create prod-us-east-01 --template production-template
hyve cluster create prod-us-west-01 --template production-template

AWS EKS Template

EKS cluster using named node groups and aliases from your AWS provider config:

apiVersion: v1
kind: Template
metadata:
name: aws-eks-template
description: Standard AWS EKS cluster with managed node groups
spec:
provider: aws
region: us-east-1
nodeGroups:
- name: system
instanceType: t3.medium
count: 2
minCount: 1
maxCount: 4
- name: workers
instanceType: t3.large
count: 3
minCount: 1
maxCount: 10
spot: true
labels:
role: worker
clusterType: eks
awsAccount: main-account # account alias from hyve config aws account add
awsVpcId: vpc-0abc123456789 # VPC ID (set in template or override at cluster-creation time)
awsEksRoleName: k8srole # EKS cluster role name
awsNodeRoleName: k8snoderole # EKS node role name
ingress:
enabled: false
loadBalancer: false
workflows:
onCreate:
- deploy-app

Usage:

Terminal window
hyve cluster create eks-prod-01 --template aws-eks-template

GCP GKE Template

GKE cluster with multiple node pools for system and workload separation:

apiVersion: v1
kind: Template
metadata:
name: gcp-gke-template
description: GCP GKE cluster with separate system and worker node pools
spec:
provider: gcp
region: us-central1
nodeGroups:
- name: system-pool
instanceType: e2-standard-2
count: 2
minCount: 1
maxCount: 3
- name: worker-pool
instanceType: e2-standard-4
count: 3
minCount: 1
maxCount: 10
labels:
role: worker
clusterType: gke
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- deploy-app

Usage:

Terminal window
hyve cluster create gke-prod-01 --template gcp-gke-template

Azure AKS Template

AKS cluster with System and User node pools:

apiVersion: v1
kind: Template
metadata:
name: azure-aks-template
description: Azure AKS cluster with System and User agent pool profiles
spec:
provider: azure
region: eastus
nodeGroups:
- name: systempool
instanceType: Standard_D2s_v3
count: 2
minCount: 1
maxCount: 3
mode: System
- name: workerpool
instanceType: Standard_D4s_v3
count: 3
minCount: 1
maxCount: 10
mode: User
labels:
role: worker
clusterType: aks
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- deploy-app

Usage:

Terminal window
hyve cluster create aks-prod-01 --template azure-aks-template

Edge Computing Template

Lightweight cluster for edge deployments:

apiVersion: v1
kind: Template
metadata:
name: edge-template
description: Edge computing cluster optimized for IoT workloads
spec:
provider: civo
region: LON1
nodes:
- g4s.kube.medium
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- edge-setup
- deploy-iot-gateway

Usage:

Terminal window
hyve cluster create edge-london-01 --template edge-template
hyve cluster create edge-london-02 --template edge-template

Multi-Region Template

Template for each region:

# US East template
apiVersion: v1
kind: Template
metadata:
name: us-east-template
description: US East region cluster
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
workflows:
onCreate:
- deploy-regional-app
---
# EU template
apiVersion: v1
kind: Template
metadata:
name: eu-template
description: EU region cluster
spec:
provider: civo
region: FRA1
nodes:
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
workflows:
onCreate:
- deploy-regional-app

Usage:

Terminal window
hyve cluster create prod-us-east-api --template us-east-template
hyve cluster create prod-eu-api --template eu-template

Use Cases

Rapid Environment Provisioning

Create template once

Terminal window
hyve template create feature-env \
--region PHX1 \
--nodes g4s.kube.small \
--on-create deploy-app,seed-data

Spin up environments on demand

Terminal window
# For each feature branch
hyve cluster create feature-auth --template feature-env
hyve cluster create feature-payments --template feature-env
hyve cluster create feature-notifications --template feature-env

Cleanup when done

Terminal window
hyve cluster delete feature-auth
hyve cluster delete feature-payments

Standardized Production Clusters

Terminal window
# Create 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
hyve cluster create prod-worker-01 --template production-template
# All clusters have:
# - Same node configuration
# - Same monitoring setup
# - Same security baseline
# - Same backup configuration

Multi-Tenant Deployments

Terminal window
# Create template for customer clusters
hyve template create customer-template \
--region NYC1 \
--nodes g4s.kube.medium,g4s.kube.medium \
--on-create setup-tenant,deploy-app,configure-isolation \
--on-delete cleanup-tenant-data
# Deploy for each customer
hyve cluster create customer-acme --template customer-template
hyve cluster create customer-globex --template customer-template
hyve cluster create customer-initech --template customer-template

Testing Different Configurations

Terminal window
# Create templates for testing
hyve template create test-k3s \
--cluster-type k3s \
--nodes g4s.kube.medium
hyve template create test-talos \
--cluster-type talos \
--nodes g4s.kube.medium
# Execute and compare
hyve cluster create test-k3s-cluster --template test-k3s
hyve cluster create test-talos-cluster --template test-talos

Best Practices

1. Name Templates by Purpose
Terminal window
# Good - clear purpose
hyve template create production-ha
hyve template create staging-standard
hyve template create dev-small
hyve template create edge-iot
# Avoid - unclear naming
hyve template create template1
hyve template create test
hyve template create cluster-tmpl
2. Use Descriptive Labels
metadata:
name: production-standard
description: Standard production cluster with HA, monitoring, and backups
labels:
environment: production
tier: standard
cost-center: engineering
region: us-east
3. Include Essential Workflows
spec:
workflows:
onCreate:
- setup-monitoring # Always monitor
- configure-logging # Always log
- setup-backups # Always backup
- deploy-app # Application-specific
onDelete:
- export-logs # Preserve audit trail
- final-backup # Last backup

Automate critical setup and teardown tasks

4. Create Templates per Environment
Terminal window
# Development
hyve template create dev-template --nodes g4s.kube.small
# Staging (production-like)
hyve template create staging-template --nodes g4s.kube.medium,g4s.kube.medium
# Production (HA)
hyve template create prod-template --nodes g4s.kube.large,g4s.kube.large,g4s.kube.large
5. Version Control Templates
Terminal window
# Templates are stored in Git
# Commit changes with descriptive messages
hyve git push "Add production-ha template with 5-node configuration"
hyve git push "Update staging template to include new monitoring workflow"
# Review template history
cd ~/.hyve/repositories/production/templates
git log production-standard.yaml
6. Validate Before Execution
Terminal window
# Always validate first
hyve template validate my-template
# Then execute
hyve cluster create new-cluster --template my-template
7. Document Workflows
spec:
workflows:
onCreate:
- setup-monitoring # Installs Prometheus + Grafana
- deploy-app # Deploys main application
- configure-backups # Sets up Velero for backups
- setup-alerting # Configures PagerDuty alerts
onDelete:
- export-metrics # Save final metrics

Add comments to explain workflow purposes

Advanced Patterns

Template Inheritance Pattern

Create base templates and extend them:

Terminal window
# Base template
cat > base-template.yaml <<EOF
apiVersion: v1
kind: Template
metadata:
name: base-cluster
spec:
provider: civo
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
EOF
# Small variant
cat > small-cluster.yaml <<EOF
apiVersion: v1
kind: Template
metadata:
name: small-cluster
spec:
provider: civo
region: PHX1
nodes:
- g4s.kube.small
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
EOF
# Large variant
cat > large-cluster.yaml <<EOF
apiVersion: v1
kind: Template
metadata:
name: large-cluster
spec:
provider: civo
region: NYC1
nodes:
- g4s.kube.large
- g4s.kube.large
- g4s.kube.large
clusterType: k3s
ingress:
enabled: true
loadBalancer: true
workflows:
onCreate:
- setup-monitoring
- setup-backups
- configure-alerting
onDelete:
- final-backup
EOF

Multi-Stage Deployment

Deploy across multiple stages:

Terminal window
# Development stage
hyve cluster create dev-app-v2 --template dev-template
# Staging stage (after dev testing)
hyve cluster create staging-app-v2 --template staging-template
# Production stage (after staging validation)
hyve cluster create prod-app-v2 --template prod-template

Blue-Green with Templates

Terminal window
# Create green environment
hyve cluster create prod-green --template production-template
# Test green environment
hyve workflow run test-suite --cluster prod-green
# Switch traffic to green
# (update load balancer/DNS)
# Delete blue environment
hyve cluster delete prod-blue
# Rename green to blue for next deployment
hyve cluster modify prod-green --name prod-blue

Troubleshooting

Template Execution Fails

Problem: Template execution returns an error

Solutions:

Terminal window
# 1. Validate template first
hyve template validate my-template
# 2. Check API credentials (Civo)
civo apikey list
# 3. Verify workflows exist
hyve workflow list
# 4. Check region availability
# Use valid regions: PHX1, NYC1, FRA1, LON1
# 5. Review template YAML
hyve template show my-template
AWS VPC or Role Not Set

Problem: hyve cluster create fails because awsVpcId or awsEksRoleName is empty.

Solution: Set the values in the template YAML directly or override at cluster-creation time:

Terminal window
hyve cluster create eks-prod-01 --template aws-template \
--vpc-id vpc-0abc123456789 \
--eks-role-name eks-cluster-role \
--node-role-name eks-node-role

Alternatively, use hyve tui to execute the template — the TUI offers live cloud lookup for VPCs and IAM roles.

Workflows Fail During Execution

Problem: Template creates cluster but workflows fail

Solutions:

Terminal window
# Cluster is created but workflows failed
# You can re-run workflows manually
# 1. Authenticate
hyve cluster auth my-cluster
# 2. Run workflows individually
hyve workflow run setup-monitoring --cluster my-cluster
hyve workflow run deploy-app --cluster my-cluster
# 3. Debug workflow issues
hyve workflow validate setup-monitoring
Template Not Found

Problem: Template doesn’t exist in repository

Solutions:

Terminal window
# List available templates
hyve template list
# Check template directory
ls ~/.hyve/repositories/production/templates/
# Sync from Git
hyve git pull
# Create template if missing
hyve template create my-template --region PHX1 --nodes g4s.kube.medium
Cluster Already Exists

Problem: Cluster name already in use

Solutions:

Terminal window
# Use a different cluster name
hyve cluster create prod-cluster-02 --template prod-template
# Or delete existing cluster first
hyve cluster delete prod-cluster-01
hyve cluster create prod-cluster-01 --template prod-template
Invalid Node Sizes

Problem: Template validation warns about node sizes

Solution:

# Use only valid Civo node sizes:
nodes:
- g4s.kube.xsmall # 1 vCPU, 1 GB RAM
- g4s.kube.small # 1 vCPU, 2 GB RAM
- g4s.kube.medium # 2 vCPU, 4 GB RAM
- g4s.kube.large # 4 vCPU, 8 GB RAM
- g4s.kube.xlarge # 6 vCPU, 16 GB RAM