Provider Configuration
This guide covers all configuration options for the Kubiya Control Plane Terraform Provider, including setup for both hosted (SaaS) and self-hosted deployments.
Basic Configuration
The provider is configured using environment variables for authentication and connection settings:
terraform {
required_providers {
controlplane = {
source = "kubiya/control-plane"
version = "~> 1.0"
}
}
}
provider "controlplane" {
# Configuration is read from environment variables:
# - KUBIYA_CONTROL_PLANE_API_KEY (required)
# - KUBIYA_CONTROL_PLANE_BASE_URL (optional)
}
Environment Variables
Required Variables
KUBIYA_CONTROL_PLANE_API_KEY
Your Kubiya Control Plane API key for authentication.
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key_here"
Never commit API keys to version control. Use environment variables, CI/CD secrets, or secrets management systems.
Optional Variables
KUBIYA_CONTROL_PLANE_BASE_URL
The base URL for your Kubiya Control Plane API.
Default: https://control-plane.kubiya.ai (hosted/SaaS)
# For self-hosted deployments
export KUBIYA_CONTROL_PLANE_BASE_URL="https://control-plane.your-company.com"
# For local development
export KUBIYA_CONTROL_PLANE_BASE_URL="http://localhost:7777"
Hosted Control Plane Configuration
For the hosted Kubiya Control Plane (SaaS), minimal configuration is required:
Step 1: Obtain API Key
- Visit https://compose.kubiya.ai
- Navigate to Settings → API Keys
- Click Generate New API Key
- Copy your API key (starts with
kcp_)
Step 2: Set Environment Variable
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key_here"
provider "controlplane" {
# API key from environment variable
# Base URL defaults to https://control-plane.kubiya.ai
}
Self-Hosted Control Plane Configuration
For self-hosted deployments, you need to specify both the API key and your custom base URL:
Step 1: Obtain API Key
- Access your self-hosted control plane dashboard
- Navigate to Settings → API Keys
- Generate and copy your API key
# Required: Your API key
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key_here"
# Required for self-hosted: Your control plane URL
export KUBIYA_CONTROL_PLANE_BASE_URL="https://control-plane.your-company.com"
provider "controlplane" {
# Both variables read from environment
}
Common Self-Hosted Scenarios
Internal Network Deployment
export KUBIYA_CONTROL_PLANE_BASE_URL="https://kubiya.internal.company.net"
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key"
On-Premise with Custom Port
export KUBIYA_CONTROL_PLANE_BASE_URL="https://kubiya.company.com:8443"
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key"
Local Development
export KUBIYA_CONTROL_PLANE_BASE_URL="http://localhost:7777"
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_dev_api_key"
For local development, you may need to disable TLS verification depending on your setup. Consult your control plane documentation for security considerations.
Authentication Methods
API Key Authentication
The provider uses API key authentication via the Authorization header.
Format: Authorization: Bearer <api-key>
API keys should:
- Start with
kcp_ prefix
- Be kept secure and never committed to version control
- Have appropriate permissions for the resources you’re managing
- Be rotated regularly per your security policies
API Key Permissions
Ensure your API key has the necessary permissions:
| Permission | Required For |
|---|
environments:read | Reading environment data sources |
environments:write | Creating/updating environments |
teams:read | Reading team data sources |
teams:write | Creating/updating teams |
agents:read | Reading agent data sources |
agents:write | Creating/updating agents |
policies:read | Reading policy data sources |
policies:write | Creating/updating policies |
Secrets Management
For production environments, use secrets management solutions instead of plain environment variables:
HashiCorp Vault
# data.tf
data "vault_generic_secret" "kubiya_api_key" {
path = "secret/kubiya/control-plane"
}
# Set environment variable from Vault
locals {
kubiya_api_key = data.vault_generic_secret.kubiya_api_key.data["api_key"]
}
export KUBIYA_CONTROL_PLANE_API_KEY=$(vault kv get -field=api_key secret/kubiya/control-plane)
terraform apply
AWS Secrets Manager
export KUBIYA_CONTROL_PLANE_API_KEY=$(aws secretsmanager get-secret-value \
--secret-id kubiya/control-plane/api-key \
--query SecretString \
--output text | jq -r .api_key)
Azure Key Vault
export KUBIYA_CONTROL_PLANE_API_KEY=$(az keyvault secret show \
--name kubiya-api-key \
--vault-name my-keyvault \
--query value -o tsv)
Google Cloud Secret Manager
export KUBIYA_CONTROL_PLANE_API_KEY=$(gcloud secrets versions access latest \
--secret="kubiya-control-plane-api-key")
CI/CD Integration
GitHub Actions
name: Terraform Apply
on:
push:
branches: [main]
jobs:
terraform:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Terraform
uses: hashicorp/setup-terraform@v2
with:
terraform_version: 1.5.0
- name: Terraform Init
run: terraform init
- name: Terraform Apply
env:
KUBIYA_CONTROL_PLANE_API_KEY: ${{ secrets.KUBIYA_API_KEY }}
# For self-hosted:
# KUBIYA_CONTROL_PLANE_BASE_URL: ${{ secrets.KUBIYA_BASE_URL }}
run: terraform apply -auto-approve
GitLab CI
terraform:
image: hashicorp/terraform:1.5
script:
- terraform init
- terraform plan
- terraform apply -auto-approve
variables:
KUBIYA_CONTROL_PLANE_API_KEY: $KUBIYA_API_KEY
# For self-hosted:
# KUBIYA_CONTROL_PLANE_BASE_URL: $KUBIYA_BASE_URL
only:
- main
Jenkins
pipeline {
agent any
environment {
KUBIYA_CONTROL_PLANE_API_KEY = credentials('kubiya-api-key')
// For self-hosted:
// KUBIYA_CONTROL_PLANE_BASE_URL = 'https://control-plane.company.com'
}
stages {
stage('Terraform Apply') {
steps {
sh 'terraform init'
sh 'terraform plan'
sh 'terraform apply -auto-approve'
}
}
}
}
CircleCI
version: 2.1
jobs:
terraform:
docker:
- image: hashicorp/terraform:1.5
steps:
- checkout
- run:
name: Terraform Init
command: terraform init
- run:
name: Terraform Apply
command: terraform apply -auto-approve
environment:
KUBIYA_CONTROL_PLANE_API_KEY: $KUBIYA_API_KEY
# For self-hosted:
# KUBIYA_CONTROL_PLANE_BASE_URL: $KUBIYA_BASE_URL
Workspace Variables
-
Navigate to your workspace in Terraform Cloud
-
Go to Variables
-
Add environment variables:
- Key:
KUBIYA_CONTROL_PLANE_API_KEY
- Value: Your API key
- Sensitive: ✓ (mark as sensitive)
- Category: Environment variable
-
For self-hosted, also add:
- Key:
KUBIYA_CONTROL_PLANE_BASE_URL
- Value: Your control plane URL
- Category: Environment variable
Variable Sets
For managing multiple workspaces, create a variable set:
# In Terraform Cloud UI
Variable Set: "Kubiya Control Plane"
- KUBIYA_CONTROL_PLANE_API_KEY (sensitive)
- KUBIYA_CONTROL_PLANE_BASE_URL (for self-hosted)
Applied to: All workspaces / Specific workspaces
Multiple Environments
Manage different environments with different configurations:
Using Workspaces
# Create workspaces
terraform workspace new production
terraform workspace new staging
terraform workspace new development
# Production
terraform workspace select production
export KUBIYA_CONTROL_PLANE_API_KEY="${PRODUCTION_API_KEY}"
export KUBIYA_CONTROL_PLANE_BASE_URL="${PRODUCTION_BASE_URL}"
terraform apply
# Staging
terraform workspace select staging
export KUBIYA_CONTROL_PLANE_API_KEY="${STAGING_API_KEY}"
export KUBIYA_CONTROL_PLANE_BASE_URL="${STAGING_BASE_URL}"
terraform apply
Using Separate Directories
environments/
production/
main.tf
terraform.tfvars
backend.tf
staging/
main.tf
terraform.tfvars
backend.tf
development/
main.tf
terraform.tfvars
backend.tf
Using Environment-Specific Files
# production.sh
export KUBIYA_CONTROL_PLANE_API_KEY="$PROD_API_KEY"
export KUBIYA_CONTROL_PLANE_BASE_URL="https://control-plane.prod.company.com"
# staging.sh
export KUBIYA_CONTROL_PLANE_API_KEY="$STAGING_API_KEY"
export KUBIYA_CONTROL_PLANE_BASE_URL="https://control-plane.staging.company.com"
# Usage
source production.sh && terraform apply
Troubleshooting
Connection Issues
Problem: Cannot connect to control plane
Error: Failed to query control plane API
- Verify
KUBIYA_CONTROL_PLANE_BASE_URL is correct
- Check network connectivity
- Verify firewall rules allow access
- For self-hosted, ensure the control plane is running
# Test connectivity
curl -I $KUBIYA_CONTROL_PLANE_BASE_URL/api/health
# Check DNS resolution
nslookup control-plane.your-company.com
Authentication Issues
Problem: Authentication failed
Solution:
- Verify API key is correct
- Check API key hasn’t expired
- Ensure API key has required permissions
# Verify environment variable is set
echo $KUBIYA_CONTROL_PLANE_API_KEY
# Test API key
curl -H "Authorization: Bearer $KUBIYA_CONTROL_PLANE_API_KEY" \
$KUBIYA_CONTROL_PLANE_BASE_URL/api/v1/environments
TLS/SSL Issues
Problem: SSL certificate verification failed
Error: x509: certificate signed by unknown authority
- Use properly signed certificates in production
- For development, consult your control plane docs for TLS configuration options
Best Practices
Security
- Never commit secrets: Use
.gitignore to exclude files with secrets
- Rotate API keys: Regularly rotate your API keys
- Use least privilege: Grant API keys only necessary permissions
- Audit access: Monitor API key usage through control plane logs
- Use secrets managers: Store credentials in dedicated secrets management systems
Configuration Management
- Environment-specific configs: Separate configurations per environment
- Version control: Track all Terraform configurations in Git
- Remote state: Use remote state backends with encryption
- State locking: Enable state locking to prevent concurrent modifications
- Consistent naming: Use clear, consistent naming conventions
Provider Versions
Pin provider versions for reproducibility:
terraform {
required_version = ">= 1.0"
required_providers {
controlplane = {
source = "kubiya/control-plane"
version = "1.2.3" # Specific version
# OR
# version = "~> 1.2" # Allow patch updates
}
}
}
Next Steps
