> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resources

> Complete reference for all Kubiya Control Plane Terraform resources

# 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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:**

```terraform theme={null}
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:

```bash theme={null}
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:

```terraform theme={null}
resource "controlplane_agent" "production_deployer" {
  name = "production-deployer"
}
```

### Configuration as JSON

Use `jsonencode()` for configuration blocks:

```terraform theme={null}
configuration = jsonencode({
  key = "value"
})
```

### Dependencies

Use explicit dependencies when needed:

```terraform theme={null}
resource "controlplane_agent" "example" {
  team_id = controlplane_team.devops.id
  depends_on = [controlplane_skill.shell]
}
```

### Tags for Organization

Use tags consistently:

```terraform theme={null}
tags = ["environment:production", "managed-by:terraform", "team:devops"]
```

## Next Steps

* [Data Sources](./data-sources) - Query existing resources
* [Modules](./modules) - Use pre-built modules for common patterns
* [Examples](./examples) - Complete end-to-end examples
* [Provider Configuration](./provider-configuration) - Configuration options