Skip to main content

​
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

ResourceDescription
controlplane_environmentExecution environments for agents and workers
controlplane_projectProjects for organizing resources
controlplane_teamTeams with shared configuration and capabilities
controlplane_agentAI agents with custom LLM configurations

​
Capabilities

ResourceDescription
controlplane_skillSkills (filesystem, shell, docker) for agent capabilities
controlplane_policyOPA Rego policies for governance and security
controlplane_worker_queueWorker queues for task execution within environments
controlplane_jobScheduled, 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: 
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: 
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 {
  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:

​
Key Features for Operators

​
Version Control

Track all changes to your Kubiya infrastructure in Git: 
git log terraform/
git diff terraform/production.tf

​
Multi-Environment Management

Use Terraform workspaces or separate state files to manage multiple environments: 
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: 
# 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 for details.

​
Next Steps

​
Support