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:
  1. A Kubiya account with API access
  2. An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
  3. 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

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"
  }
}
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

  • Verify you have appropriate permissions to create runners
  • Check that the runner name is unique within your organization
  • Ensure the runner name follows naming conventions (no special characters)
  • Confirm your organization has available runner quota
  • Ensure the runner exists before referencing it in agents
  • Check that the runner name exactly matches in agent configuration
  • Verify the runner is active and available
  • Confirm the agent has permissions to use the specified runner
  • Monitor runner resource utilization and performance metrics
  • Consider workload distribution across multiple runners
  • Check for resource constraints or bottlenecks
  • Review runner capacity and scaling requirements