Deploy Kubiya runners to Kubernetes via Helm

Deploy Kubiya runners to your Kubernetes cluster using our official Helm chart for scalable, production-ready automation.

Overview

Kubiya runners execute your workflows and agent tasks in secure, isolated environments. The Helm chart provides:

Automatic scaling based on workload demand
Security-first configuration with RBAC and network policies
Production-ready monitoring and logging
Easy upgrades and configuration management

Before You Start

Requirements:

Kubernetes cluster (v1.20+)
Helm 3.x installed
kubectl access to your cluster
Kubiya organization access

What You’ll Need:

Your Kubiya API key
Organization name
Desired runner configuration

Step 1: Access the Runners Dashboard

Navigate to your Kubernetes runners management interface:

Kubernetes Runners dashboard showing deployed runners with their health status

Go to Resources → Local Runners in your Kubiya organization
Click “Create Runner” to start the setup wizard
You’ll see all your existing runners with their status (Healthy/Unknown)

Step 2: Create a New Runner

Configure your Kubernetes runner through the creation wizard:

Basic Setup tab - Configure runner name, deployment target, and resource profile Basic Setup Configuration:

Runner Name: Enter a unique name (e.g., “dev-cluster”)
Deployment Target: Select “Kubernetes”
Resource Profile: Choose “Standard (Production)” for resource limits
Basic Options:
- ☐ Cluster-wide access - Grant permissions across all namespaces
- ☑ Persistent storage - Enable persistent volumes for state
- ☑ Monitoring & telemetry - Enable Azure Prometheus and Grafana

Step 3: Advanced Configuration

Switch to the Advanced Configuration tab for detailed settings:

Advanced Configuration tab - Detailed component and security settings Advanced Configuration Options: Runner Configuration:

Runner Name: Confirm your runner name
Deployment Target: Kubernetes (confirmed)
Resource Profile: Standard for production workloads

Security & RBAC:

☐ Cluster-wide access - Allow access to all namespaces
☑ Network policies - Enable namespace isolation
☑ Run as non-root - Enhanced security context

Storage Configuration:

☑ Persistent storage - Enable PVCs for state
Storage Class: default (or specify your preferred class)

Components:

☑ Workflow Engine - Execute workflow automations
☑ Dagger Runtime - Container-based tool execution
☐ Image Updater - Automatic component updates (optional)

Monitoring & Telemetry:

☑ Azure Prometheus - Metrics collection and dashboards
☑ OpenTelemetry tracing - Distributed tracing support

Click “Create Runner” to generate your runner configuration and token

Step 4: Add the Kubiya Helm Repository

# Add the Kubiya Helm repository
helm repo add kubiya https://kubiyabot.github.io/helm-charts

# Update your local chart repository cache
helm repo update

Step 5: Install the Runner

Quick Installation

# Install with basic configuration
helm install my-kubiya-runner kubiya/kubiya-runner \
  --set config.apiKey="your-api-key-here" \
  --set config.organization="your-org-name" \
  --set config.runnerToken="your-runner-token"

Production Installation

Create a values.yaml file for production configuration:

# values.yaml
config:
  apiKey: "your-api-key-here"
  organization: "your-org-name"
  runnerToken: "your-runner-token"
  environment: "production"

# Resource configuration
resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 500m
    memory: 1Gi

# Autoscaling
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

# Security
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 2000

# Networking
service:
  type: ClusterIP
  port: 8080

# Monitoring
monitoring:
  enabled: true
  serviceMonitor:
    enabled: true

Install with the production configuration:

# Install with custom values
helm install my-kubiya-runner kubiya/kubiya-runner \
  --values values.yaml \
  --namespace kubiya \
  --create-namespace

Step 6: Verify Installation

Check that your runner is deployed and healthy:

# Check pod status
kubectl get pods -n kubiya

# View runner logs
kubectl logs -f deployment/my-kubiya-runner -n kubiya

# Check runner service
kubectl get services -n kubiya

Once deployed, your runner will appear in the Kubernetes Runners dashboard with a “Healthy” status, and you can monitor its components (Runner, Tools, Agents) as shown in the dashboard screenshot above.

Configuration Options

Environment Variables

config:
  # Required
  apiKey: "your-api-key"
  organization: "your-org"
  runnerToken: "your-runner-token"
  
  # Optional
  environment: "production"
  logLevel: "INFO"
  maxConcurrentJobs: 10
  jobTimeout: "30m"

Resource Management

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
    ephemeral-storage: 10Gi
  requests:
    cpu: 500m
    memory: 1Gi
    ephemeral-storage: 5Gi

Security Configuration

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 2000
  capabilities:
    drop:
    - ALL

podSecurityContext:
  seccompProfile:
    type: RuntimeDefault

Networking

networking:
  # Network policies
  networkPolicy:
    enabled: true
    ingress:
      enabled: true
      from: []
    egress:
      enabled: true
      to: []

  # Service configuration
  service:
    type: ClusterIP
    port: 8080
    annotations: {}

Advanced Configuration

Multiple Runner Types

Deploy different runner configurations for different environments:

# Development runner
helm install dev-runner kubiya/kubiya-runner \
  --values values-dev.yaml \
  --namespace kubiya-dev

# Production runner  
helm install prod-runner kubiya/kubiya-runner \
  --values values-prod.yaml \
  --namespace kubiya-prod

High Availability Setup

# values-ha.yaml
replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20

podDisruptionBudget:
  enabled: true
  minAvailable: 2

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          app.kubernetes.io/name: kubiya-runner
      topologyKey: kubernetes.io/hostname

Persistent Storage

persistence:
  enabled: true
  storageClass: "fast-ssd"
  size: 50Gi
  mountPath: "/data"

Monitoring and Logging

Prometheus Integration

monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s
    scrapeTimeout: 10s
    labels:
      app: kubiya-runner

Log Aggregation

logging:
  enabled: true
  format: "json"
  level: "info"
  
  # Forward logs to external system
  fluent-bit:
    enabled: true
    output: "elasticsearch"
    host: "elasticsearch.logging.svc.cluster.local"

Upgrading

Update Runner Configuration

# Update with new values
helm upgrade my-kubiya-runner kubiya/kubiya-runner \
  --values values.yaml \
  --namespace kubiya

# Check upgrade status
helm status my-kubiya-runner -n kubiya

Version Management

# List available versions
helm search repo kubiya/kubiya-runner --versions

# Upgrade to specific version
helm upgrade my-kubiya-runner kubiya/kubiya-runner \
  --version 1.2.3 \
  --namespace kubiya

Troubleshooting

Common Issues

Runner Not Connecting:

# Check runner logs
kubectl logs deployment/my-kubiya-runner -n kubiya

# Verify API key and token
kubectl get secret my-kubiya-runner-config -n kubiya -o yaml

Resource Constraints:

# Check resource usage
kubectl top pods -n kubiya

# View resource limits
kubectl describe pod <runner-pod-name> -n kubiya

Network Issues:

# Test connectivity
kubectl exec -it <runner-pod-name> -n kubiya -- wget -O- https://api.kubiya.ai/health

# Check network policies
kubectl get networkpolicies -n kubiya

Complete Helm Chart Reference

For the complete list of configuration options, values, and advanced features, see the full chart documentation on Artifact Hub: 📚 Kubiya Runner Helm Chart - Artifact Hub The Artifact Hub documentation includes:

Complete values.yaml reference
All configuration options
Security best practices
Monitoring and alerting setup
Advanced deployment patterns
Troubleshooting guides

Next Steps

Configure Agents to use your new runner
Create Workflows that leverage runner capabilities
Monitor Performance through the Kubiya dashboard
Set up CI/CD integration with your runner

Introduction

Quick Start

Core Concepts

Using Kubiya

Workflows

MCP Integration

Administration

Reference

Deploy Kubiya runners to Kubernetes via Helm

Deploy Kubiya runners to Kubernetes via Helm

Overview

Before You Start

Step 1: Access the Runners Dashboard

Step 2: Create a New Runner

Step 3: Advanced Configuration

Step 4: Add the Kubiya Helm Repository

Step 5: Install the Runner

Quick Installation

Production Installation

Step 6: Verify Installation

Configuration Options

Environment Variables

Resource Management

Security Configuration

Networking

Advanced Configuration

Multiple Runner Types

High Availability Setup

Persistent Storage

Monitoring and Logging

Prometheus Integration

Log Aggregation

Upgrading

Update Runner Configuration

Version Management

Troubleshooting

Common Issues

Complete Helm Chart Reference

Next Steps

Introduction

Quick Start

Core Concepts

Using Kubiya

Workflows

MCP Integration

Administration

Reference

​Deploy Kubiya runners to Kubernetes via Helm

​Overview

​Before You Start

​Step 1: Access the Runners Dashboard

​Step 2: Create a New Runner

​Step 3: Advanced Configuration

​Step 4: Add the Kubiya Helm Repository

​Step 5: Install the Runner

​Quick Installation

​Production Installation

​Step 6: Verify Installation

​Configuration Options

​Environment Variables

​Resource Management

​Security Configuration

​Networking

​Advanced Configuration

​Multiple Runner Types

​High Availability Setup

​Persistent Storage

​Monitoring and Logging

​Prometheus Integration

​Log Aggregation

​Upgrading

​Update Runner Configuration

​Version Management

​Troubleshooting

​Common Issues

​Complete Helm Chart Reference

​Next Steps

Deploy Kubiya runners to Kubernetes via Helm

Overview

Before You Start

Step 1: Access the Runners Dashboard

Step 2: Create a New Runner

Step 3: Advanced Configuration

Step 4: Add the Kubiya Helm Repository

Step 5: Install the Runner

Quick Installation

Production Installation

Step 6: Verify Installation

Configuration Options

Environment Variables

Resource Management

Security Configuration

Networking

Advanced Configuration

Multiple Runner Types

High Availability Setup

Persistent Storage

Monitoring and Logging

Prometheus Integration

Log Aggregation

Upgrading

Update Runner Configuration

Version Management

Troubleshooting

Common Issues

Complete Helm Chart Reference

Next Steps