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
hyve template create prod-template \ --region NYC1 \ --nodes g4s.kube.large,g4s.kube.large,g4s.kube.large \ --on-create setup-monitoring,deploy-apphyve 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: v1kind: Templatemetadata: name: prod-template description: Production cluster with monitoringspec: 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-dataVPC and IAM roles already exist — set them directly in the template:
apiVersion: v1kind: Templatemetadata: name: aws-eks-template description: AWS EKS cluster with managed node groupsspec: 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-appVPC and IAM roles created by a beforeCreate workflow. List them in dynamicFields so the TUI skips the prompts:
apiVersion: v1kind: Templatemetadata: name: aws-eks-automated description: EKS cluster with workflow-provisioned VPC and IAM rolesspec: 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-prereqsTemplate Structure
Complete Template Example
apiVersion: v1kind: Templatemetadata: name: production-standard description: Standard production cluster with 3 large nodes, monitoring, and observability labels: environment: production tier: standardspec: 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-backupTemplate 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: engineeringSpec
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_NAMEExecuting Templates
Basic Execution
Execute a template to create a new cluster:
hyve cluster create prod-cluster-01 --template prod-templateThis command:
- Creates cluster definition from template
- Runs any
beforeCreateworkflows (before the cluster is provisioned) - Provisions cluster in cloud provider
- Waits for cluster to be ready
- Syncs kubeconfig
- Executes all
onCreateworkflows in order - Applies
spec.resources, if any - Executes all
afterCreateworkflows in order - Note:
onDeleteandafterDeleteworkflows 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 deletedTemplate Management
Listing Templates
hyve template listOutput:
📋 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
hyve template show production-standardOutput:
📋 Template: production-standard
apiVersion: v1kind: Templatemetadata: name: production-standard description: Standard production cluster with 3 large nodes, monitoring, and observabilityspec: 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-dataDeleting Templates
hyve template delete old-templateOutput:
✅ Template 'old-template' deleted successfullyValidating Templates
Run Validation
hyve template validate production-standardValidation 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: noneTemplate Examples
Development Template
Small, cost-effective cluster for development:
apiVersion: v1kind: Templatemetadata: name: dev-template description: Single-node development clusterspec: provider: civo region: PHX1 nodes: - g4s.kube.small clusterType: k3s ingress: enabled: true loadBalancer: falseUsage:
hyve cluster create dev-feature-auth --template dev-templatehyve cluster create dev-feature-payments --template dev-templateStaging Template
Production-like environment for testing:
apiVersion: v1kind: Templatemetadata: name: staging-template description: Staging environment matching productionspec: 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-dataUsage:
hyve cluster create staging-v2 --template staging-templateProduction Template
High-availability production cluster:
apiVersion: v1kind: Templatemetadata: name: production-template description: Production HA cluster with full observability labels: environment: production tier: high-availabilityspec: 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-teamUsage:
hyve cluster create prod-us-east-01 --template production-templatehyve cluster create prod-us-west-01 --template production-templateAWS EKS Template
EKS cluster using named node groups and aliases from your AWS provider config:
apiVersion: v1kind: Templatemetadata: name: aws-eks-template description: Standard AWS EKS cluster with managed node groupsspec: 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-appUsage:
hyve cluster create eks-prod-01 --template aws-eks-templateGCP GKE Template
GKE cluster with multiple node pools for system and workload separation:
apiVersion: v1kind: Templatemetadata: name: gcp-gke-template description: GCP GKE cluster with separate system and worker node poolsspec: 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-appUsage:
hyve cluster create gke-prod-01 --template gcp-gke-templateAzure AKS Template
AKS cluster with System and User node pools:
apiVersion: v1kind: Templatemetadata: name: azure-aks-template description: Azure AKS cluster with System and User agent pool profilesspec: 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-appUsage:
hyve cluster create aks-prod-01 --template azure-aks-templateEdge Computing Template
Lightweight cluster for edge deployments:
apiVersion: v1kind: Templatemetadata: name: edge-template description: Edge computing cluster optimized for IoT workloadsspec: provider: civo region: LON1 nodes: - g4s.kube.medium clusterType: k3s ingress: enabled: true loadBalancer: true workflows: onCreate: - edge-setup - deploy-iot-gatewayUsage:
hyve cluster create edge-london-01 --template edge-templatehyve cluster create edge-london-02 --template edge-templateMulti-Region Template
Template for each region:
# US East templateapiVersion: v1kind: Templatemetadata: name: us-east-template description: US East region clusterspec: provider: civo region: NYC1 nodes: - g4s.kube.large - g4s.kube.large clusterType: k3s workflows: onCreate: - deploy-regional-app---# EU templateapiVersion: v1kind: Templatemetadata: name: eu-template description: EU region clusterspec: provider: civo region: FRA1 nodes: - g4s.kube.large - g4s.kube.large clusterType: k3s workflows: onCreate: - deploy-regional-appUsage:
hyve cluster create prod-us-east-api --template us-east-templatehyve cluster create prod-eu-api --template eu-templateUse Cases
Rapid Environment Provisioning
Create template once
hyve template create feature-env \ --region PHX1 \ --nodes g4s.kube.small \ --on-create deploy-app,seed-dataSpin up environments on demand
# For each feature branchhyve cluster create feature-auth --template feature-envhyve cluster create feature-payments --template feature-envhyve cluster create feature-notifications --template feature-envCleanup when done
hyve cluster delete feature-authhyve cluster delete feature-paymentsStandardized Production Clusters
# Create standardized production clustershyve cluster create prod-api-01 --template production-templatehyve cluster create prod-api-02 --template production-templatehyve cluster create prod-web-01 --template production-templatehyve cluster create prod-worker-01 --template production-template
# All clusters have:# - Same node configuration# - Same monitoring setup# - Same security baseline# - Same backup configurationMulti-Tenant Deployments
# Create template for customer clustershyve 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 customerhyve cluster create customer-acme --template customer-templatehyve cluster create customer-globex --template customer-templatehyve cluster create customer-initech --template customer-templateTesting Different Configurations
# Create templates for testinghyve 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 comparehyve cluster create test-k3s-cluster --template test-k3shyve cluster create test-talos-cluster --template test-talosBest Practices
1. Name Templates by Purpose
# Good - clear purposehyve template create production-hahyve template create staging-standardhyve template create dev-smallhyve template create edge-iot
# Avoid - unclear naminghyve template create template1hyve template create testhyve template create cluster-tmpl2. 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-east3. 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 backupAutomate critical setup and teardown tasks
4. Create Templates per Environment
# Developmenthyve 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.large5. Version Control Templates
# Templates are stored in Git# Commit changes with descriptive messageshyve git push "Add production-ha template with 5-node configuration"hyve git push "Update staging template to include new monitoring workflow"
# Review template historycd ~/.hyve/repositories/production/templatesgit log production-standard.yaml6. Validate Before Execution
# Always validate firsthyve template validate my-template
# Then executehyve cluster create new-cluster --template my-template7. 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 metricsAdd comments to explain workflow purposes
Advanced Patterns
Template Inheritance Pattern
Create base templates and extend them:
# Base templatecat > base-template.yaml <<EOFapiVersion: v1kind: Templatemetadata: name: base-clusterspec: provider: civo clusterType: k3s ingress: enabled: true loadBalancer: true workflows: onCreate: - setup-monitoringEOF
# Small variantcat > small-cluster.yaml <<EOFapiVersion: v1kind: Templatemetadata: name: small-clusterspec: provider: civo region: PHX1 nodes: - g4s.kube.small clusterType: k3s ingress: enabled: true loadBalancer: true workflows: onCreate: - setup-monitoringEOF
# Large variantcat > large-cluster.yaml <<EOFapiVersion: v1kind: Templatemetadata: name: large-clusterspec: 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-backupEOFMulti-Stage Deployment
Deploy across multiple stages:
# Development stagehyve 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-templateBlue-Green with Templates
# Create green environmenthyve cluster create prod-green --template production-template
# Test green environmenthyve workflow run test-suite --cluster prod-green
# Switch traffic to green# (update load balancer/DNS)
# Delete blue environmenthyve cluster delete prod-blue
# Rename green to blue for next deploymenthyve cluster modify prod-green --name prod-blueTroubleshooting
Template Execution Fails
Problem: Template execution returns an error
Solutions:
# 1. Validate template firsthyve template validate my-template
# 2. Check API credentials (Civo)civo apikey list
# 3. Verify workflows existhyve workflow list
# 4. Check region availability# Use valid regions: PHX1, NYC1, FRA1, LON1
# 5. Review template YAMLhyve template show my-templateAWS 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:
hyve cluster create eks-prod-01 --template aws-template \ --vpc-id vpc-0abc123456789 \ --eks-role-name eks-cluster-role \ --node-role-name eks-node-roleAlternatively, 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:
# Cluster is created but workflows failed# You can re-run workflows manually
# 1. Authenticatehyve cluster auth my-cluster
# 2. Run workflows individuallyhyve workflow run setup-monitoring --cluster my-clusterhyve workflow run deploy-app --cluster my-cluster
# 3. Debug workflow issueshyve workflow validate setup-monitoringTemplate Not Found
Problem: Template doesn’t exist in repository
Solutions:
# List available templateshyve template list
# Check template directoryls ~/.hyve/repositories/production/templates/
# Sync from Githyve git pull
# Create template if missinghyve template create my-template --region PHX1 --nodes g4s.kube.mediumCluster Already Exists
Problem: Cluster name already in use
Solutions:
# Use a different cluster namehyve cluster create prod-cluster-02 --template prod-template
# Or delete existing cluster firsthyve cluster delete prod-cluster-01hyve cluster create prod-cluster-01 --template prod-templateInvalid 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