Single-node cluster setup

Note

Even though currently the scripts are set up for just a single node, all pieces of software are capable of setting up and running multiple control planes and worker nodes.

Warning

If you run Traefik in HA, make sure to shift from built-in certificatesResolvers usage to cert-manager. I removed cert-manager, because I am unlikely to have multiple nodes (for now).

This repository contains multiple modules and scripts, that you can run manually to set up a homelab / NAS. The scripts are very opinionated and they work for me - feel free to change anything you might want or need.

The host module is meant to set up the Proxmox v9 host.

The cluster module is meant to set up a Talos Kubernetes cluster.

The Step CA LXC module is meant to set up a Step CA LXC container.

Note

While the Step CA LXC container will work out of the box, Proxmox v9 will fail to install the necessary Step CA client. To install it on the Proxmox host, follow the instructions in the official documentation.

Note

I need to mount a specific partition persistently (ext4 filesystem) and in order to not have to look up the commands each time, I am noting them here:

$ mkdir -p /mnt/temp
$ cp /etc/fstab /etc/fstab.backup # backup fstab
$ echo "/dev/disk/by-id/nvme-Micron_7400_MTFDKBA800TFC_22063ABEC630-part1  /mnt/temp  ext4  defaults  0  2" >> /etc/fstab
$ mount -a # auto-mount all

This should be done before the host Terraform script is executed.

Table of Contents

• BOM
  • Deployment
  • System
  • Orchestration, network and storage
  • Security
  • Database
• Modules
  • Main modules
  • Common Modules
  • Legacy Modules (Not in Use)
• Scripts
  • State management
  • Terraform / cluster management

BOM

Here's a list of all the software being used in this homelab setup:

Deployment:

• OpenTofu / Terraform - Infrastructure provisioning
• Helm - Kubernetes package manager

System:

• Proxmox VE - Virtualization platform
• Talos Linux - Immutable Kubernetes OS
• Alpine Linux - Lightweight Linux distribution for containers

Orchestration, network and storage:

• Kubernetes - Container orchestration platform
• Cilium - eBPF-based networking, observability, and security
• Traefik - Modern reverse proxy and load balancer with automatic service discovery
• Local Path Provisioner - Dynamic local storage provisioner
• External DNS - Kubernetes addon to configure external DNS servers

Security:

• Step-CA CLI / server - Certificate authority for internal PKI
• Zitadel - Identity and access management platform

Database

• CloudNative-PG - Kubernetes operator for PostgreSQL, used by Zitadel and other applications
• pgAdmin - Web-based PostgreSQL administration and management tool

Modules

Host module

• host - Configures the Proxmox host with required packages, users, storage pools, and system settings
  • authorized-keys-appender - Handles appending of SSH keys to the authorized_keys file of a given user
  • copy-configs - Handles copying configuration files to the host
  • directory-mappings - Maps directories for VirtioFS sharing with VMs
  • gitops-user - Creates and manages a dedicated user with git+ssh access (gitops)
  • packages - Installs additional APT packages on the host
  • proxmox-storage-import - Imports existing storage directories into Proxmox
  • repositories - Manages APT repositories (enables no-subscription repo)
  • scripts - Executes various non-interactive setup scripts
  • share-user - Creates a dedicated user for file sharing
  • terraform-user - Creates Terraform user and API token for Proxmox automation
  • trust-proxmox-ca - Configures Proxmox to trust its own CA certificate
  • zfs-storage - Imports and manages ZFS storage pools

Cluster

• cluster - Sets up the Talos Kubernetes cluster on Proxmox with networking (Cilium), ingress (Traefik), storage (local-path-provisioner), DNS (external-dns), database (CloudNative-PG), and platform applications

  • talos-download-image - Downloads and manages Talos images for deployment

  • talos-prepare-cluster - Prepares cluster by generating machine secrets and configurations

  • talos-create-vm - Creates Talos VMs on Proxmox with proper configuration

  • talos-await-cluster - Waits for Talos cluster to become ready and available

  • infrastructure - Core cluster infrastructure components

    • cilium - Installs Cilium CNI for eBPF-based networking, observability, and security
    • traefik-crds - Installs Traefik Custom Resource Definitions
    • traefik - Installs Traefik v3 ingress controller with ACME support and OIDC capabilities
    • external-dns - Installs external-dns for automatic DNS record management
    • local-path-provisioner - Installs local-path-provisioner for dynamic local storage
    • metrics - Cluster metrics configuration

  • platform - Platform applications and services

    • cnpg-operator - Installs CloudNative-PG operator for PostgreSQL management
    • zitadel - Deploys Zitadel identity and access management platform
    • pgadmin - Deploys pgAdmin for PostgreSQL administration

Step CA LXC

• stepca-lxc - Sets up Step-CA certificate authority in an Alpine LXC container for internal PKI management

Common Modules

• common/modules/alpine - Creates Alpine Linux LXC containers with SSH access and basic packages
• common/modules/helm-terraform-installer - Installs Helm charts through Terraform with namespace and manifest management

Legacy Modules (Not in Use)

• (not-in-use)lldap-lxc - LLDAP lightweight directory service (deprecated)
• (not-in-use)pihole-lxc - Pi-hole DNS server (deprecated)

Scripts

State management

• backup-state.sh - Backs up Terraform state files to a remote host via SSH/SCP. Useful for preserving infrastructure state before major changes.

  Usage:
  

  ./backup-state.sh -d /remote/path [-s source_dir] [-h host] [-u user]

• restore-state.sh - Restores Terraform state files from a remote host. Complements the backup script for disaster recovery.

  Usage:
  

  ./restore-state.sh -d /remote/path [-h host] [-u user] [-o output_dir]

Terraform / cluster management

• cleanup-cluster.sh - Completely removes cluster VMs from Proxmox and cleans up local Terraform files. Supports dry-run mode.

  Usage:
  

  ./cleanup-cluster.sh PROXMOX_HOST [--dry-run] [--tf-path PATH]

• generate-docs.sh - Automatically generates README documentation for all Terraform modules using terraform-docs. Includes execution story generation.

  Usage:
  

  ./generate-docs.sh [PATH]

• story-plan.sh - Analyzes Terraform dependency graphs to show resource execution order. Supports both module-only and extended (resource-level) views.

  Usage:
  

  ./story-plan.sh [-d|--debug] [-x|--extended] [-r|--raw] [-p|--path PATH] [-b|--binary BINARY]