> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Configuration

> Detailed configuration guide for the Kubiya Control Plane Terraform Provider including hosted and self-hosted deployments

# 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 theme={null}
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.

```bash theme={null}
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key_here"
```

<Warning>
  Never commit API keys to version control. Use environment variables, CI/CD secrets, or secrets management systems.
</Warning>

### Optional Variables

#### KUBIYA\_CONTROL\_PLANE\_BASE\_URL

The base URL for your Kubiya Control Plane API.

**Default**: `https://control-plane.kubiya.ai` (hosted/SaaS)

```bash theme={null}
# 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

1. Visit [https://compose.kubiya.ai](https://compose.kubiya.ai)
2. Navigate to **Settings** → **API Keys**
3. Click **Generate New API Key**
4. Copy your API key (starts with `kcp_`)

### Step 2: Set Environment Variable

```bash theme={null}
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key_here"
```

### Step 3: Configure Provider

```terraform theme={null}
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

1. Access your self-hosted control plane dashboard
2. Navigate to **Settings** → **API Keys**
3. Generate and copy your API key

### Step 2: Configure Environment Variables

```bash theme={null}
# 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

```terraform theme={null}
provider "controlplane" {
  # Both variables read from environment
}
```

### Common Self-Hosted Scenarios

#### Internal Network Deployment

```bash theme={null}
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

```bash theme={null}
export KUBIYA_CONTROL_PLANE_BASE_URL="https://kubiya.company.com:8443"
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_your_api_key"
```

#### Local Development

```bash theme={null}
export KUBIYA_CONTROL_PLANE_BASE_URL="http://localhost:7777"
export KUBIYA_CONTROL_PLANE_API_KEY="kcp_dev_api_key"
```

<Tip>
  For local development, you may need to disable TLS verification depending on your setup. Consult your control plane documentation for security considerations.
</Tip>

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

```hcl theme={null}
# 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"]
}
```

```bash theme={null}
export KUBIYA_CONTROL_PLANE_API_KEY=$(vault kv get -field=api_key secret/kubiya/control-plane)
terraform apply
```

### AWS Secrets Manager

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
export KUBIYA_CONTROL_PLANE_API_KEY=$(gcloud secrets versions access latest \
  --secret="kubiya-control-plane-api-key")
```

## CI/CD Integration

### GitHub Actions

```yaml theme={null}
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

```yaml theme={null}
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

```groovy theme={null}
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

```yaml theme={null}
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

1. Navigate to your workspace in Terraform Cloud

2. Go to **Variables**

3. Add environment variables:
   * **Key**: `KUBIYA_CONTROL_PLANE_API_KEY`
   * **Value**: Your API key
   * **Sensitive**: ✓ (mark as sensitive)
   * **Category**: Environment variable

4. 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:

```hcl theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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**:

1. Verify `KUBIYA_CONTROL_PLANE_BASE_URL` is correct
2. Check network connectivity
3. Verify firewall rules allow access
4. For self-hosted, ensure the control plane is running

```bash theme={null}
# 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**:

1. Verify API key is correct
2. Check API key hasn't expired
3. Ensure API key has required permissions

```bash theme={null}
# 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):

1. Use properly signed certificates in production
2. For development, consult your control plane docs for TLS configuration options

## Best Practices

### Security

1. **Never commit secrets**: Use `.gitignore` to exclude files with secrets
2. **Rotate API keys**: Regularly rotate your API keys
3. **Use least privilege**: Grant API keys only necessary permissions
4. **Audit access**: Monitor API key usage through control plane logs
5. **Use secrets managers**: Store credentials in dedicated secrets management systems

### Configuration Management

1. **Environment-specific configs**: Separate configurations per environment
2. **Version control**: Track all Terraform configurations in Git
3. **Remote state**: Use remote state backends with encryption
4. **State locking**: Enable state locking to prevent concurrent modifications
5. **Consistent naming**: Use clear, consistent naming conventions

### Provider Versions

Pin provider versions for reproducibility:

```terraform theme={null}
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](./resources) - Learn about available resources
* [Data Sources](./data-sources) - Query existing resources
* [Modules](./modules) - Use pre-built modules for common patterns
* [Examples](./examples) - Complete end-to-end examples
* [API Reference](../api-reference/overview) - Control Plane API documentation