Make sure you have generated anin order to use the provider
Getting Started with Kubiya Provider
This guide will help you get started with the Kubiya Terraform provider. By the end of this guide, you'll have created your first Kubiya AI Teammate (agent) with a basic configuration and understand how to set up more advanced integrations.
Prerequisites
A Kubiya account with API access
Terraform installed on your system
Basic familiarity with Terraform
Install Terraform
If you haven't already, you'll need to install Terraform. Ensure you have the version compatible with the provider you intend to use.
Setup Your Terraform Configuration
Initialize a New Terraform Directory:
Create a new directory for your Terraform configuration files. You can do this with your system's command line interface:
mkdir terraform-kubiya
cd terraform-kubiya
touch main.tf
Create a Terraform Configuration File:
Within this directory, create a new file named main.tf. You can do this using a text editor. Then, copy the provided Terraform plan into this file.
Configuring the Provider
First, you'll need to configure the Kubiya provider in your Terraform configuration. Create a new directory for your Terraform files and create a file named main.tf with the following content:
terraform {
required_providers {
kubiya = {
source = "kubiya-terraform/kubiya"
}
}
}
provider "kubiya" {
# API key can be provided via environment variable KUBIYA_API_KEY
}
Setting up your API Key
The Kubiya provider requires an API key for authentication. You can generate an API key from the Kubiya dashboard under Admin → Kubiya API Keys.
Set the API key as an environment variable:
export KUBIYA_API_KEY="your-api-key"
Creating Your First Runner
Before you can create an agent, you need a runner. Runners are the compute environments where your agents execute code.
Add the following to your main.tf file:
resource "kubiya_runner" "first_runner" {
name = "my-first-runner"
description = "My first Kubiya runner"
type = "vcluster"
}
Deploying the Runner
After creating the runner resource through Terraform, you will need to deploy the helm chart of the created runner. You can use the Kubiya dashboard to access the complete helm chart for your runner.
Adding Knowledge Sources
Knowledge sources provide information to your agents. Sources are required for agent resources - every agent must have at least one source.
# Create a source for your agent
resource "kubiya_source" "basic_tooling" {
name = "basic-tooling"
description = "Basic tooling for the agent"
url = "https://github.com/kubiyabot/community-tools/tree/main/basics"
runner = kubiya_runner.first_runner.name
}
Creating Your First Agent (Sources Required)
Now you can create your first agent, which will use the runner and source you just defined. Remember: Every agent must have at least one source - this is a mandatory requirement:
resource "kubiya_agent" "first_agent" {
name = "my-first-agent"
runner = kubiya_runner.first_runner.name
description = "My first Kubiya agent created through Terraform"
# Sources are REQUIRED for all agents - this is not optional
sources = [kubiya_source.basic_tooling.name]
# Optional: Configure some conversation starters
starters = [
{
name = "Hello"
command = "Say hello and introduce yourself"
},
{
name = "Help"
command = "List what you can help me with"
}
]
}
Adding Knowledge Resources
In addition to sources, you can create specific knowledge resources that contain information your agents can reference:
# Add a direct knowledge entry
resource "kubiya_knowledge" "company_faq" {
name = "company-faq"
description = "Company FAQ and procedures"
content = file("${path.module}/company-faq.md")
format = "markdown"
}
Managing Sensitive Information with Secrets
Secrets allow you to securely store sensitive information that your agents might need:
resource "kubiya_secret" "api_credentials" {
name = "api-credentials"
description = "API credentials for external services"
data = {
api_key = var.api_key
api_secret = var.api_secret
}
}
# Reference the secret in your agent
resource "kubiya_agent" "api_agent" {
name = "api-integration-agent"
runner = kubiya_runner.first_runner.name
description = "Agent with API integration capabilities"
# Sources are required for agents
sources = [kubiya_source.basic_tooling.name]
# Link the secret to the agent
secrets = [kubiya_secret.api_credentials.name]
}
Setting Up Integrations
Integrations connect your agents to external services:
resource "kubiya_integration" "github_integration" {
name = "github-org"
type = "github"
description = "GitHub organization integration"
configuration = {
org_name = "mycompany"
}
}
# Link the integration to an agent
resource "kubiya_agent" "devops_agent" {
name = "devops-agent"
runner = kubiya_runner.first_runner.name
description = "DevOps automation agent"
# Sources are required for agents
sources = [kubiya_source.basic_tooling.name]
integrations = [kubiya_integration.github_integration.name]
}
Creating Webhooks for Event-Driven Automation
Webhooks allow external systems to trigger your agents:
