Workflow Overview

What are Workflows?

Workflows are automated deployment pipelines defined as YAML files in Git repositories. They enable you to automate complex multi-step processes with built-in validation, secret management, and variable substitution.

Automation

Automate deployments, builds, and infrastructure tasks

Validation

Validate tools and secrets before execution

Variables

Dynamic configuration with environment variables

Composable

Chain workflows together for complex pipelines

Why Use Workflows?

Consistency

Every deployment follows the same process, reducing errors and ensuring reliability.

Repeatability

Run the same workflow multiple times with predictable results.

Version Control

Workflows are stored in Git, providing full audit trails and easy rollbacks.

Collaboration

Team members can review and improve workflows via pull requests.

Documentation

Workflows serve as executable documentation of your deployment process.

Basic Workflow

Here’s a simple workflow that deploys an application:

apiVersion: v1
kind: Workflow
metadata:
  name: deploy-app
  description: Deploy application to Kubernetes
spec:
  requirements:
    tools:
      - name: kubectl
        version: "1.28"
  env:
    APP_NAME: my-app
    NAMESPACE: default
  jobs:
    - name: deploy
      steps:
        - name: apply-manifests
          command: kubectl apply -f manifests/ -n ${NAMESPACE}
        - name: wait-rollout
          command: kubectl rollout status deployment/${APP_NAME} -n ${NAMESPACE}

Workflow Components

Metadata

Identifies the workflow:

metadata:
  name: deploy-app                      # Unique identifier
  description: Deploy app to Kubernetes # Human-readable description

Inputs

spec.inputs declares the environment variables a workflow requires at runtime. When assigned to a lifecycle hook (beforeCreate, onCreate, afterCreate, onDelete, afterDelete, preReconcile) these are injected automatically. When run ad-hoc via hyve workflow run, any missing inputs are prompted for in the TUI or must be provided via --set KEY=VALUE.

spec:
  inputs:
    - name: HYVE_CLUSTER_NAME
      description: "Cluster name (used to name cloud resources consistently)"
    - name: HYVE_CLUSTER_REGION
      description: "Cloud region to create resources in"
    - name: HYVE_CLUSTER_PROVIDER
      description: "Cloud provider (azure, aws, gcp, civo)"
      default: azure
    # Provider-specific account identifier — only the relevant one is set per cluster:
    #   HYVE_AWS_ACCOUNT, HYVE_GCP_PROJECT, HYVE_AZURE_SUBSCRIPTION, HYVE_CIVO_ORG
    - name: HYVE_AWS_ACCOUNT
      description: "AWS account alias (AWS clusters only)"

See Workflow Concepts — Workflow Inputs for full details.

Requirements

Validates prerequisites before execution:

requirements:
  tools:                    # Required CLI tools
    - name: kubectl
      version: "1.28"
  secrets:                  # Required secrets
    - name: DOCKER_TOKEN
      provider: docker

Environment Variables

Define variables for the workflow:

env:
  APP_NAME: my-app
  REGISTRY: docker.io/myuser
  VERSION: v1.0.0

Jobs

Define the work to be done:

jobs:
  - name: build              # Job name
    steps:                   # Steps to execute
      - name: docker-build
        command: docker build -t ${APP_NAME} .

Creating Workflows

Using Templates

Hyve can generate workflow templates:

# Create workflow from template
hyve workflow create --template deployment-pipeline

# This creates workflows/deployment-pipeline.yaml

Manual Creation

Create workflow files directly:

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

# Create workflow
cat > workflows/deploy-app.yaml <<EOF
apiVersion: v1
kind: Workflow
metadata:
  name: deploy-app
spec:
  requirements:
    tools:
      - name: kubectl
  jobs:
    - name: deploy
      steps:
        - name: apply
          command: kubectl apply -f manifests/
EOF

# Commit to Git
git add workflows/deploy-app.yaml
git commit -m "Add deployment workflow"

Running Workflows

Basic Execution

# Run workflow
hyve workflow run deploy-app

# Run with specific cluster
hyve workflow run deploy-app --cluster production

Execution Steps

Load Workflow

Hyve reads the workflow YAML from the repository

Validate Requirements

Checks that required tools and secrets are available

Set Environment

Loads environment variables and secrets

Execute Jobs

Runs each job in sequence

Report Results

Shows success or failure with detailed output

Workflow Structure

Jobs and Steps

Jobs contain steps that execute sequentially:

jobs:
  - name: build
    steps:
      - name: compile
        command: make build
      - name: test
        command: make test

  - name: deploy
    dependsOn: [build]
    steps:
      - name: deploy-app
        command: kubectl apply -f manifests/

Job Dependencies

Control execution order:

jobs:
  - name: test
    steps:
      - name: run-tests
        command: npm test

  - name: build
    dependsOn: [test]      # Runs after 'test' completes
    steps:
      - name: docker-build
        command: docker build .

  - name: deploy
    dependsOn: [build]     # Runs after 'build' completes
    steps:
      - name: kubectl-apply
        command: kubectl apply -f manifests/

Execution order: test → build → deploy

Commands vs Scripts

Single-line commands:

steps:
  - name: deploy
    command: kubectl apply -f manifests/

Multi-line scripts:

steps:
  - name: deploy
    script: |
      echo "Starting deployment..."
      kubectl apply -f manifests/
      kubectl rollout status deployment/my-app
      echo "Deployment complete!"

Common Workflow Patterns

Deployment Workflow

apiVersion: v1
kind: Workflow
metadata:
  name: deploy-application
spec:
  requirements:
    tools:
      - name: kubectl
        version: "1.28"
  env:
    APP_NAME: my-app
    NAMESPACE: production
  jobs:
    - name: deploy
      steps:
        - name: apply-config
          command: kubectl apply -f config/ -n ${NAMESPACE}
        - name: apply-deployment
          command: kubectl apply -f deployment.yaml -n ${NAMESPACE}
        - name: wait-ready
          command: kubectl rollout status deployment/${APP_NAME} -n ${NAMESPACE}
        - name: verify
          command: kubectl get pods -n ${NAMESPACE} -l app=${APP_NAME}

Build and Push Workflow

apiVersion: v1
kind: Workflow
metadata:
  name: build-push
spec:
  requirements:
    tools:
      - name: docker
    secrets:
      - name: DOCKER_TOKEN
        provider: docker
  env:
    IMAGE: myapp
    TAG: latest
    REGISTRY: docker.io/myuser
  jobs:
    - name: build-push
      steps:
        - name: login
          script: |
            echo "$DOCKER_TOKEN" | docker login -u myuser --password-stdin
        - name: build
          command: docker build -t ${REGISTRY}/${IMAGE}:${TAG} .
        - name: push
          command: docker push ${REGISTRY}/${IMAGE}:${TAG}

Multi-Stage Pipeline

apiVersion: v1
kind: Workflow
metadata:
  name: complete-pipeline
spec:
  requirements:
    tools:
      - name: docker
      - name: kubectl
  env:
    APP_NAME: my-app
    VERSION: v1.0.0

  jobs:
    - name: test
      steps:
        - name: unit-tests
          command: npm test

    - name: build
      dependsOn: [test]
      steps:
        - name: docker-build
          command: docker build -t ${APP_NAME}:${VERSION} .

    - name: deploy
      dependsOn: [build]
      steps:
        - name: kubectl-apply
          command: kubectl apply -f manifests/

    - name: verify
      dependsOn: [deploy]
      steps:
        - name: smoke-tests
          command: ./scripts/smoke-test.sh

Managing Workflows

List Workflows

# List all workflows in active repository
hyve workflow list

Output:

Workflows in repository 'production':
  - deploy-app
  - build-image
  - setup-monitoring
  - backup-database

View Workflow

# View workflow definition
cat ~/.hyve/repositories/production/workflows/deploy-app.yaml

Edit Workflow

# Edit workflow
vim ~/.hyve/repositories/production/workflows/deploy-app.yaml

# Commit changes
git commit -am "Update deployment workflow"

Delete Workflow

# Delete workflow
rm workflows/deploy-app.yaml
git commit -am "Remove deployment workflow"

Advanced Features

Environment Variable Substitution

Use shell variable syntax:

steps:
  - name: deploy
    command: echo "Deploying ${APP_NAME} version ${VERSION:-latest}"

Secret Management

Load secrets automatically:

requirements:
  secrets:
    - name: DOCKER_TOKEN
      provider: docker

jobs:
  - name: login
    steps:
      - name: docker-login
        script: echo "$DOCKER_TOKEN" | docker login -u myuser --password-stdin

Tool Validation

Ensure required tools are available:

requirements:
  tools:
    - name: kubectl
      version: "1.28"
      description: Kubernetes CLI
    - name: helm
      version: "3.12"
      description: Helm package manager

Best Practices

1. Name Things Clearly

Use descriptive names for workflows, jobs, and steps:

metadata:
  name: deploy-api-production
  description: Deploy API service to production cluster

jobs:
  - name: run-integration-tests
    steps:
      - name: test-api-endpoints
      - name: verify-database-connection

2. Validate Requirements

Always specify required tools and secrets:

requirements:
  tools:
    - name: kubectl
      version: "1.28"
  secrets:
    - name: DOCKER_TOKEN
      provider: docker
      required: true

3. Use Environment Variables

Avoid hardcoding values:

# Good
env:
  NAMESPACE: production
steps:
  - name: deploy
    command: kubectl apply -f manifests/ -n ${NAMESPACE}

# Bad
steps:
  - name: deploy
    command: kubectl apply -f manifests/ -n production

4. Add Verification Steps

Verify deployments succeed:

jobs:
  - name: deploy
    steps:
      - name: apply
        command: kubectl apply -f manifests/
      - name: wait-ready
        command: kubectl rollout status deployment/my-app
      - name: verify
        command: kubectl get pods -l app=my-app

5. Document Workflows

Add descriptions explaining purpose:

metadata:
  name: deploy-app
  description: |
    Deploy application to Kubernetes cluster
    - Runs tests first
    - Builds Docker image
    - Deploys to cluster with rolling update
    - Verifies deployment success

Error Handling

Workflows stop on first error:

jobs:
  - name: deploy
    steps:
      - name: test
        command: npm test        # If this fails, workflow stops

      - name: build
        command: docker build .  # This won't run if test fails

      - name: deploy
        command: kubectl apply . # This won't run if build fails

Workflow Examples

See the Workflow Examples page for complete real-world examples including:

Complete CI/CD pipelines
Multi-environment deployments
Infrastructure provisioning
Database migrations
Backup and restore operations

Troubleshooting

Workflow not found

Error: Workflow 'deploy-app' not found

Solution:

# Check workflow exists
hyve workflow list

# Verify file exists
ls -la ~/.hyve/repositories/production/workflows/

# Create workflow if missing
hyve workflow create --template deployment-pipeline

Requirements validation fails

Error: Required tool 'kubectl' not found

Solution:

# Install missing tool
# For kubectl:
brew install kubectl

# For helm:
brew install helm

# Verify installation
kubectl version --client

Secret not found

Error: Required secret 'DOCKER_TOKEN' not found

Solution:

# Set secret via environment variable
export DOCKER_TOKEN=your-token

Step fails

Error: Step 'deploy' failed with exit code 1

Solution:

# Run the command manually to debug
kubectl apply -f manifests/

# Check logs for details
# Fix the issue
# Re-run workflow
hyve workflow run deploy-app

Workflow Concepts

Learn workflow fundamentals

Requirements

Tool and secret validation

Variables

Variable substitution guide

Validation

Workflow validation

Examples

Real-world workflow examples

CLI Workflow

Workflow command reference

Workflow Overview

What are Workflows?

Why Use Workflows?

Basic Workflow

Workflow Components

Metadata

Inputs

Requirements

Environment Variables

Jobs

Creating Workflows

Using Templates

Manual Creation

Running Workflows

Basic Execution

Execution Steps

Workflow Structure

Jobs and Steps

Job Dependencies

Commands vs Scripts

Common Workflow Patterns

Deployment Workflow

Build and Push Workflow

Multi-Stage Pipeline

Managing Workflows

List Workflows

View Workflow

Edit Workflow

Delete Workflow

Advanced Features

Environment Variable Substitution

Secret Management

Tool Validation

Best Practices

Error Handling

Workflow Examples

Troubleshooting

Related