Skip to content

alexmorbo/terraform-proxmox-talos

BranchesTags

Repository files navigation

About

GitHub Release GitHub

Terraform module to provision Talos Linux-based Kubernetes clusters on Proxmox Virtual Environment (PVE). Handles VM creation, Talos image deployment, cluster bootstrapping, and client configuration setup.

Features

  • Deploys Kubernetes clusters based on Talos Linux
  • Supports both control plane and worker nodes
  • Downloads and provisions Talos images into Proxmox
  • Optional creation of kubeconfig and talosconfig files locally
  • Modular and customizable node group definitions

Quick Start

module "talos_cluster" {
  source        = "github.com/alexmorbo/terraform-proxmox-talos"
  cluster_name  = "mycluster"
  talos_cp_version = "1.10.0"
  talos_schematic = [
    "siderolabs/i915",
    "siderolabs/qemu-guest-agent",
  ]

  default_gateway = "10.90.12.1"
  cluster_vip     = "10.90.12.11"

  vm_subnet      = "10.90.12.0/24"
  pod_subnet     = "10.209.0.0/16"
  service_subnet = "10.208.0.0/16"

  proxmox_cluster = {
    cluster_name = "homelab"
    nodes = {
      node-1 = {
        datastore = "local-lvm"
      }
      node-2 = {
        datastore = "local-lvm"
      }
      node-3 = {
        datastore = "local-lvm"
      }
    }
  }

  controlplanes = {
    node-1 = {
      count = 1
      networks = [
        {
          interface = "eth0"
          bridge    = "vmbr0"
        },
      ]
    }
    node-2 = {
      count = 1
      networks = [
        {
          interface = "eth0"
          bridge    = "vmbr0"
        },
      ]
    }
    node-3 = {
      count = 1
      networks = [
        {
          interface = "eth0"
          bridge    = "vmbr0"
        },
      ]
    }
  }

  workers = {
    node-1 = {
      ingress = {
        count = 1
        cpu   = 2
        ram   = 4096
        networks = [
          {
            interface = "eth0"
            bridge    = "vmbr0"
          },
        ]
      }
      default = {
        count = 2
        networks = [
          {
            interface = "eth0"
            bridge    = "vmbr0"
          },
        ]
      }
    }
    node-2 = {
      ingress = {
        count = 1
        cpu   = 2
        ram   = 4096
        networks = [
          {
            interface = "eth0"
            bridge    = "vmbr0"
          },
        ]
      }
      default = {
        count = 1
        networks = [
          {
            interface = "eth0"
            bridge    = "vmbr0"
          },
        ]
      }
    }
    node-2 = {
      ingress = {
        count = 1
        cpu   = 2
        ram   = 4096
        networks = [
          {
            interface = "eth0"
            bridge    = "vmbr0"
          },
        ]
      }
    }
  }
}

Module Structure

  • modules/node_group/ – reusable logic for control plane and worker nodes
  • images.tf – Talos image downloading and provisioning
  • talos.tf – Talos client and machine configurations
  • virtual_machines.tf – VM creation logic for Proxmox
  • files.tf – optional local configuration file generation

Notes

  • Tested with Proxmox VE 8.2
  • Requires a user with access to upload ISO/images and manage VMs
  • Make sure to enable Talos provider by setting environment variables or credentials

Requirements

Name Version
terraform >= 1.5.0
local >= 2.5.2
proxmox >= 0.76.1
talos >= 0.8.0

Providers

Name Version
local 2.5.3
proxmox 0.76.1
talos 0.8.0-alpha.0

Modules

Name Source Version
control_plane ./modules/node_group n/a
worker_node_group ./modules/node_group n/a

Resources

Name Type
local_file.kubeconfig resource
local_file.talosconfig resource
proxmox_virtual_environment_download_file.talos_image resource
talos_cluster_kubeconfig.this resource
talos_image_factory_schematic.version resource
talos_machine_bootstrap.this resource
talos_machine_configuration_apply.this resource
talos_machine_secrets.this resource
talos_client_configuration.this data source
talos_image_factory_extensions_versions.version data source
talos_machine_configuration.this data source

Inputs

Name Description Type Default Required
cilium_values A map of configuration values for Cilium, used to customize its deployment and behavior in the Kubernetes cluster. any 
{
  "cgroup": {
    "autoMount": {
      "enabled": false
    },
    "hostRoot": "/sys/fs/cgroup"
  },
  "externalIPs": {
    "enabled": true
  },
  "hubble": {
    "tls": {
      "auto": {
        "method": "cronJob"
      }
    }
  },
  "ipam": {
    "mode": "kubernetes"
  },
  "k8sClientRateLimit": {
    "burst": 100,
    "qps": 50
  },
  "k8sServiceHost": "localhost",
  "k8sServicePort": 7445,
  "kubeProxyReplacement": true,
  "l2announcements": {
    "enabled": true
  },
  "operator": {
    "replicas": 1
  },
  "rollOutCiliumPods": true,
  "routingMode": "tunnel",
  "securityContext": {
    "capabilities": {
      "ciliumAgent": [
        "CHOWN",
        "KILL",
        "NET_ADMIN",
        "NET_RAW",
        "IPC_LOCK",
        "SYS_ADMIN",
        "SYS_RESOURCE",
        "DAC_OVERRIDE",
        "FOWNER",
        "SETGID",
        "SETUID"
      ],
      "cleanCiliumState": [
        "NET_ADMIN",
        "SYS_ADMIN",
        "SYS_RESOURCE"
      ]
    }
  },
  "tunnelProtocol": "vxlan"
}
 no
cluster_name The name of the Talos cluster. string n/a yes
cluster_vip The virtual IP (VIP) address for the cluster, typically used for load balancing or high availability setups. string n/a yes
controlplanes Configuration of control plane nodes, including the number of nodes, resources (CPU, RAM), and network configuration. 
map(object({
    count   = number
    socket  = optional(number, 1)
    cpu     = optional(number, 4)
    ram     = optional(number, 8192)
    sysctls = optional(map(string), {})
    networks = list(object({
      interface     = string
      bridge        = string
      tag           = number
      model         = optional(string, "virtio")
      address       = optional(string, null)
      dhcp_disabled = optional(bool, false)
    }))
  }))
 n/a yes
create_kubeconfig_file Flag to determine whether a local kubernetes configuration file should be created. If set to true, a local_file resource will be generated with the appropriate content. bool false no
create_talosconfig_file Flag to determine whether a local Talos configuration file should be created. If set to true, a local_file resource will be generated with the appropriate content. bool false no
default_gateway The default gateway for the cluster nodes, used for routing external traffic. string n/a yes
dns A set of DNS server addresses to be used by the cluster nodes. Default includes Cloudflare and Google DNS. set(string) 
[
  "1.1.1.1",
  "8.8.8.8"
]
 no
kubeconfig_file_template Template path for the kubeconfig file, where '__CLUSTER__' will be replaced by the cluster name. string "~/.kube/configs/__CLUSTER__.yaml" no
kubernetes_version The desired version of Kubernetes to be installed in the cluster. string "1.33.0" no
pod_subnet The subnet for Kubernetes pods, defining the IP range for pod networking. string n/a yes
proxmox_cluster Proxmox cluster configuration, including the cluster name and the datastore associated with each node. 
object({
    cluster_name = string
    nodes = map(object({
      datastore = string
    }))
  })
 n/a yes
service_subnet The subnet for Kubernetes services, defining the IP range for internal cluster services. string n/a yes
sysctls A map of sysctl settings to be applied to the nodes in the cluster. These settings can be used to tune kernel parameters for performance or security. map(string) {} no
talos_arch The architecture for Talos nodes. Defaults to 'amd64'. string "amd64" no
talos_cp_version The desired version of Talos to be used in the cluster nodes. string n/a yes
talos_cp_version_update Optional: The Talos control plane version update, if any, to apply to the existing Talos version. string null no
talos_factory_url The URL of the Talos factory, used for managing node images and configurations. string "https://factory.talos.dev" no
talos_platform The platform type for Talos, typically used to define how nodes are provisioned (e.g., nocloud, vmware, etc.). string "nocloud" no
talos_schematic A set of Talos configuration files or schematics to apply during the cluster setup. set(string) n/a yes
talosconfig_file_name The path and filename for the generated Talos configuration file. Defaults to ~/.talos/config. string "~/.talos/config" no
vm_subnet The subnet for the virtual machines in the cluster. string n/a yes
workers Configuration of worker nodes, with the ability to specify the number of nodes, Talos version, Kubernetes version, and network details. 
map(map(object({
    count                = number
    talos_version        = optional(string)
    talos_version_update = optional(string)
    kubernetes_version   = optional(string)
    socket               = optional(number, 1)
    cpu                  = optional(number, 4)
    ram                  = optional(number, 8192)
    sysctls              = optional(map(string), {})
    networks = list(object({
      bridge        = string
      tag           = number
      interface     = string
      model         = optional(string, "virtio")
      address       = optional(string, null)
      dhcp_disabled = optional(bool, false)
    }))
    pci_passthrough = optional(list(object({
      id      = optional(string)
      mapping = optional(string)
      pcie    = optional(bool, true)
      rombar  = optional(bool, true)
      xvga    = optional(bool, false)
    })))
  })))
 {} no

Outputs

Name Description
all_ips A set of all the IP addresses used by the cluster nodes. This includes both control plane and worker nodes.
cilium_values The Cilium values used for the cluster initialization, which define the configuration for the Cilium CNI plugin.
cluster_name The name of the Kubernetes cluster, as defined in the input variable.
dedicated_node_groups Set of dedicated node groups in the cluster, that have taints.
kubeconfig The kubeconfig for accessing the Kubernetes cluster, containing the necessary authentication information and cluster context.
kubernetes_version n/a
node_ips A map of node names to their respective IP addresses, showing the internal IPs of each node in the cluster.
talos_config The Talos configuration used for the cluster nodes, containing sensitive data such as credentials and settings for node provisioning.
talos_version n/a

About

Terraform module to provision Talos Linux Kubernetes clusters with Proxmox

Topics

kubernetes terraform talos terraform-module

Resources

Readme

License

MIT license
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases 1

v0.1.1 Latest
May 4, 2025

Packages

No packages published

Languages