Skip to main content

​
Terraform Resources

This page provides a comprehensive reference for all resources available in the Kubiya Control Plane Terraform Provider.

​
Core Resources

​
controlplane_environment

Manages execution environments for agents and workers. Arguments:
  • name (Required, string) - Environment name
  • display_name (Optional, string) - Display name
  • description (Optional, string) - Environment description
  • tags (Optional, list(string)) - Tags for organization
  • configuration (Optional, JSON string) - Environment configuration
  • execution_environment (Optional, JSON string) - Execution settings
Example: 
resource "controlplane_environment" "production" {
  name         = "production"
  display_name = "Production Environment"
  description  = "Production environment for agents"
  tags         = ["production", "managed-by-terraform"]

  configuration = jsonencode({
    region         = "us-east-1"
    max_workers    = 20
    auto_scaling   = true
    retention_days = 90
  })

  execution_environment = jsonencode({
    env_vars = {
      LOG_LEVEL = "info"
      APP_ENV   = "production"
    }
  })
}

​
controlplane_project

Manages projects for organizing resources. Arguments:
  • name (Required, string) - Project name
  • key (Required, string) - Project key (uppercase abbreviation)
  • description (Optional, string) - Project description
  • goals (Optional, string) - Project goals
  • visibility (Optional, string) - Visibility setting (“private” or “public”)
  • metadata (Optional, JSON string) - Additional metadata
Example: 
resource "controlplane_project" "platform" {
  name        = "platform-engineering"
  key         = "PLAT"
  description = "Platform engineering and infrastructure"
  goals       = "Manage and automate platform infrastructure"
  visibility  = "private"

  metadata = jsonencode({
    owner       = "platform-team"
    cost_center = "engineering"
  })
}

​
controlplane_team

Manages teams with shared configuration and capabilities. Arguments:
  • name (Required, string) - Team name
  • description (Optional, string) - Team description
  • runtime (Required, string) - Runtime type: “default” (Agno) or “claude_code” (Claude Code SDK)
  • configuration (Optional, JSON string) - Team configuration
  • capabilities (Optional, list(string)) - Team capabilities
Example: 
resource "controlplane_team" "devops" {
  name        = "devops-team"
  description = "DevOps and platform engineering team"
  runtime     = "claude_code"

  configuration = jsonencode({
    max_agents     = 15
    slack_channel  = "#devops-agents"
    alert_on_error = true
  })

  capabilities = ["deployment", "monitoring", "incident_response"]
}

​
controlplane_agent

Manages AI agents with custom LLM configurations. Arguments:
  • name (Required, string) - Agent name
  • description (Optional, string) - Agent description
  • model_id (Required, string) - LLM model (e.g., “kubiya/claude-sonnet-4”, “kubiya/gpt-4”)
  • runtime (Required, string) - Runtime: “default” or “claude_code”
  • team_id (Optional, string) - Team ID to assign agent
  • llm_config (Required, JSON string) - LLM configuration (temperature, max_tokens, etc.)
  • configuration (Optional, JSON string) - Agent-specific configuration
  • capabilities (Optional, list(string)) - Agent capabilities
Example: 
resource "controlplane_agent" "deployer" {
  name        = "production-deployer"
  description = "AI agent for production deployments"
  model_id    = "kubiya/claude-sonnet-4"
  runtime     = "claude_code"
  team_id     = controlplane_team.devops.id

  llm_config = jsonencode({
    temperature = 0.3
    max_tokens  = 4096
  })

  configuration = jsonencode({
    capabilities    = ["kubernetes", "helm", "terraform"]
    max_retries     = 3
    timeout         = 900
    approval_needed = true
  })

  capabilities = ["kubernetes_deploy", "helm_deploy", "rollback"]
}

​
Capability Resources

​
controlplane_skill

Manages skills for agent capabilities (filesystem, shell, docker, etc.). Arguments:
  • name (Required, string) - Skill name
  • description (Optional, string) - Skill description
  • type (Required, string) - Skill type: “shell”, “file_system”, “docker”, “custom”
  • enabled (Optional, bool) - Whether skill is enabled (default: true)
  • configuration (Optional, JSON string) - Skill-specific configuration
Examples: Shell Skill: 
resource "controlplane_skill" "shell_ops" {
  name        = "shell-operations"
  description = "Shell command execution"
  type        = "shell"
  enabled     = true

  configuration = jsonencode({
    allowed_commands = ["kubectl", "helm", "aws", "terraform"]
    timeout          = 600
    working_dir      = "/app"
  })
}
Filesystem Skill: 
resource "controlplane_skill" "filesystem" {
  name        = "filesystem-access"
  description = "File system operations"
  type        = "file_system"
  enabled     = true

  configuration = jsonencode({
    allowed_paths = ["/app/configs", "/app/data"]
    max_file_size = 52428800 # 50MB
    operations    = ["read", "write", "list", "delete"]
  })
}
Docker Skill: 
resource "controlplane_skill" "docker" {
  name        = "docker-operations"
  description = "Docker container management"
  type        = "docker"
  enabled     = true

  configuration = jsonencode({
    allowed_registries = ["docker.io", "gcr.io", "ghcr.io"]
    max_containers     = 20
    network_mode       = "bridge"
  })
}

​
controlplane_policy

Manages OPA Rego policies for governance and security. Arguments:
  • name (Required, string) - Policy name
  • description (Optional, string) - Policy description
  • enabled (Optional, bool) - Whether policy is enabled (default: true)
  • policy_content (Required, string) - OPA Rego policy content
  • tags (Optional, list(string)) - Policy tags
Example: 
resource "controlplane_policy" "security" {
  name        = "production-security"
  description = "Security policy for production"
  enabled     = true

  policy_content = <<-EOT
    package kubiya.security

    # Deny destructive operations without approval
    deny[msg] {
      input.operation = "delete"
      input.environment = "production"
      count(input.approvals) < 2
      msg := "Delete operations require at least 2 approvals"
    }

    # Require MFA for sensitive operations
    deny[msg] {
      input.operation = "deploy"
      input.environment = "production"
      not input.mfa_verified
      msg := "Production deployments require MFA verification"
    }
  EOT

  tags = ["security", "production", "compliance"]
}

​
controlplane_worker_queue

Manages worker queues for task execution within an environment. Arguments:
  • environment_id (Required, string) - Environment ID (cannot be changed after creation)
  • name (Required, string) - Queue name (lowercase, no spaces, 2-50 characters)
  • display_name (Optional, string) - Display name (default: "")
  • description (Optional, string) - Queue description (default: "")
  • status (Optional, string) - Queue status: “active”, “inactive”, or “paused” (default: “active”)
  • heartbeat_interval (Optional, number) - Heartbeat interval in seconds (10-300, default: 60)
  • max_workers (Optional, number) - Maximum workers (null = unlimited)
  • tags (Optional, list(string)) - Queue tags (default: [])
  • settings (Optional, map(string)) - Additional settings as key-value pairs (default: )
Computed Attributes:
  • id - Worker Queue ID
  • active_workers - Number of currently active workers
  • task_queue_name - Task queue name for Temporal
  • created_at - Creation timestamp
  • updated_at - Last update timestamp
Example: 
resource "controlplane_worker_queue" "production_primary" {
  environment_id     = controlplane_environment.production.id
  name               = "production-primary"
  display_name       = "Production Primary Queue"
  description        = "Primary worker queue for production"
  status             = "active"
  heartbeat_interval = 60
  max_workers        = 20
  tags               = ["production", "primary", "high-priority"]

  settings = {
    region   = "us-east-1"
    tier     = "production"
    priority = "high"
  }
}

​
controlplane_job

Manages scheduled, webhook-triggered, and manual jobs. Arguments:
  • name (Required, string) - Job name
  • description (Optional, string) - Job description
  • enabled (Optional, bool) - Whether job is enabled (default: true)
  • trigger_type (Required, string) - Trigger type: “cron”, “webhook”, or “manual”
  • cron_schedule (Optional, string) - Cron expression (required for cron triggers)
  • cron_timezone (Optional, string) - Timezone for cron (default: “UTC”)
  • planning_mode (Optional, string) - Planning mode: “predefined_agent”, “predefined_team”, “predefined_workflow”, or “on_the_fly” (default: “predefined_agent”)
  • entity_type (Optional, string) - Entity type: “agent”, “team”, or “workflow” (required when planning_mode is not “on_the_fly”)
  • entity_id (Optional, string) - Entity ID (agent_id, team_id, or workflow_id) (required when planning_mode is not “on_the_fly”)
  • prompt_template (Required, string) - Prompt template with variables
  • system_prompt (Optional, string) - System prompt for agent
  • executor_type (Optional, string) - Executor: “auto”, “specific_queue”, or “environment” (default: “auto”)
  • worker_queue_name (Optional, string) - Worker queue name (required for “specific_queue” executor)
  • environment_name (Optional, string) - Environment name (required for “environment” executor)
  • execution_env_vars (Optional, map(string)) - Environment variables
  • execution_secrets (Optional, list(string)) - Secret names
  • execution_integrations (Optional, list(string)) - Integration IDs to inject
  • config (Optional, JSON string) - Additional configuration
Examples: Cron Job: 
resource "controlplane_job" "health_check" {
  name          = "daily-health-check"
  description   = "Daily health check at 9am UTC"
  enabled       = true
  trigger_type  = "cron"
  cron_schedule = "0 9 * * *"
  cron_timezone = "UTC"

  planning_mode   = "predefined_agent"
  entity_type     = "agent"
  entity_id       = controlplane_agent.monitor.id
  prompt_template = "Run daily health check"
  system_prompt   = "Check all services and report issues"

  executor_type = "auto"

  execution_env_vars = {
    CHECK_TYPE = "comprehensive"
  }
}
Webhook Job: 
resource "controlplane_job" "deployment_webhook" {
  name         = "deployment-handler"
  description  = "Handle deployment webhooks"
  enabled      = true
  trigger_type = "webhook"

  planning_mode   = "predefined_agent"
  entity_type     = "agent"
  entity_id       = controlplane_agent.deployer.id
  prompt_template = "Deploy {{service}} version {{version}}"
  system_prompt   = "Process deployment request"

  executor_type    = "environment"
  environment_name = controlplane_environment.production.name

  config = jsonencode({
    timeout = 1800
  })
}
Manual Job: 
resource "controlplane_job" "incident_response" {
  name         = "incident-response"
  description  = "Manual incident response"
  enabled      = true
  trigger_type = "manual"

  planning_mode   = "predefined_agent"
  entity_type     = "agent"
  entity_id       = controlplane_agent.incident_responder.id
  prompt_template = "Handle incident: {{incident_id}}"
  system_prompt   = "Coordinate incident response"

  executor_type = "auto"

  execution_secrets = ["pagerduty_token"]
}
Job with Specific Queue: 
resource "controlplane_job" "queue_specific" {
  name         = "queue-specific-job"
  description  = "Job routed to specific worker queue"
  enabled      = true
  trigger_type = "cron"
  cron_schedule = "0 */6 * * *"  # Every 6 hours
  cron_timezone = "UTC"

  planning_mode   = "predefined_agent"
  entity_type     = "agent"
  entity_id       = controlplane_agent.batch_processor.id
  prompt_template = "Process batch data"
  system_prompt   = "Execute batch processing task"

  executor_type     = "specific_queue"
  worker_queue_name = controlplane_worker_queue.batch_queue.name

  execution_env_vars = {
    BATCH_SIZE = "100"
  }
}
Job with Integrations: 
resource "controlplane_job" "cloud_sync" {
  name         = "cloud-sync"
  description  = "Sync data with cloud providers"
  enabled      = true
  trigger_type = "cron"
  cron_schedule = "0 3 * * *"  # Daily at 3 AM
  cron_timezone = "UTC"

  planning_mode   = "predefined_team"
  entity_type     = "team"
  entity_id       = controlplane_team.devops.id
  prompt_template = "Sync cloud resources and update inventory"

  executor_type = "auto"

  execution_env_vars = {
    SYNC_TYPE = "full"
  }

  execution_secrets = ["cloud_api_token"]

  # Integration IDs for AWS, GCP, Azure
  execution_integrations = ["integration-aws-123", "integration-gcp-456", "integration-azure-789"]

  config = jsonencode({
    timeout = 3600
    retry_policy = {
      max_attempts = 2
    }
  })
}
Job with On-the-Fly Planning: 
resource "controlplane_job" "dynamic_query" {
  name         = "dynamic-query"
  description  = "Handle dynamic queries with on-the-fly agent selection"
  enabled      = true
  trigger_type = "webhook"

  planning_mode   = "on_the_fly"
  # No entity_type or entity_id needed for on_the_fly mode
  prompt_template = "Answer query: {{query}}"

  executor_type    = "environment"
  environment_name = controlplane_environment.production.name

  execution_env_vars = {
    MAX_RESPONSE_TIME = "30"
  }
}

​
Attributes Reference

All resources export the following attributes:
  • id - Unique identifier for the resource
  • created_at - Timestamp when resource was created
  • updated_at - Timestamp when resource was last updated

​
Job-Specific Attributes

Jobs also export:
  • webhook_url - Webhook URL (for webhook trigger type)
  • webhook_secret - Webhook HMAC secret for signature verification (sensitive)
  • status - Job status

​
Worker Queue-Specific Attributes

Worker queues also export:
  • environment_id - Environment ID
  • status - Queue status
  • active_workers - Number of active workers
  • task_queue_name - Task queue name for Temporal

​
Import

Resources can be imported using their ID: 
terraform import controlplane_agent.example agent-xxxxx
terraform import controlplane_team.example team-xxxxx
terraform import controlplane_environment.example env-xxxxx
terraform import controlplane_project.example project-xxxxx
terraform import controlplane_skill.example skill-xxxxx
terraform import controlplane_policy.example policy-xxxxx
terraform import controlplane_worker_queue.example queue-xxxxx
terraform import controlplane_job.example job-xxxxx

​
Best Practices

​
Resource Naming

Use consistent, descriptive names: 
resource "controlplane_agent" "production_deployer" {
  name = "production-deployer"
}

​
Configuration as JSON

Use jsonencode() for configuration blocks: 
configuration = jsonencode({
  key = "value"
})

​
Dependencies

Use explicit dependencies when needed: 
resource "controlplane_agent" "example" {
  team_id = controlplane_team.devops.id
  depends_on = [controlplane_skill.shell]
}

​
Tags for Organization

Use tags consistently: 
tags = ["environment:production", "managed-by:terraform", "team:devops"]

​
Next Steps