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

Manages worker registration and configuration. Arguments:

environment_name (Required, string) - Environment name
hostname (Required, string) - Worker hostname
metadata (Optional, JSON string) - Worker metadata

Example:

resource "controlplane_worker" "worker_01" {
  environment_name = controlplane_environment.production.name
  hostname         = "worker-prod-01"

  metadata = jsonencode({
    region = "us-east-1"
    zone   = "us-east-1a"
    type   = "primary"
  })
}

controlplane_worker_queue

Manages worker queues for task execution. Arguments:

name (Required, string) - Queue name
environment_name (Required, string) - Environment name
display_name (Optional, string) - Display name
description (Optional, string) - Queue description
heartbeat_interval (Optional, number) - Heartbeat interval in seconds
max_workers (Optional, number) - Maximum workers
tags (Optional, list(string)) - Queue tags
settings (Optional, map(string)) - Queue settings

Example:

resource "controlplane_worker_queue" "production_primary" {
  name               = "production-primary"
  environment_name   = controlplane_environment.production.name
  display_name       = "Production Primary Queue"
  description        = "Primary worker queue for production"
  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 (Required, string) - Planning mode: “predefined_agent”, “predefined_team”, or “dynamic”
entity_type (Required, string) - Entity type: “agent” or “team”
entity_id (Optional, string) - Entity ID (use entity_id for direct reference)
prompt_template (Required, string) - Prompt template with variables
system_prompt (Optional, string) - System prompt for agent
executor_type (Required, string) - Executor: “auto”, “environment”
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
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"]
}

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)

Worker Queue-Specific Attributes

Worker queues also export:

task_name - Task name for worker registration

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

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

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

Getting Started

Reference

Guides

​Terraform Resources

​Core Resources

​controlplane_environment

​controlplane_project

​controlplane_team

​controlplane_agent

​Capability Resources

​controlplane_skill

​controlplane_policy

​controlplane_worker

​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

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