​
Kubiya Terraform Provider

The Kubiya Terraform provider enables Infrastructure as Code (IaC) management of your Kubiya AI platform resources. Define, version, and deploy agents, workflows, integrations, and more through declarative Terraform configurations.
The Kubiya provider is officially supported and maintained by Kubiya. For support, visit support.kubiya.ai.

​
Why Use the Terraform Provider?

Infrastructure as Code

Version control your AI agents and workflows alongside your infrastructure

Reproducible Deployments

Deploy consistent configurations across environments

GitOps Ready

Integrate with your existing CI/CD pipelines

Drift Detection

Automatically detect and correct configuration drift

​
Quick Start

1

Install Provider

Add the provider to your Terraform configuration:
terraform {
  required_providers {
    kubiya = {
      source  = "kubiya-terraform/kubiya"
      version = "~> 1.0"
    }
  }
}

provider "kubiya" {
  # API key is read from KUBIYA_API_KEY environment variable
}
2

Set Authentication

Export your API key as an environment variable:
export KUBIYA_API_KEY="your-api-key-here"
Generate an API key from the Kubiya dashboard under Admin → Kubiya API Keys.
3

Create Resources

Define your first agent:
resource "kubiya_agent" "my_assistant" {
  name         = "terraform-assistant"
  runner       = "kubiya-hosted"
  description  = "AI assistant managed by Terraform"
  instructions = "You are a helpful AI assistant."
}
4

Deploy

Initialize and apply your configuration:
terraform init
terraform plan
terraform apply

​
Authentication

The Kubiya provider supports authentication via environment variable for security best practices. 
export KUBIYA_API_KEY="your-api-key"
The provider automatically reads from KUBIYA_API_KEY:
provider "kubiya" {
  # No explicit configuration needed
}
Never commit API keys to version control. Always use environment variables or secret management systems.

​
Available Resources

The Kubiya provider offers comprehensive resource management:

​
Core Resources

kubiya_agent - AI agents that can execute tasks and workflows
  • Define agent behaviors and capabilities
  • Configure access controls and permissions
  • Set up integrations and tools
kubiya_source - Workflow and tool definitions
  • Define reusable workflow templates
  • Create custom tool integrations
  • Version control your automation logic
kubiya_integration - Third-party service connections
  • Connect to external APIs and services
  • Configure OAuth and API key authentication
  • Manage integration lifecycles

​
Automation Resources

kubiya_webhook - Event-driven automation endpoints
  • Receive events from external systems
  • Trigger workflows automatically
  • Process incoming data
kubiya_trigger - HTTP endpoints for workflow execution
  • Create custom API endpoints
  • Handle HTTP requests
  • Return structured responses
kubiya_scheduled_task - Cron-based automation
  • Schedule recurring tasks
  • Define time-based workflows
  • Automate maintenance operations

​
Infrastructure Resources

kubiya_runner - Execution environments for agents
  • Configure compute resources
  • Set up isolated environments
  • Manage runner pools
kubiya_secret - Secure credential storage
  • Store API keys and tokens
  • Manage sensitive configuration
  • Control access permissions
kubiya_knowledge - AI knowledge repositories
  • Configure knowledge sources
  • Set up vector databases
  • Manage context for agents

​
Best Practices

​
Example Configurations

resource "kubiya_agent" "support_bot" {
  name         = "support-assistant"
  runner       = "kubiya-hosted"
  description  = "Customer support AI assistant"
  instructions = "Help users with technical support inquiries."
  
  allowed_users  = ["support-team@company.com"]
  allowed_groups = ["customer-support"]
}

​
Migration Guide

If you’re migrating from manual configuration to Terraform:
1

Import Existing Resources

terraform import kubiya_agent.existing agent-id-here
2

Generate Configuration

Use terraform show to view imported resource configuration
3

Refine and Apply

Adjust the configuration and apply changes incrementally

​
Troubleshooting

Ensure your API key is correctly set:
echo $KUBIYA_API_KEY
Verify the key has appropriate permissions in the Kubiya dashboard.
Check that resource names are unique within your organization and follow naming conventions.
The Kubiya API has rate limits. Use -parallelism=1 for large deployments:
terraform apply -parallelism=1

​
Next Steps

Getting Started Guide

Step-by-step tutorial for your first deployment

Example Configurations

Production-ready configuration examples

Resource Reference

Detailed documentation for all resources

Best Practices

Advanced patterns and recommendations

​
Support

Need Help?