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"

Step 3: Configure Provider

provider "controlplane" {
  # API key from environment variable
  # Base URL defaults to https://control-plane.kubiya.ai
}

That’s it! The provider will automatically connect to the hosted control plane.

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

Step 2: Configure Environment Variables

# 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"

Step 3: Configure Provider

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

Contact your Kubiya administrator to configure API key permissions.

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

Terraform Cloud / Enterprise

Configure environment variables in your workspace:

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

Solution:

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

Error: 401 Unauthorized

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

Solution (for self-hosted with self-signed certificates):

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

Resource Documentation - Learn about available resources
Data Sources - Query existing resources
Modules - Use pre-built modules for common patterns
Examples - Complete end-to-end examples
API Reference - Control Plane API documentation

​Provider Configuration

​Basic Configuration

​Environment Variables

​Required Variables

​KUBIYA_CONTROL_PLANE_API_KEY

​Optional Variables

​KUBIYA_CONTROL_PLANE_BASE_URL

​Hosted Control Plane Configuration

​Step 1: Obtain API Key

​Step 2: Set Environment Variable

​Step 3: Configure Provider

​Self-Hosted Control Plane Configuration

​Step 1: Obtain API Key

​Step 2: Configure Environment Variables

​Step 3: Configure Provider

​Common Self-Hosted Scenarios

​Internal Network Deployment

​On-Premise with Custom Port

​Local Development

​Authentication Methods

​API Key Authentication

​API Key Permissions

​Secrets Management

​HashiCorp Vault

​AWS Secrets Manager

​Azure Key Vault

​Google Cloud Secret Manager

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Jenkins

​CircleCI

​Terraform Cloud / Enterprise

​Workspace Variables

​Variable Sets

​Multiple Environments

​Using Workspaces

​Using Separate Directories

​Using Environment-Specific Files

​Troubleshooting

​Connection Issues

​Authentication Issues

​TLS/SSL Issues

​Best Practices

​Security

​Configuration Management

​Provider Versions

​Next Steps

Provider Configuration

Basic Configuration

Environment Variables

Required Variables

KUBIYA_CONTROL_PLANE_API_KEY

Optional Variables

KUBIYA_CONTROL_PLANE_BASE_URL

Hosted Control Plane Configuration

Step 1: Obtain API Key

Step 2: Set Environment Variable

Step 3: Configure Provider

Self-Hosted Control Plane Configuration

Step 1: Obtain API Key

Step 2: Configure Environment Variables

Step 3: Configure Provider

Common Self-Hosted Scenarios

Internal Network Deployment

On-Premise with Custom Port

Local Development

Authentication Methods

API Key Authentication

API Key Permissions

Secrets Management

HashiCorp Vault

AWS Secrets Manager

Azure Key Vault

Google Cloud Secret Manager

CI/CD Integration

GitHub Actions

GitLab CI

Jenkins

CircleCI

Terraform Cloud / Enterprise

Workspace Variables

Variable Sets

Multiple Environments

Using Workspaces

Using Separate Directories

Using Environment-Specific Files

Troubleshooting

Connection Issues

Authentication Issues

TLS/SSL Issues

Best Practices

Security

Configuration Management

Provider Versions

Next Steps