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

Data Sources - Query existing resources
Modules - Use pre-built modules for common patterns
Examples - Complete end-to-end examples
Provider Configuration - Configuration options

Getting Started

Reference

Guides

Resources

Terraform Resources

Core Resources

controlplane_environment

controlplane_project

controlplane_team

controlplane_agent

Capability Resources

controlplane_skill

controlplane_policy

controlplane_worker_queue

controlplane_job

Attributes Reference

Job-Specific Attributes

Worker Queue-Specific Attributes

Import

Best Practices

Resource Naming

Configuration as JSON

Dependencies

Tags for Organization

Next Steps

​Terraform Resources

​Core Resources

​controlplane_environment

​controlplane_project

​controlplane_team

​controlplane_agent

​Capability Resources

​controlplane_skill

​controlplane_policy

​controlplane_worker_queue

​controlplane_job

​Attributes Reference

​Job-Specific Attributes

​Worker Queue-Specific Attributes

​Import

​Best Practices

​Resource Naming

​Configuration as JSON

​Dependencies

​Tags for Organization

​Next Steps

Terraform Resources

Core Resources

controlplane_environment

controlplane_project

controlplane_team

controlplane_agent

Capability Resources

controlplane_skill

controlplane_policy

controlplane_worker_queue

controlplane_job

Attributes Reference

Job-Specific Attributes

Worker Queue-Specific Attributes

Import

Best Practices

Resource Naming

Configuration as JSON

Dependencies

Tags for Organization

Next Steps