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	Worker registration and management
controlplane_job	Scheduled, webhook-triggered, and manual jobs

Data Sources

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

• controlplane_environment
• controlplane_project
• controlplane_team
• controlplane_agent
• controlplane_skill
• controlplane_policy

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:

• Source: kubiya/control-plane
• Registry: https://registry.terraform.io/providers/kubiya/control-plane

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

Next Steps

• Getting Started Guide - Set up your first Terraform configuration
• Provider Configuration - Detailed configuration options
• Resources Documentation - Complete resource reference
• Operator Examples - End-to-end examples for common use cases

Support

• Issues: GitHub Issues
• Documentation: Kubiya Docs
• Provider Source: GitHub Repository