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

# Terraform Provider Overview

> Comprehensive guide to the Kubiya Control Plane Terraform Provider for managing infrastructure as code

# Kubiya Control Plane Terraform Provider

The Kubiya Control Plane Terraform Provider enables you to manage your entire Kubiya platform infrastructure as code. This provider allows operators to declaratively define and manage agents, teams, projects, environments, skills, policies, workers, and jobs using Terraform.

## Why Use Terraform with Kubiya?

* **Infrastructure as Code**: Version control your Kubiya resources alongside your application infrastructure
* **Repeatability**: Deploy consistent configurations across multiple environments
* **Automation**: Integrate Kubiya resource provisioning into your CI/CD pipelines
* **Collaboration**: Enable team collaboration through code reviews and GitOps workflows
* **Compliance**: Track changes and maintain audit trails for your AI agent infrastructure

## Supported Resources

The provider supports comprehensive management of all Kubiya Control Plane resources:

### Core Resources

| Resource                   | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `controlplane_environment` | Execution environments for agents and workers    |
| `controlplane_project`     | Projects for organizing resources                |
| `controlplane_team`        | Teams with shared configuration and capabilities |
| `controlplane_agent`       | AI agents with custom LLM configurations         |

### Capabilities

| Resource                    | Description                                               |
| --------------------------- | --------------------------------------------------------- |
| `controlplane_skill`        | Skills (filesystem, shell, docker) for agent capabilities |
| `controlplane_policy`       | OPA Rego policies for governance and security             |
| `controlplane_worker_queue` | Worker queues for task execution within environments      |
| `controlplane_job`          | Scheduled, webhook-triggered, and manual jobs             |

### Data Sources

All resources have corresponding data sources for read-only lookups:

* `controlplane_environment` - Look up a single environment by ID
* `controlplane_project` - Look up a single project by ID
* `controlplane_team` - Look up a single team by ID
* `controlplane_agent` - Look up a single agent by ID
* `controlplane_skill` - Look up a single skill by ID
* `controlplane_policy` - Look up a single policy by ID
* `controlplane_job` - Look up a single job by ID
* `controlplane_jobs` - List all jobs
* `controlplane_worker_queue` - Look up a single worker queue by ID
* `controlplane_worker_queues` - List all worker queues in an environment

## Deployment Options

The Kubiya Control Plane can be deployed in two ways:

### 1. Hosted Control Plane (SaaS)

Use Kubiya's managed control plane at `https://control-plane.kubiya.ai`:

```bash theme={null}
export KUBIYA_CONTROL_PLANE_API_KEY="your-api-key"
# KUBIYA_CONTROL_PLANE_BASE_URL not needed - defaults to hosted
```

### 2. Self-Hosted Control Plane

Deploy the control plane in your own infrastructure:

```bash theme={null}
export KUBIYA_CONTROL_PLANE_API_KEY="your-api-key"
export KUBIYA_CONTROL_PLANE_BASE_URL="https://your-control-plane.example.com"
```

Both deployment models use the same provider configuration and support identical features.

## Quick Example

```terraform theme={null}
terraform {
  required_providers {
    controlplane = {
      source  = "kubiya/control-plane"
      version = "~> 1.0"
    }
  }
}

provider "controlplane" {
  # Configuration via environment variables:
  # KUBIYA_CONTROL_PLANE_API_KEY (required)
  # KUBIYA_CONTROL_PLANE_BASE_URL (optional - defaults to https://control-plane.kubiya.ai)
}

# Create an environment
resource "controlplane_environment" "production" {
  name        = "production"
  description = "Production environment for agents"
}

# Create a team
resource "controlplane_team" "platform" {
  name    = "platform-team"
  runtime = "default"
}

# Create an agent
resource "controlplane_agent" "ops_assistant" {
  name        = "ops-assistant"
  description = "Operations assistant agent"
  model_id    = "kubiya/claude-sonnet-4"
  runtime     = "claude_code"
  team_id     = controlplane_team.platform.id

  llm_config = jsonencode({
    temperature = 0.7
    max_tokens  = 4096
  })
}
```

## Provider Registry

The provider is published to the official Terraform Registry:

* **Source**: `kubiya/control-plane`
* **Registry**: [https://registry.terraform.io/providers/kubiya/control-plane](https://registry.terraform.io/providers/kubiya/control-plane)

## Key Features for Operators

### Version Control

Track all changes to your Kubiya infrastructure in Git:

```bash theme={null}
git log terraform/
git diff terraform/production.tf
```

### Multi-Environment Management

Use Terraform workspaces or separate state files to manage multiple environments:

```bash theme={null}
terraform workspace new production
terraform workspace new staging
```

### Modular Configuration

Create reusable modules for common patterns:

```
modules/
  agent-team/
    main.tf
    variables.tf
    outputs.tf
```

### CI/CD Integration

Integrate with your existing deployment pipelines:

```yaml theme={null}
# GitHub Actions example
- name: Terraform Apply
  run: |
    terraform init
    terraform plan
    terraform apply -auto-approve
```

## Authentication & Security

The provider requires API key authentication:

1. **Generate API Key**: Create an API key from your Kubiya Control Plane dashboard
2. **Set Environment Variable**: Export `KUBIYA_CONTROL_PLANE_API_KEY`
3. **Secure Storage**: Use secrets management (Vault, AWS Secrets Manager, etc.)

Never commit API keys to version control. Use:

* Environment variables
* Terraform Cloud/Enterprise variables
* CI/CD secret stores
* Secret management systems

## Reusable Modules

The provider includes pre-built Terraform modules for common patterns:

* **engineering-org**: Complete organization setup with environments, teams, agents, skills, policies, and jobs

See [Modules Documentation](./modules) for details.

## Next Steps

* [Getting Started Guide](./getting-started) - Set up your first Terraform configuration
* [Provider Configuration](./provider-configuration) - Detailed configuration options
* [Resources Documentation](./resources) - Complete resource reference
* [Modules](./modules) - Reusable Terraform modules
* [Data Sources](./data-sources) - Query existing resources
* [Operator Examples](./examples) - End-to-end examples for common use cases

## Support

* **Issues**: [GitHub Issues](https://github.com/kubiya-terraform/kubiya-control-plane/issues)
* **Documentation**: [Kubiya Docs](https://docs.kubiya.ai)
* **Provider Source**: [GitHub Repository](https://github.com/kubiya-terraform/kubiya-control-plane)