Template Concepts

Overview

Templates in Hyve are reusable cluster configurations that combine cluster definitions 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

Templates stored in Git with full history

Template Structure

Templates are YAML files that define cluster specifications and optional lifecycle workflows:

apiVersion: v1
kind: Template
metadata:
  name: prod-template
  description: Production cluster template with monitoring
spec:
  provider: civo
  region: NYC1
  nodes:
    - g4s.kube.large
    - g4s.kube.large
    - g4s.kube.large
  schedule: "0 20 * * 5"   # optional: auto-expire clusters every Friday at 20:00
  workflows:
    onCreate:
      - setup-monitoring
      - deploy-base-apps
    onDelete:
      - backup-data
      - cleanup-resources

Metadata

metadata.name string required

Unique template identifier

metadata.description string

Human-readable description of the template

Spec

spec.cluster object required

Cluster configuration (region, provider, nodes)

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 (e.g. a namespace or Deployment).

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.kubernetesVersion string

Kubernetes version to pin for clusters created from this template (e.g. "1.30"). Supported by AWS (EKS), GCP (GKE), and Azure (AKS).

spec.awsProfile string

Named AWS CLI profile for authentication. When set, Hyve uses ~/.aws/config profile credentials. AWS only.

spec.awsKmsKeyAlias string

AWS KMS key alias for EKS secrets encryption at rest (e.g. "alias/my-eks-key"). AWS only.

spec.awsClusterSgId string

Pre-existing EC2 cluster security group ID. Can be set by a beforeCreate workflow via HYVE_CLUSTER_SG_ID. AWS only.

spec.awsWorkerSgId string

Pre-existing EC2 worker node security group ID, applied via EC2 launch template. Can be set by a beforeCreate workflow via HYVE_WORKER_SG_ID. AWS only.

spec.lockParams boolean

When true, users cannot override default param values at cluster-creation time. The TUI skips the “Override default params?” prompt entirely, and any --set flags passed to hyve cluster create are silently ignored. Use this to enforce a fixed cluster shape — for example, a production template where node size and count must not be changed by the person spinning up the cluster.

spec:
  lockParams: true
  params:
    node_size: g4s.kube.large
    node_count: "3"

spec.schedule string

A 5-field cron expression (e.g. 0 20 * * 5). When a cluster is created from the template, the next scheduled occurrence is computed and set as spec.expiresAt on the generated cluster definition, causing it to be automatically deleted at that time. Useful for short-lived environments that should expire on a predictable schedule.

Creating Templates

Using CLI

# Create basic template
hyve template create prod-template \
  --region NYC1 \
  --nodes g4s.kube.large,g4s.kube.large,g4s.kube.large

# Create template with lifecycle workflows
hyve template create prod-template \
  --region NYC1 \
  --nodes g4s.kube.large,g4s.kube.large,g4s.kube.large \
  --on-create setup-monitoring,deploy-apps \
  --on-delete backup-data,cleanup

# Create a dev template that auto-expires clusters every Friday at 20:00
hyve template create dev-weekly \
  --region PHX1 \
  --nodes g4s.kube.small \
  --schedule "0 20 * * 5"

Manual YAML Creation

Create template file in repository:

# Navigate to repository
cd ~/.hyve/repositories/production

# Create template
cat > templates/prod-template.yaml <<EOF
apiVersion: v1
kind: Template
metadata:
  name: prod-template
  description: Production cluster with 3 large nodes
spec:
  cluster:
    region: NYC1
    provider: civo
    nodes:
      - g4s.kube.large
      - g4s.kube.large
      - g4s.kube.large
  workflows:
    onCreate:
      - setup-monitoring
      - deploy-base-apps
    onDelete:
      - backup-data
EOF

# Commit to Git
git add templates/prod-template.yaml
git commit -m "Add production cluster template"

Executing Templates

Execute a template to create a cluster:

# Execute template
hyve cluster create my-prod-cluster --template prod-template

# This will:
# 1. Create cluster 'my-prod-cluster' using template specs
# 2. Wait for cluster to be ready
# 3. Run 'onCreate' workflows (setup-monitoring, deploy-base-apps)
# Note: 'onDelete' workflows run before deletion, 'afterDelete' workflows run after

Execution Flow

Load Template

Read template YAML from repository

Create Cluster

Create cluster using template specifications

[INFO] Creating cluster 'my-prod-cluster' from template 'prod-template'
[INFO] Region: NYC1
[INFO] Nodes: 3x g4s.kube.large

Wait for Ready

Wait for cluster to become ready

[INFO] Waiting for cluster to be ready...
[INFO] Cluster is ready!

Execute onCreate Workflows

Run each onCreate workflow in sequence

[INFO] Running onCreate workflow 'setup-monitoring'
[INFO] Workflow 'setup-monitoring' completed
[INFO] Running onCreate workflow 'deploy-base-apps'
[INFO] Workflow 'deploy-base-apps' completed

Complete

Template execution finished

[INFO] Template 'prod-template' executed successfully
[INFO] Cluster 'my-prod-cluster' is ready

Template Types

Production Template

High-availability cluster with monitoring:

apiVersion: v1
kind: Template
metadata:
  name: production-template
  description: Production-ready cluster with HA and monitoring
spec:
  cluster:
    region: NYC1
    provider: civo
    nodes:
      - g4s.kube.large
      - g4s.kube.large
      - g4s.kube.large
  workflows:
    onCreate:
      - setup-monitoring
      - setup-logging
      - deploy-ingress-controller
      - setup-cert-manager
    onDelete:
      - backup-persistent-data
      - notify-team

Staging Template

Mid-sized cluster for testing:

apiVersion: v1
kind: Template
metadata:
  name: staging-template
  description: Staging environment cluster
spec:
  cluster:
    region: PHX1
    provider: civo
    nodes:
      - g4s.kube.medium
      - g4s.kube.medium
  workflows:
    onCreate:
      - setup-monitoring
      - deploy-test-apps

Development Template

Small cluster for development:

apiVersion: v1
kind: Template
metadata:
  name: dev-template
  description: Development cluster (single node)
spec:
  cluster:
    region: LON1
    provider: civo
    nodes:
      - g4s.kube.small
  workflows:
    onCreate:
      - setup-dev-tools

Specialized Template

Template for specific use cases:

apiVersion: v1
kind: Template
metadata:
  name: ml-cluster-template
  description: Machine learning cluster with GPU nodes
spec:
  cluster:
    region: NYC1
    provider: civo
    nodes:
      - g4s.kube.xlarge
      - g4s.kube.xlarge
      - g4s.kube.xlarge
  workflows:
    onCreate:
      - install-cuda-drivers
      - setup-jupyter
      - deploy-ml-platform
    onDelete:
      - export-model-artifacts

Workflow Integration

Templates support lifecycle workflows that run at different stages:

# Template with lifecycle workflows
spec:
  cluster:
    region: NYC1
    nodes:
      - g4s.kube.large
      - g4s.kube.large
  workflows:
    beforeCreate:          # Run before the cluster is provisioned (no kubeconfig)
      - provision-prereqs
    onCreate:              # Run after cluster is ready, before spec.resources applies (kubeconfig injected)
      - setup-monitoring
      - deploy-apps
      - configure-ingress
    afterCreate:            # Run after cluster is ready, after spec.resources applies (kubeconfig injected)
      - create-app-secrets
    onDelete:             # Run before cluster deletion (kubeconfig injected)
      - backup-data
      - cleanup-dns
    afterDelete:           # Run after the cluster is deleted (no kubeconfig)
      - teardown-prereqs

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

Workflow Requirements

Workflows referenced in templates must exist in the repository:

~/.hyve/repositories/production/
├── templates/
│   └── prod-template.yaml
└── workflows/
    ├── setup-monitoring.yaml
    ├── deploy-apps.yaml
    └── configure-ingress.yaml

Managing Templates

List Templates

# List all templates
hyve template list

Output:

Templates in repository 'production':
  - production-template (NYC1, 3 nodes)
  - staging-template (PHX1, 2 nodes)
  - dev-template (LON1, 1 node)

View Template

# View template details
cat ~/.hyve/repositories/production/templates/prod-template.yaml

Edit Template

# Edit template
vim ~/.hyve/repositories/production/templates/prod-template.yaml

# Commit changes
git commit -am "Update production template"

Delete Template

# Delete template
hyve template delete prod-template

# Or delete manually
rm templates/prod-template.yaml
git commit -am "Remove production template"

Use Cases

Rapid Environment Creation

Create identical environments quickly:

# Create production cluster
hyve cluster create prod-cluster-01 --template prod-template

# Create another production cluster
hyve cluster create prod-cluster-02 --template prod-template

# Both clusters identical: same size, region, and workflows

Standardization

Ensure all clusters follow organizational standards:

apiVersion: v1
kind: Template
metadata:
  name: company-standard
  description: Company standard cluster configuration
spec:
  cluster:
    region: NYC1
    nodes:
      - g4s.kube.large
      - g4s.kube.large
  workflows:
    onCreate:
      - install-security-policies
      - setup-monitoring
      - configure-networking
      - deploy-compliance-tools
    onDelete:
      - audit-log-export
      - compliance-notification

Multi-Region Deployment

Deploy to multiple regions with same configuration:

# US East
hyve cluster create us-east-prod --template prod-template
# Edit template to change region to NYC1

# US West
hyve cluster create us-west-prod --template prod-template
# Edit template to change region to PHX1

# EU
hyve cluster create eu-prod --template prod-template
# Edit template to change region to FRA1

Testing Infrastructure Changes

Test changes in development before production:

# Create test cluster from template
hyve git use development
hyve cluster create test-new-config --template prod-template

# If successful, use in production
hyve git use production
hyve cluster create prod-new-cluster --template prod-template

Best Practices

1. Use Descriptive Names

Name templates according to their purpose:

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

# Avoid
metadata:
  name: template1

2. Document Template Purpose

Add detailed descriptions:

metadata:
  name: ml-cluster
  description: |
    Machine learning cluster template
    - 3x xlarge nodes for compute
    - Pre-installed CUDA drivers
    - Jupyter notebook deployment
    - ML framework setup

3. Include Essential Workflows

Add lifecycle workflows for consistent configuration:

workflows:
  onCreate:
    - setup-monitoring        # Always monitor
    - configure-security      # Security baseline
    - setup-backup           # Disaster recovery
    - deploy-core-services   # Essential services
  onDelete:
    - export-logs            # Preserve audit trail
    - backup-final-state     # Final backup

4. Version Templates

Use Git tags for template versions:

# Create template version
git tag -a prod-template-v1.0 -m "Production template v1.0"
git push origin prod-template-v1.0

# Use specific version
git checkout prod-template-v1.0
hyve cluster create my-cluster --template prod-template

5. Test Templates

Always test templates in development first:

# Test in development
hyve git use development
hyve cluster create test-cluster --template new-template

# Verify workflows run successfully
# Then use in production
hyve git use production
hyve cluster create prod-cluster --template new-template

Template Inheritance

While Hyve doesn’t support template inheritance directly, you can create base templates and extend them:

# Base template
apiVersion: v1
kind: Template
metadata:
  name: base-cluster
spec:
  cluster:
    provider: civo
    nodes:
      - g4s.kube.medium
  workflows:
    onCreate:
      - setup-monitoring

# Production variant (copy and modify)
# templates/prod-cluster.yaml
apiVersion: v1
kind: Template
metadata:
  name: prod-cluster
spec:
  cluster:
    provider: civo
    region: NYC1
    nodes:
      - g4s.kube.large
      - g4s.kube.large
      - g4s.kube.large
  workflows:
    onCreate:
      - setup-monitoring
      - setup-logging
      - deploy-ingress
    onDelete:
      - backup-data

Complete Example

Production Template with Lifecycle Workflows

apiVersion: v1
kind: Template
metadata:
  name: production-complete
  description: |
    Complete production cluster template
    - HA configuration (3 large nodes)
    - Monitoring and logging
    - Security policies
    - Ingress controller
    - Cert manager
spec:
  cluster:
    region: NYC1
    provider: civo
    nodes:
      - g4s.kube.large
      - g4s.kube.large
      - g4s.kube.large
  workflows:
    onCreate:
      - setup-monitoring
      - setup-logging
      - install-security-policies
      - deploy-ingress-controller
      - setup-cert-manager
    onDelete:
      - backup-persistent-volumes
      - export-audit-logs
      - notify-operations-team

Workflows for Template

apiVersion: v1
kind: Workflow
metadata:
  name: setup-monitoring
spec:
  requirements:
    tools:
      - name: helm
        version: "3.12"
  jobs:
    - name: install-prometheus
      steps:
        - name: add-repo
          command: helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
        - name: install
          command: helm install prometheus prometheus-community/kube-prometheus-stack

# workflows/setup-logging.yaml
apiVersion: v1
kind: Workflow
metadata:
  name: setup-logging
spec:
  requirements:
    tools:
      - name: helm
  jobs:
    - name: install-loki
      steps:
        - name: add-repo
          command: helm repo add grafana https://grafana.github.io/helm-charts
        - name: install
          command: helm install loki grafana/loki-stack

Execute Template

# Create production cluster
hyve cluster create prod-app-01 --template production-complete

# Output:
# [INFO] Creating cluster 'prod-app-01' from template 'production-complete'
# [INFO] Cluster created successfully
# [INFO] Running onCreate workflow 'setup-monitoring'
# [INFO] Workflow 'setup-monitoring' completed
# [INFO] Running onCreate workflow 'setup-logging'
# [INFO] Workflow 'setup-logging' completed
# ...
# [INFO] Template execution completed successfully

# When cluster is deleted later:
hyve cluster delete prod-app-01

# Output:
# [INFO] Running onDelete workflow 'backup-persistent-volumes'
# [INFO] Workflow 'backup-persistent-volumes' completed
# [INFO] Running onDelete workflow 'export-audit-logs'
# [INFO] Workflow 'export-audit-logs' completed
# [INFO] Running onDelete workflow 'notify-operations-team'
# [INFO] Workflow 'notify-operations-team' completed
# [INFO] Cluster 'prod-app-01' deleted successfully

Workflows

Learn about workflows

Clusters

Cluster definitions

Template Management

Complete template guide

CLI Template

Template command reference

Template Concepts

Overview

Template Structure

Metadata

Spec

Creating Templates

Using CLI

Manual YAML Creation

Executing Templates

Execution Flow

Template Types

Production Template

Staging Template

Development Template

Specialized Template

Workflow Integration

Lifecycle Events

Workflow Requirements

Managing Templates

List Templates

View Template

Edit Template

Delete Template

Use Cases

Rapid Environment Creation

Standardization

Multi-Region Deployment

Testing Infrastructure Changes

Best Practices

Template Inheritance

Complete Example

Production Template with Lifecycle Workflows

Workflows for Template

Execute Template

Related