Cockpit Terraform Provider

The Cockpit Terraform Provider enables you to manage your Cockpit resources using Infrastructure as Code (IaC). Cockpit serves as the central control plane for multiple Vapor virtualization environments, and this provider allows you to automate the provisioning and lifecycle management of hosts, virtual machines, Kubernetes clusters, datastores, and network switches.

The provider registry page is available at Terraform Registry - awanio/cockpit.

Requirements

Terraform >= 1.0
Go >= 1.25 (only required for building the provider from source)

Provider Configuration

To use the provider, declare it in your Terraform configuration. The provider requires credentials from a Cockpit service account (Client ID and Client Secret) and the Cockpit API endpoint URL.

Schema Configuration

hcl

terraform {
  required_providers {
    cockpit = {
      source  = "awanio/cockpit"
      version = "~> 1.0.0" # Adjust to the desired version
    }
  }
}

provider "cockpit" {
  host          = "http://localhost:7771/api/v1"
  client_id     = "your-service-account-client-id"
  client_secret = "your-service-account-client-secret"
}

Environment Variables

Configuration parameters can also be passed using environment variables. This is the recommended approach to avoid hardcoding sensitive credentials in HCL files.

COCKPIT_HOST — The Cockpit API base URL (e.g., http://localhost:7771/api/v1).
COCKPIT_CLIENT_ID — The Client ID of the service account.
COCKPIT_CLIENT_SECRET — The Client Secret of the service account.

Resources

cockpit_host

Manages a Vapor host server registration and its connection within the Cockpit orchestrator.

Example Usage

hcl

resource "cockpit_host" "example" {
  address   = "10.0.0.15"
  port      = 7770
  api_token = "vapor-api-token-here"
  parent_id = "datacenter-or-cluster-uuid"
}

Argument Reference

address (String, Required) — The IP address or fully qualified domain name (FQDN) of the Vapor host.
port (Number, Optional) — The port where the Vapor API service is listening. Defaults to 7770.
api_token (String, Required, Sensitive) — The API token used to authenticate with the Vapor host.
parent_id (String, Required) — The UUID of the Datacenter or Cluster inventory entity where the host is placed.

cockpit_virtual_machine

Manages the lifecycle of a Virtual Machine in the Cockpit orchestrator.

Example Usage

hcl

resource "cockpit_virtual_machine" "example" {
  host_id   = "host-uuid-here"
  name      = "terraform-vm"
  memory    = 2048
  vcpus     = 2
  autostart = true

  os = {
    type    = "linux"
    variant = "ubuntu22.04"
  }

  storage = {
    disks = [
      {
        size = 20
        pool = "default"
      }
    ]
  }

  networks = [
    {
      type   = "network"
      source = "default"
    }
  ]
}

Argument Reference

host_id (String, Required) — The UUID of the Vapor host where the Virtual Machine will run.
name (String, Required) — The name of the virtual machine.
memory (Number, Required) — The allocated memory size in megabytes (MB).
vcpus (Number, Required) — The number of virtual CPU cores allocated to the machine.
cluster_id (String, Optional) — The UUID of the target cluster for VM scheduling.
datacenter_id (String, Optional) — The UUID of the target datacenter.
os (Block, Optional) — Operating system configuration parameters. Contains:
- type (String) — The OS type (e.g., linux, windows).
- variant (String) — The specific OS distribution variant (e.g., ubuntu22.04).
storage (Block, Optional) — Storage configuration parameters. Contains:
- disks (List of Blocks) — A list of disk configurations. Each disk block contains:
  - size (Number) — The size of the disk in gigabytes (GB).
  - pool (String) — The name of the storage pool where the disk will be provisioned.
networks (Block List, Optional) — Network interfaces to attach to the VM. Each network block contains:
- type (String) — The interface type (e.g., network).
- source (String) — The source network or bridge name.
autostart (Boolean, Optional) — Whether to automatically start the virtual machine when the host boots. Defaults to false.

cockpit_kubernetes_cluster

Manages a Kubernetes cluster provisioned via the Cockpit Auto-Provisioner service.

Example Usage

hcl

resource "cockpit_kubernetes_cluster" "k8s" {
  name           = "k8s-prod"
  version        = "v1.36.1+k3s1"
  network_id     = "network-switch-uuid"
  ssh_public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ..."
  image_path     = "/var/lib/libvirt/images/ubuntu-k8s-template.qcow2"

  control_plane = {
    cpu             = 2
    memory_mb       = 2048
    storage_pool_id = "default"
    storage_gb      = 20
    desired_count   = 1
  }

  workers = {
    cpu             = 2
    memory_mb       = 2048
    storage_pool_id = "default"
    storage_gb      = 20
    desired_count   = 3
  }

  csi_tiers = {
    local_path_enabled = true
    longhorn_enabled   = false
  }
}

Argument Reference

name (String, Required) — The name of the Kubernetes cluster.
version (String, Required) — The target K3s Kubernetes version tag (e.g., v1.36.1+k3s1).
network_id (String, Required) — The UUID of the network switch where the cluster nodes are attached.
ssh_public_key (String, Required) — The SSH public key injected into the cluster nodes for administrative access.
image_path (String, Optional) — Path to the OS template or golden image used for provisioning nodes.
control_plane (Block, Required) — Node specification for the control plane. Contains:
- cpu (Number) — CPU cores per control plane node.
- memory_mb (Number) — Memory in MB per control plane node.
- storage_pool_id (String) — Storage pool ID for the nodes' OS disks.
- storage_gb (Number) — Disk size in GB.
- desired_count (Number) — Number of control plane nodes (must be an odd number for HA, e.g., 1, 3, 5).
workers (Block, Required) — Node specification for worker nodes. Contains:
- cpu (Number) — CPU cores per worker node.
- memory_mb (Number) — Memory in MB per worker node.
- storage_pool_id (String) — Storage pool ID for the nodes' OS disks.
- storage_gb (Number) — Disk size in GB.
- desired_count (Number) — The desired number of worker nodes.
csi_tiers (Block, Optional) — Storage integration configurations for the Kubernetes Container Storage Interface (CSI). Contains:
- local_path_enabled (Boolean) — Enable or disable the local path CSI driver.
- longhorn_enabled (Boolean) — Enable or disable the Longhorn distributed block storage driver.

cockpit_datastore

Manages a storage datastore (storage pool) on a Vapor host.

Example Usage

hcl

resource "cockpit_datastore" "example" {
  name      = "nfs-images"
  host_id   = "host-uuid-here"
  type      = "netfs"
  path      = "/var/lib/libvirt/images/nfs-images"
  source    = "10.0.0.5:/exports/images"
  autostart = true
  scope     = "shared"
}

Argument Reference

name (String, Required) — The name of the storage pool or datastore.
host_id (String, Required) — The UUID of the Vapor host where the datastore is configured.
type (String, Required) — The type of storage pool (e.g., dir, netfs, logical, fs).
path (String, Optional) — The local filesystem target mount path or directory for the pool.
source (String, Optional) — The source path or export identifier (such as the remote NFS export string).
target (String, Optional) — Target storage identifier or path.
autostart (Boolean, Optional) — Automatically start the storage pool when the host system boots. Defaults to true.
scope (String, Optional) — The logical scope of the datastore. Supported values are local or shared. Defaults to local.

cockpit_switch

Manages a network switch (virtual network) on a Vapor host.

Example Usage

hcl

resource "cockpit_switch" "example" {
  name       = "vnet-nat-example"
  host_id    = "host-uuid-here"
  mode       = "nat"
  ip_address = "192.168.100.1"
  netmask    = "255.255.255.0"
  dhcp_start = "192.168.100.10"
  dhcp_end   = "192.168.100.100"
  autostart  = true
}

Argument Reference

name (String, Required) — The name of the virtual network switch.
host_id (String, Required) — The UUID of the target Vapor host.
mode (String, Required) — The network forwarding mode. Supported values are nat, bridge, route, and isolated.
bridge (String, Optional) — The name of the host bridge interface device.
ip_address (String, Optional) — The IP address assigned to the bridge interface.
netmask (String, Optional) — The subnet mask of the bridge network.
dhcp_start (String, Optional) — The start IP address for the DHCP allocation pool.
dhcp_end (String, Optional) — The end IP address for the DHCP allocation pool.
autostart (Boolean, Optional) — Automatically start the virtual switch when the host boots. Defaults to true.
domain (String, Optional) — DNS domain name prefix to assign to DHCP clients.

Local Development Compilation

For development or testing custom provider modifications locally, you can build the provider binary from source using the following command:

bash

go build -o terraform-provider-cockpit

Cockpit Terraform Provider ​

Requirements ​

Provider Configuration ​

Schema Configuration ​

Environment Variables ​

Resources ​

cockpit_host ​

Example Usage ​

Argument Reference ​

cockpit_virtual_machine ​

Example Usage ​

Argument Reference ​

cockpit_kubernetes_cluster ​

Example Usage ​

Argument Reference ​

cockpit_datastore ​

Example Usage ​

Argument Reference ​

cockpit_switch ​

Example Usage ​

Argument Reference ​

Local Development Compilation ​

Cockpit Terraform Provider

Requirements

Provider Configuration

Schema Configuration

Environment Variables

Resources

cockpit_host

Example Usage

Argument Reference

cockpit_virtual_machine

Example Usage

Argument Reference

cockpit_kubernetes_cluster

Example Usage

Argument Reference

cockpit_datastore

Example Usage

Argument Reference

cockpit_switch

Example Usage

Argument Reference

Local Development Compilation