kubiya_runner

The kubiya_runner resource allows you to create and manage runners in the Kubiya platform. Runners are compute environments where Kubiya agents execute code and perform operations. They provide isolated, secure execution contexts for your automation tasks.

Runners provide dedicated compute environments that ensure consistent performance, security isolation, and resource management for your automation workloads.

Prerequisites

Before using this resource, ensure you have:

A Kubiya account with API access
An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
Appropriate permissions to create runners in your organization

Quick Start

resource "kubiya_runner" "basic" {
  name = "basic-runner"
}

resource "kubiya_agent" "basic_agent" {
  name         = "basic-agent"
  runner       = kubiya_runner.basic.name
  description  = "Agent using custom runner"
  instructions = "You are an agent running on dedicated infrastructure."
}

Configuration Examples

Create runners for different environments with corresponding agents:

locals {
  environments = ["dev", "staging", "prod"]
}

# Create runners for each environment
resource "kubiya_runner" "environment" {
  for_each = toset(local.environments)
  
  name = "${each.value}-runner"
}

# Create agents for each environment
resource "kubiya_agent" "environment_agent" {
  for_each = toset(local.environments)
  
  name         = "${each.key}-agent"
  runner       = kubiya_runner.environment[each.key].name
  description  = "Agent for ${each.key} environment"
  instructions = "You are an agent operating in the ${each.key} environment."
  
  environment_variables = {
    ENVIRONMENT = each.key
    LOG_LEVEL   = each.key == "prod" ? "INFO" : "DEBUG"
  }
}

# Environment-specific sources
resource "kubiya_source" "env_tools" {
  for_each = toset(local.environments)
  
  url    = "https://github.com/org/${each.value}-tools"
  runner = kubiya_runner.environment[each.key].name
}

Advanced Configurations

Runner with Custom Sources

Configure runners with specialized tools and sources:

resource "kubiya_runner" "ml_pipeline" {
  name = "machine-learning-runner"
}

resource "kubiya_source" "ml_tools" {
  url    = "https://github.com/org/ml-tools"
  runner = kubiya_runner.ml_pipeline.name
  
  dynamic_config = jsonencode({
    branch = "main"
    path   = "ml-workflows"
  })
}

resource "kubiya_inline_source" "custom_ml_tools" {
  name   = "custom-ml-tools"
  runner = kubiya_runner.ml_pipeline.name
  
  tools = jsonencode([
    {
      name        = "model-trainer"
      description = "Train machine learning models"
      type        = "docker"
      image       = "tensorflow/tensorflow:latest-py3"
      content     = "python /app/train_model.py"
      with_files = [
        {
          destination = "/app/train_model.py"
          content     = <<-PYTHON
            import tensorflow as tf
            import os
            
            def train_model():
                # Model training logic
                print("Training ML model...")
                model = tf.keras.Sequential([
                    tf.keras.layers.Dense(128, activation='relu'),
                    tf.keras.layers.Dense(10, activation='softmax')
                ])
                print("Model training completed")
            
            if __name__ == "__main__":
                train_model()
          PYTHON
        }
      ]
    }
  ])
}

resource "kubiya_agent" "ml_agent" {
  name         = "ml-engineer"
  runner       = kubiya_runner.ml_pipeline.name
  description  = "Machine learning engineering agent"
  instructions = "You are an ML engineer with access to TensorFlow and custom ML tools."
  
  sources = [
    kubiya_source.ml_tools.id,
    kubiya_inline_source.custom_ml_tools.id
  ]
  
  environment_variables = {
    TF_ENABLE_GPU = "true"
    CUDA_VISIBLE_DEVICES = "0"
    MODEL_OUTPUT_DIR = "/models"
  }
}

High-Availability Runner Setup

Configure runners for high-availability scenarios:

locals {
  regions = ["us-east-1", "us-west-2", "eu-west-1"]
}

resource "kubiya_runner" "ha_runners" {
  for_each = toset(local.regions)
  
  name = "ha-runner-${each.value}"
}

resource "kubiya_agent" "ha_agents" {
  for_each = toset(local.regions)
  
  name         = "ha-agent-${each.key}"
  runner       = kubiya_runner.ha_runners[each.key].name
  description  = "High-availability agent in ${each.key}"
  instructions = "You are a high-availability agent providing redundant automation capabilities."
  
  environment_variables = {
    REGION = each.key
    HA_MODE = "active"
    FAILOVER_REGION = local.regions[(index(local.regions, each.key) + 1) % length(local.regions)]
  }
}

# Load balancer configuration for agents
resource "kubiya_agent" "ha_coordinator" {
  name         = "ha-coordinator"
  runner       = "kubiya-hosted"
  description  = "High-availability coordinator agent"
  instructions = <<-EOT
    You coordinate between multiple high-availability agents.
    Route requests to available regional agents based on health and load.
    
    Available regional agents:
    ${join("\n", [for region in local.regions : "- ha-agent-${region}"])}
  EOT
}

Arguments Reference

Required Arguments

name

string

required

The name of the runner. Must be unique within your organization and should be descriptive of the runner’s purpose.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

runner_type

string

The type of the runner as computed by the system. This reflects the runner’s configuration and capabilities.

Runner Types and Use Cases

Organize runners by deployment environment:

# Development - for testing and experimentation
resource "kubiya_runner" "development" {
  name = "development-runner"
}

# Staging - for pre-production testing  
resource "kubiya_runner" "staging" {
  name = "staging-runner"
}

# Production - for live workloads
resource "kubiya_runner" "production" {
  name = "production-runner"
}

Import

Runners can be imported using their name:

terraform import kubiya_runner.example <runner-name>

Best Practices

Environment Management

Create separate runners for different environments (dev, staging, prod)
Use consistent naming conventions that indicate the runner’s purpose
Implement proper access controls and permissions for each environment
Consider resource requirements and scaling needs per environment

Workload Optimization

Design runners for specific workload types (compute, I/O, memory intensive)
Consider geographic distribution for global workloads
Plan for peak usage and scaling requirements
Monitor runner performance and resource utilization

Security & Compliance

Implement appropriate security controls for runner environments
Ensure compliance requirements are met for sensitive workloads
Use dedicated runners for high-security or regulated workloads
Regularly audit runner configurations and access patterns

Operations & Maintenance

Document the purpose and configuration of each runner
Implement monitoring and alerting for runner health
Plan for disaster recovery and high availability
Establish clear ownership and maintenance procedures

Special Runner Configurations

Kubiya-Hosted Runner: The special runner name “kubiya-hosted” refers to Kubiya’s cloud-hosted runners. These are managed by Kubiya and provide:

Automatic scaling and resource management
Built-in security and compliance measures
No infrastructure management overhead
Global availability and redundancy

Custom Runner Considerations: When creating custom runners, consider:

Resource requirements and scaling needs
Network connectivity and security requirements
Maintenance and update responsibilities
Monitoring and observability requirements

Runner Lifecycle Management

# Create runner first
resource "kubiya_runner" "example" {
  name = "example-runner"
}

# Then reference in agents
resource "kubiya_agent" "example_agent" {
  name   = "example-agent"
  runner = kubiya_runner.example.name
  # ... other configuration
}

Compatibility

Requirements:

Kubiya Terraform Provider version >= 1.0.0
Terraform >= 1.0
Runners must be created before they can be referenced by agents or sources
Runner names must be unique within your organization

Troubleshooting

Runner Creation Issues

Agent Association Problems

Performance Issues

Getting Started

Resources

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Attributes Reference

Runner Types and Use Cases

Import

Best Practices

Environment Management

Workload Optimization

Security & Compliance

Operations & Maintenance

Special Runner Configurations

Runner Lifecycle Management

Compatibility

Troubleshooting

Getting Started

Resources

​Prerequisites

​Quick Start

​Configuration Examples

​Advanced Configurations

​Arguments Reference

​Required Arguments

​Attributes Reference

​Runner Types and Use Cases

​Import

​Best Practices

Environment Management

Workload Optimization

Security & Compliance

Operations & Maintenance

​Special Runner Configurations

​Runner Lifecycle Management

​Compatibility

​Troubleshooting

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Attributes Reference

Runner Types and Use Cases

Import

Best Practices

Special Runner Configurations

Runner Lifecycle Management

Compatibility

Troubleshooting