Homelab on zharif.my

GitHub Organization as Code with Terraform

Wed, 22 Apr 2026 00:00:00 +0000

Why This Matters

If you’ve ever tried to explain to your team that “we can’t create a new repo right now, I’m at dinner,” you understand why GitHub management should be code. Every infrastructure change in my homelab goes through code review — including how we manage GitHub itself.

The problem: GitHub’s web UI is fine for 3 repos, painful for 30+. You can’t track who changed what, can’t enforce naming conventions, and can’t ensure consistency across repositories.

The solution: treat your GitHub organization like database infrastructure. Define everything in YAML, let Terraform handle the drift, and sleep better at night.

Scale: This setup manages 40+ repositories across my organization with full configuration, teams, secrets, and custom properties.

All Terraform resources support lifecycle { create_before_destroy = true } for zero-downtime deployments.

Architecture

The github-management-plane repository manages my GitHub organization through Terraform — the same configuration-driven pattern as my homelab infrastructure:

  graph TB
    G[github-management-plane]
    R[Repository Module]
    S[Secrets/Variables Module]
    O[Organization Custom Properties]
    
    G --> R
    G --> S
    G --> O
    
    Repos["All Repositories"]
    Vars["Actions Variables"]
    Secs["Actions Secrets"]
    
    Repos --> tf-infra-homelab["tf-infra-homelab"]
    Repos --> tf-module-proxmox-talos["tf-module-proxmox-talos"]
    Repos --> applications-homelab["applications-homelab"]
    Repos --> ...["24+ repositories"]

What This Module Does

Repository management — create and configure all repositories via YAML
Team management — define teams and members
Organization custom properties — classify repositories
Actions secrets/variables — manage organization-wide secrets
Issue labels — standardize labels across repositories

Quick Start

module "repositories" {
  source   = "./modules/repository"
  for_each = local.filtered_repo_configurations
  
  configuration = each.value
  organization  = var.github_organization
}

Repository Management

All repositories are defined as YAML configurations:

# configurations/repository/tf-infra-homelab.yaml
name: tf-infra-homelab
description: A terraform infrastructure repository for managing my homelab environment
enabled: true
archived: false
visibility: private
type: terraform-infrastructure

topics:
  - homelab
  - proxmox

enabled_features:
  vulnerability_alerts: true
  issues: true
  wiki: false
  projects: false
  discussions: false

Repository Types

The module supports different repository types with defaults:

locals {
  repository_types = {
    terraform-infrastructure = {
      license_template = "mit"
      auto_init       = true
      topics        = ["terraform", "homelab"]
    }
    terraform-module = {
      license_template = "mit"
      auto_init       = true
      topics         = ["terraform", "proxmox"]
    }
    python-docker-application = {
      license_template = "mit"
      auto_init       = true
      topics         = ["python", "docker"]
    }
    generic = {
      auto_init = true
    }
  }
}

Repository Resource

resource "github_repository" "this" {
  name        = var.configuration.name
  description = var.configuration.description
  visibility  = var.configuration.visibility
  
  allow_rebase_merge    = true
  allow_squash_merge  = true
  delete_branch_on_merge = true
  
  vulnerability_alerts = var.configuration.enabled_features.vulnerability_alerts
  has_discussions     = var.configuration.enabled_features.discussions
  has_issues         = var.configuration.enabled_features.issues
  has_projects       = var.configuration.enabled_features.projects
  has_wiki           = var.configuration.enabled_features.wiki
}

Organization Custom Properties

Custom properties allow classification and filtering:

locals {
  organization_custom_properties = {
    "can-be-public" = {
      description   = "To indicate whether the repository can be made public"
      value_type  = "single_select"
      required   = true
      allowed_values = ["true", "false"]
      default_value = "false"
    }
    
    "managed-by" = {
      description = "To identify who manages the repository"
      value_type = "single_select"
      required = true
      allowed_values = [
        "github-management-plane",
        "manual-management",
      ]
      default_value = "manual-management"
    }
    
    "repository-type" = {
      description = "To indicate the type of repository"
      value_type = "single_select"
      required = true
      allowed_values = [
        "generic",
        "repository-template",
        "golang-linux-package",
        "golang-docker-application",
        "python-docker-application",
        "python-package",
        "terraform-infrastructure",
        "terraform-module",
      ]
    }
  }
}

Apply them:

resource "github_organization_custom_properties" "managed_properties" {
  for_each   = local.organization_custom_properties
  
  property_name = each.key
  value_type  = each.value.value_type
  required   = each.value.required
  description = each.value.description
  default_value = each.value.default_value
  allowed_values = each.value.allowed_values
}

Secrets and Variables

Actions secrets and variables are managed through Bitwarden:

# configurations/secrets_variables/global.yaml
variables:
  - name: RUNNER
    value: self-hosted
    visibility: all

secrets:
  - name: BWS_ACCESS_TOKEN
    is_manual: true
    visibility: private

Variable Resource

resource "github_actions_organization_variable" "managed_variables" {
  for_each = { for v in var.configuration.variables : v.name => v }
  
  variable_name = each.value.name
  visibility   = each.value.visibility
  value        = each.value.value
}

Secret Resource

For secrets, two patterns:

# Manual secrets (value set outside Terraform)
resource "github_actions_organization_secret" "managed_secrets_manual" {
  for_each = { for v in var.configuration.secrets : v.name => v if v.is_manual }
  
  secret_name = each.value.name
  visibility = each.value.visibility
  plaintext_value = "NONE"
}

# Synced secrets (from Bitwarden)
resource "github_actions_organization_secret" "managed_secrets_sync" {
  for_each = { for v in var.configuration.secrets : v.name => v if !v.is_manual }
  
  secret_name     = each.value.name
  visibility     = each.value.visibility
  plaintext_value = data.bitwarden-secrets_secret.secrets[each.value.name].value
}

Get secrets from Bitwarden:

data "bitwarden-secrets_secret" "secrets" {
  for_each = { for v in local.all_secrets : v.name => v if !v.is_manual }
  id      = each.value.bw_secret_id
}

Team Management

Teams are defined in the main module:

resource "github_team" "organization_administrators" {
  name        = "organization-administrators"
  description = "Team with administrative access to the organization"
  privacy     = "closed"
}

resource "github_team_members" "organization_administrators_members" {
  team_id = github_team.organization_administrators.id
  
  members = {
    "your-username" = {
      role = "maintainer"
    }
  }
}

Issue Labels

Labels are standardized across repositories:

locals {
  shared_labels = {
    "bug" = {
      color   = "d73a4a"
      description = "Bug report"
    }
    "enhancement" = {
      color   = "a2eeef"
      description = "New feature"
    }
    "documentation" = {
      color   = "0075ca"
      description = "Documentation improvements"
    }
  }
}

resource "github_issue_labels" "this" {
  repository = var.configuration.name
  
  label = merge(
    local.shared_labels,
    try(var.configuration.labels, {})
  )
}

My Repository Configuration

Here’s the list of repositories managed:

configurations/repository/
├── tf-infra-homelab.yaml          # Homelab infrastructure
├── tf-infra-github-management-plane.yaml  # GitHub management
├── tf-module-proxmox-lxc.yaml    # LXC module
├── tf-module-proxmox-vm.yaml    # VM module
├── tf-module-proxmox-talos.yaml  # Talos module
├── tf-module-proxmox-docker.yaml # Docker module
├── applications-homelab.yaml   # Kustomize apps
├── cf-worker-terraform-registry.yaml  # TF registry worker
├── cf-worker-apt-repository.yaml   # APT repository worker
├── template-terraform-basic.yaml   # Module template
├── template-cloudflare-worker-python.yaml  # Worker template
└── ... (24 total)

Each is just a YAML file — adding a new repository is adding a file.

Configuration Structure

github-management-plane/
├── configurations/
│   ├── repository/           # Repository definitions
│   ├── secrets_variables/   # Actions secrets/variables
│   └── rulesets/           # Branch protection (future)
├── modules/
│   ├── repository/         # Repository module
│   ├── secrets_variables/  # Secrets module
│   └── organization/        # Org properties module
├── main.tf                 # Orchestration
├── locals.tf              # Configuration loading
└── providers.tf          # Provider setup

This mirrors the homelab infrastructure structure.

Outputs

The module doesn’t have specific outputs since it manages the organization passively.

What’s Next

Branch protection rulesets — via rulesets API (when Terraform provider supports it)
Repository invitations — managing outside collaborators
Security advisories — automated security scanning

What Most People Get Wrong

“GitHub Terraform is just for repos” — It’s org-wide: teams, custom properties, secrets, variables. The whole thing.
“One Terraform run is enough” — Git rate limits apply. Use ratenode provider or caching.
“Manual changes are fine if you revert” — Terraform drift will catch you. Enable logento or run terraform refresh regularly.

When to Use / When NOT to Use

Use GitHub Management Plane	Do it manually
20+ repositories	1-5 repos
Team collaboration	Personal projects
Audit requirements	Quick experiments
Secret/variable management	Ad-hoc scripts only

This makes GitHub management declarative — every change goes through code review.

Self-Service Infrastructure with Backstage

Sat, 18 Apr 2026 00:00:00 +0000

Why Self-Service Matters

In my homelab, I was the bottleneck. Every new Kubernetes cluster meant:

  flowchart LR
    A[Create YAML] --> B[Find free IPs]
    B --> C[Configure node sizes]
    C --> D[Manually create Backstage catalog entries]
    D --> E[Open PR]
    E --> F[Wait for review]

That’s 6 steps where 4 could be automated.

The insight: infrastructure already defined as YAML. Backstage should consume that same YAML and generate its own catalog entries.

Real-world constraint: I deploy clusters infrequently (quarterly?), so I forget the steps. The templated approach ensures consistency whether I do this once a month or once a year.

This post covers the Backstage integration for homelab infrastructure. See the architecture overview for how it fits in the broader platform.

Two Integration Points

Backstage integrates with the homelab infrastructure in two ways:

Resource Catalog — auto-generated entities from infrastructure YAML configurations
Software Templates — scaffolder templates for self-service provisioning

  graph LR
    subgraph "Configuration"
        C[configurations/*.yaml]
    end
    
    subgraph "Generation"
        G[generate_backstage_catalog.py]
    end
    
    subgraph "Backstage"
        R[Resource Catalog]
        T[Software Templates]
    end
    
    C --> G
    G --> R
    G --> T

Auto-Generated Catalog

Running make backstage-catalog generates Backstage Resource entities from configurations:

make backstage-catalog
# ✓ kubernetes--prod-k8s.yaml (prod-k8s, disabled)
# ✓ kubernetes--dev-k8s.yaml (dev-k8s, disabled)
# ✓ docker--prod-docker-lxc.yaml (prod-docker-lxc, disabled)
# ✓ docker--dev-docker-lxc.yaml (dev-docker-lxc, enabled)

Generated Entity Example

Each generated YAML file is a Backstage Resource:

# backstage/catalog/kubernetes--prod-k8s.yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: prod-k8s
  description: Talos kubernetes cluster configuration for production environment
  annotations:
    github.com/project-slug: your-org/your-infra-repo
    homelab.dev/configuration-file: configurations/kubernetes/prod-k8s.yaml
    homelab.dev/resource-type: kubernetes
    homelab.dev/schema-file: configuration_schemas/kubernetes.schema.yaml
    backstage.io/techdocs-entity: component:terraform-module-kubernetes
    homelab.dev/cluster-name: prod-k8s
    homelab.dev/talos-version: v1.12.4
    homelab.dev/kubernetes-version: v1.35.0
    homelab.dev/vip-address: 192.168.62.20
  labels:
    homelab.dev/enabled: 'false'
    homelab.dev/environment: prod
    homelab.dev/control-plane-count: '3'
    homelab.dev/worker-count: '3'
    homelab.dev/size-control_plane-cpu: '4'
    homelab.dev/size-control_plane-memory: '8192'
    homelab.dev/size-worker-cpu: '10'
    homelab.dev/size-worker-memory: '49152'
  tags:
    - disabled
    - kubernetes
    - prod
    - proxmox
    - talos
spec:
  type: kubernetes-cluster
  lifecycle: experimental
  owner: group:default/homelab-admins
  system: tf-infra-homelab
  dependsOn:
    - component:default/terraform-module-kubernetes

Docker Cluster Entity

# backstage/catalog/docker--prod-docker-lxc.yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: prod-docker-lxc
  description: Docker configuration on lxc for production environment
  annotations:
    github.com/project-slug: your-org/your-infra-repo
    homelab.dev/configuration-file: configurations/docker/prod-docker-lxc.yaml
    homelab.dev/resource-type: docker
    homelab.dev/cluster-name: prod-docker-lxc
    homelab.dev/cluster-type: lxc
    homelab.dev/vip-address: 192.168.61.20
  labels:
    homelab.dev/enabled: 'false'
    homelab.dev/environment: prod
    homelab.dev/worker-count: '3'
    homelab.dev/size-medium-cpu: '8'
    homelab.dev/size-medium-memory: '32768'
  tags:
    - disabled
    - docker
    - lxc
    - prod
    - proxmox
spec:
  type: docker-cluster
  lifecycle: experimental
  owner: group:default/homelab-admins
  system: tf-infra-homelab
  dependsOn:
    - component:default/terraform-module-docker

Metadata Extraction

The generation script extracts key metadata from configurations:

# scripts/generate_backstage_catalog.py

def extract_kubernetes_metadata(config: dict) -> dict:
    """Extract catalog-relevant metadata from a Kubernetes configuration."""
    annotations = {}
    labels = {}
    
    cluster = config.get("cluster", {})
    annotations["homelab.dev/cluster-name"] = cluster.get("name", "")
    
    talos = cluster.get("talos", {}) or {}
    annotations["homelab.dev/talos-version"] = talos.get("version", "")
    annotations["homelab.dev/kubernetes-version"] = cluster.get("kubernetes_version", "")
    
    cp_nodes = config.get("control_plane_nodes", {}).get("nodes", [])
    worker_nodes = config.get("worker_nodes", {}).get("nodes", [])
    labels["homelab.dev/control-plane-count"] = str(len(cp_nodes))
    labels["homelab.dev/worker-count"] = str(len(worker_nodes))
    
    cp_vip = config.get("control_plane_nodes", {}).get("vip", {})
    if cp_vip and cp_vip.get("enabled"):
        annotations["homelab.dev/vip-address"] = cp_vip.get("address", "")
    
    sizes = config.get("node_size_configuration", {})
    for size_name, size_spec in sizes.items():
        labels[f"homelab.dev/size-{size_name}-cpu"] = str(size_spec.get("cpu", ""))
        labels[f"homelab.dev/size-{size_name}-memory"] = str(size_spec.get("memory", ""))
    
    return {"annotations": annotations, "labels": labels}

This enables filtering in Backstage:

homelab.dev/environment=prod — production clusters
homelab.dev/enabled=true — currently deployed
homelab.dev/size-worker-memory=49152 — large workers

Catalog-Info Definition

The root catalog-info.yaml defines the domain, system, and components:

# Domain: homelab
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: homelab
  description: Self-hosted homelab infrastructure managed with Terraform and Proxmox
  annotations:
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: your-org/your-infra-repo
spec:
  owner: group:default/homelab-admins

---
# System: tf-infra-homelab
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: tf-infra-homelab
  description: Terraform-managed homelab infrastructure provisioning system
spec:
  owner: group:default/homelab-admins
  domain: homelab

---
# Component: terraform-module-kubernetes
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: terraform-module-kubernetes
  description: Terraform module for provisioning Kubernetes (Talos) clusters on Proxmox
spec:
  type: terraform-module
  lifecycle: production
  owner: group:default/homelab-admins
  system: tf-infra-homelab

---
# Location: discovers auto-generated resources
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: tf-infra-homelab-resources
spec:
  targets:
    - ./backstage/catalog/*.yaml

Software Templates

The Backstage scaffolder templates enable self-service provisioning:

Kubernetes Template

# backstage/templates/kubernetes/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: provision-kubernetes-cluster
  title: Provision Kubernetes Cluster
  description: Create a new Talos-based Kubernetes cluster configuration on Proxmox
  tags:
    - terraform
    - kubernetes
    - talos
    - proxmox
    - homelab
spec:
  owner: group:default/homelab-admins
  type: infrastructure
  system: tf-infra-homelab

Template Parameters

The template accepts parameters for cluster configuration:

parameters:
  - title: Cluster Identity
    required:
      - name
      - environment
    properties:
      name:
        title: Cluster Name
        type: string
        pattern: "^[a-z][a-z0-9-]+$"
      environment:
        title: Environment
        type: string
        enum:
          - dev
          - staging
          - prod

  - title: Cluster Configuration
    properties:
      talos_version:
        title: Talos Version
        type: string
        default: v1.12.4
      kubernetes_version:
        title: Kubernetes Version
        type: string
        default: v1.35.0
      disable_default_cni:
        title: Disable Default CNI
        type: boolean
        default: true

  - title: Control Plane Nodes
    properties:
      cp_count:
        title: Number of Control Plane Nodes
        type: integer
        minimum: 1
        maximum: 5
        default: 3
      cp_cpu:
        title: CPU Cores per CP Node
        type: integer
        default: 4
      cp_memory:
        title: Memory per CP Node (MB)
        type: integer
        default: 8192

  - title: Worker Nodes
    properties:
      worker_count:
        title: Number of Workers
        type: integer
        default: 3
      worker_cpu:
        title: CPU Cores per Worker
        type: integer
        default: 8
      worker_memory:
        title: Memory per Worker (MB)
        type: integer
        default: 16384

Template Steps

Each template has three steps:

steps:
  - id: generate
    name: Generate Configuration
    action: fetch:template
    input:
      url: ./skeleton/kubernetes
      targetPath: configurations/kubernetes
      values:
        name: ${{ parameters.name }}
        talos_version: ${{ parameters.talos_version }}
        cp_count: ${{ parameters.cp_count }}

  - id: generate-catalog
    name: Generate Backstage Catalog Entry
    action: fetch:template
    input:
      url: ./skeleton/backstage/catalog
      targetPath: backstage/catalog

  - id: publish
    name: Open Pull Request
    action: publish:github:pull-request
    input:
      repoUrl: github.com?repo=tf-infra-homelab&owner=your-org
      title: "feat: provision Kubernetes cluster ${{ parameters.name }}"

User Flow

In Backstage, users:

Choose template — “Provision Kubernetes Cluster”
Fill parameters — name, environment, node sizes
Submit — opens a PR automatically
Review — maintainers approve the PR
Apply — Terraform provisions the cluster

  sequenceDiagram
    participant User
    participant BS as Backstage
    participant GH as GitHub
    participant TF as Terraform
    participant PVE as Proxmox
    participant Talos
    participant Flux
    
    User->>BS: Create new cluster (fill form)
    BS->>GH: Open PR with config files
    Maintainer->>GH: Review and approve PR
    GH->>TF: Merge triggers apply
    TF->>PVE: Provision VMs
    PVE->>Talos: Bootstrap cluster
    Talos->>Flux: Install GitOps

Generation Script

The full script in scripts/generate_backstage_catalog.py:

#!/usr/bin/env python3
"""Generate Backstage catalog Resource entities from configuration YAML files."""

import yaml
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent

def load_yaml(path: Path) -> dict:
    return yaml.safe_load(path.read_text()) or {}

def build_resource_entity(resource_type, environment_name, config):
    """Build a Backstage Resource entity from configuration."""
    entity = {
        "apiVersion": "backstage.io/v1alpha1",
        "kind": "Resource",
        "metadata": {
            "name": config.get("name", environment_name),
            "description": config.get("description", ""),
            "annotations": {...},
            "labels": {...},
        },
        "spec": {
            "type": RESOURCE_TYPE_META[resource_type]["backstage_type"],
            "lifecycle": "experimental",
            "owner": "group:default/homelab-admins",
            "system": "tf-infra-homelab",
        },
    }
    return entity

def main():
    for config_file in (REPO_ROOT / "configurations").rglob("*.yaml"):
        config = load_yaml(config_file)
        entity = build_resource_entity(...)
        output_file.write_text(yaml.dump(entity))

Run via Makefile:

backstage-catalog:
  python3 scripts/generate_backstage_catalog.py

Filtering in Backstage

With the generated metadata, users can filter in Backstage:

Filter	Use Case
`homelab.dev/environment=prod`	Production clusters
`homelab.dev/enabled=true`	Currently deployed
`homelab.dev/control-plane-count=3`	Full quorum
`homelab.dev/size-worker-memory>=16384`	Large workers
`homelab.dev/talos-version=v1.12.*`	Specific Talos version

What Most People Get Wrong

“Backstage is only for Kubernetes” — It catalogs anything. My LXC, VMs, Docker clusters all have Backstage entries.
“Templates replace code review” — My templates generate PRs. Human review still happens. Self-service ≠ unattended.
“Catalog must be perfect at launch” — Start simple. The YAML-to-catalog pipeline can always regenerate.

When to Use / When NOT to Use

Use Backstage	Use direct Terraform
Team self-service	Single admin
10+ resources	<5 resources
Need catalog UI	CLI is enough

What’s Next

Current areas of exploration:

More templates — VM and LXC provisioning templates
Approval workflows — notification to maintainers
Status tracking — integration with Terraform Cloud state

The Backstage integration makes infrastructure self-serviceable while maintaining code review.

High-Availability Docker Swarm on Proxmox

Fri, 10 Apr 2026 00:00:00 +0000

Why Docker Swarm (Not Kubernetes)

Kubernetes is the standard, but for 5-10 containers, it’s overkill. Docker Swarm gives you:

Service discovery with zero configuration
Built-in load balancing
Rolling updates without custom tooling
Single-node control plane if needed

The trade-off: advanced scheduling or custom CNIs need Kubernetes. For Home Assistant, Jellyfin, and WireGuard? Swarm is simpler.

Hardware constraint: My GPU passthrough works on LXC (device nodes), which is simpler than PCI passthrough on VMs. This determines the choice.

Proxmox LXC containers with device nodes bypass the need for PCI passthrough. This simplifies GPU access significantly.

Module Capabilities

The tf-module-proxmox-docker module provisions Docker containers or VMs with Docker Engine installed, optionally forming a Docker Swarm cluster:

Multi-node provisioning — creates LXC or VM nodes across host pool
Docker installation — installs Docker Engine via cloud-init
Keepalived integration — optional VIP for high availability
GPU device passthrough — passes through /dev/apex_0, /dev/dri/* for hardware acceleration
Host pool scheduling — round-robin distribution across Proxmox nodes

Quick Start

module "docker_cluster" {
  source  = "registry.example.com/namespace/tf-module-proxmox-docker/docker"
  version = "1.2.3"

  configuration = {
    cluster = {
      name = "prod-docker"
      type = "lxc"  # or "vm"
      datastore = { id = "nas", node = "alpha" }
    }

    host_pool = [
      { name = "alpha", datastore_id = "local-lvm" },
      { name = "charlie", datastore_id = "local-lvm" },
      { name = "foxtrot", datastore_id = "local-lvm" }
    ]

    worker_nodes = [
      {
        size = "medium"
        networks = { dmz = { address = "192.168.61.21/24", gateway = "192.168.61.1" } }
        vip = { state = "MASTER", priority = 100, interface = "dmz" }
      },
      {
        size = "medium"
        networks = { dmz = { address = "192.168.61.22/24", gateway = "192.168.61.1" } }
        vip = { state = "BACKUP", priority = 90, interface = "dmz" }
      }
    ]

    node_size_configuration = {
      medium = { cpu = 8, memory = 32768, os_disk = 256 }
    }

    vip = { enabled = true, address = "192.168.61.20" }
  }
}

LXC vs VM

The module supports both container and VM backends:

Aspect	LXC	VM
Resource overhead	Minimal	Full hypervisor
GPU passthrough	Device nodes	Full PCI
Nesting support	No	Yes
Use case	Simple containers	Full VMs

# LXC-based (type = "lxc")
configuration = {
  cluster = {
    type = "lxc"
  }
}

# VM-based (type = "vm")
configuration = {
  cluster = {
    type = "vm"
  }
}

The VM provisioner downloads a cloud image and imports it:

resource "proxmox_download_file" "vm_image" {
  content_type    = "iso"
  datastore_id  = var.configuration.cluster.datastore.id
  file_name    = "docker-base.iso"
  url          = var.configuration.node_os_configuration[var.configuration.cluster.type].template_image_url
}

Host Pool Scheduling

VMs are distributed across Proxmox nodes via modulo arithmetic:

# In nodes.tf
node_name = var.configuration.host_pool[
  each.key % length(var.configuration.host_pool)
].name

With 3 nodes and 3 node indices:

Node 0 → alpha (0 % 3)
Node 1 → charlie (1 % 3)
Node 2 → foxtrot (2 % 3)

This ensures even distribution across the cluster for resilience.

Keepalived HA

For high availability, Keepalived provides a floating VIP:

configuration = {
  vip = {
    enabled  = true
    address  = "192.168.61.20"
    router_id = 20
  }
}

Each node is configured with its role:

worker_nodes = [
  {
    size = "medium"
    networks = { dmz = { address = "192.168.61.21/24", gateway = "192.168.61.1" } }
    vip = { state = "MASTER", priority = 100, interface = "dmz" }
  },
  {
    size = "medium"
    networks = { dmz = { address = "192.168.61.22/24", gateway = "192.168.61.1" } }
    vip = { state = "BACKUP", priority = 90, interface = "dmz" }
  },
  {
    size = "medium"
    networks = { dmz = { address = "192.168.61.23/24", gateway = "192.168.61.1" } }
    vip = { state = "BACKUP", priority = 80, interface = "dmz" }
  }
]

The module generates Keepalived configuration:

resource "proxmox_virtual_environment_file" "keepalived_config" {
  content = <<-EOF
    vrrp_instance VI_1 {
        state ${node.vip.state}
        interface ${node.vip.interface}
        virtual_router_id ${var.configuration.vip.router_id}
        priority ${node.vip.priority}
        virtual_ipaddress {
            ${var.configuration.vip.address}
        }
    }
  EOF
}

GPU Passthrough

For hardware acceleration (e.g., transcodeing, ML workloads), device passthrough is configured in the host pool:

host_pool = [
  {
    name = "alpha"
    device_map = [
      { device = "/dev/apex_0", mode = "0666" }      # GPU
      { device = "/dev/dri/renderD128", mode = "0666" }  # iGPU
      { device = "/dev/dri/card1", mode = "0666" }
    ]
    datastore_id = "local-lvm"
  }
]

The devices are passed through to containers:

resource "proxmox_virtual_environment_container" "this" {
  # ...
  
 devices_passthrough = [
    for device in var.configuration.host_pool[each.key % length(var.configuration.host_pool)].device_map : {
      path = device.device
      mode = device.mode
    }
  ]
}

Docker Installation

Docker is installed via cloud-init:

resource "proxmox_virtual_environment_file" "cloud_config" {
  content = <<-EOF
#cloud-config
package_update: true
packages:
  - docker.io
  - docker-compose
runcmd:
  - systemctl enable docker
  - systemctl start docker
  - usermod -aG docker root
EOF
}

Or for more complex setups, custom post-install commands:

node_os_configuration = {
  debian = {
    family = "debian"
    template_image_url = "https://..."
    packages = ["docker.io", "docker-compose"]
    package_manager = {
      install_command = "apt-get install -y"
    }
    post_install_commands = [
      "systemctl enable docker",
      "usermod -aG docker root"
    ]
  }
}

Multi-Network Support

The module supports multiple network interfaces per node:

networks = {
  dmz = {
    address = "192.168.61.21/24"
    gateway = "192.168.61.1"
  }
  vmbr1 = {
    address = "192.168.192.121/25"
  }
}

This maps to:

dmz — frontend network with gateway (for public access)
vmbr1 — backend network (for inter-node communication)

Node Sizing

The node_size_configuration block keeps definitions DRY:

node_size_configuration = {
  small = {
    cpu     = 2
    memory  = 512
    os_disk = 20
  }
  medium = {
    cpu     = 8
    memory  = 32768
    os_disk = 256
  }
  large = {
    cpu     = 16
    memory  = 65536
    os_disk = 512
  }
}

My production cluster uses medium nodes (8 vCPU, 32GB RAM, 256GB disk).

Optional Tools

The module can provision additional tools:

configuration = {
  cluster = {
    options = {
      # Hawser - container management
      hawser = {
        enabled = true
        image   = "harbor.example.com/gh/finsys/hawser:latest"
      }
      
      # Newt - container log viewer  
      newt = {
        enabled = true
        image   = "harbor.example.com/dh/fosrl/newt:latest"
        endpoint = "https://newt.example.com"
      }
      
      # APT cache for faster downloads
      apt_cache = {
        enabled = true
        url     = "https://apt.example.com/"
      }
    }
  }
}

My Production Configuration

Here’s the actual production YAML configuration:

# configurations/docker/prod-docker-lxc.yaml
name: prod-docker-lxc
enabled: true

cluster:
  name: prod-docker-lxc
  type: lxc
  datastore:
    id: nas
    node: alpha

host_pool:
  - name: alpha
    device_map:
      - device: /dev/apex_0
        mode: "0666"
      - device: /dev/dri/renderD128
        mode: "0666"
      - device: /dev/dri/card1
        mode: "0666"
    datastore_id: local-lvm
  - name: charlie
    device_map:
      - device: /dev/dri/renderD128
        mode: "0666"
      - device: /dev/dri/card0
        mode: "0666"
    datastore_id: local-lvm
  - name: foxtrot
    device_map:
      - device: /dev/apex_0
        mode: "0666"
      - device: /dev/dri/renderD128
        mode: "0666"
      - device: /dev/dri/card0
        mode: "0666"
    datastore_id: local-lvm

worker_nodes:
  - size: medium
    networks:
      dmz:
        address: 192.168.61.21/24
        gateway: 192.168.61.1
      vmbr1:
        address: 192.168.192.121/24
    vip:
      state: MASTER
      priority: 100
      interface: dmz
  - size: medium
    networks:
      dmz:
        address: 192.168.61.22/24
        gateway: 192.168.61.1
      vmbr1:
        address: 192.168.192.122/24
    vip:
      state: BACKUP
      priority: 90
      interface: dmz
  - size: medium
    networks:
      dmz:
        address: 192.168.61.23/24
        gateway: 192.168.61.1
      vmbr1:
        address: 192.168.192.123/24
    vip:
      state: BACKUP
      priority: 80
      interface: dmz

node_size_configuration:
  medium:
    cpu: 8
    memory: 32768
    os_disk: 256

vip:
  enabled: true
  address: 192.168.61.20
  router_id: 20

Outputs

The module returns node credentials for access:

output "nodes_credentials" {
  value = {
    password = random_password.node_root_password.result
    ssh_key = tls_private_key.node_root_ssh_key.private_key_pem
    hawser_token = random_uuid.hawser_token.id
  }
}

output "nodes_configurations" {
  value = {
    for idx, node in proxmox_virtual_environment_container.this : idx => {
      id      = node.id
      name    = node.name
      node    = node.node
      ip      = node.ip_addresses[0]
    }
  }
}

Credentials are automatically stored in Bitwarden:

resource "bitwarden-secrets_secret" "docker_nodes_password" {
  key   = "${local.cluster_name}-nodes_password"
  value = module.docker[0].nodes_credentials.password.result
}

resource "bitwarden-secrets_secret" "docker_nodes_ssh_key" {
  key   = "${local.cluster_name}-nodes_ssh_key"
  value = module.docker[0].nodes_credentials.ssh_key.private_key_pem
}

Use Cases

This cluster handles workloads like:

Home Assistant — Docker Compose-based home automation
Media services — Plex, Jellyfin with GPU transcoding
VPN services — WireGuard, OpenVPN
CI runners — GitHub Actions self-hosted runners

The hardware acceleration via GPU passthrough is critical for media workloads.

What Most People Get Wrong

“Docker Swarm is dead” — It’s not Kubernetes, but for 10-container workloads, it’s simpler. No RBAC complexity, no CNI headaches.
GPU passthrough works on LXC — Most guides assume PCI passthrough (VMs). With device nodes (/dev/apex_0, /dev/dri/*), LXC containers access GPUs directly.
Keepalived needs 3 nodes for quorum — Two nodes work fine with nopreempt on the master. The backup only takes over if master fails.

When to Use / When NOT to Use

Use Docker Swarm	Use Kubernetes
3-15 containers	50+ containers
Simple networking	Custom CNI required
Single admin	Team with RBAC needs
GPU passthrough via LXC	GPU operators

What’s Next

Current areas of exploration:

GPU scheduling — Kubernetes-style GPU scheduling for Docker
Portainer integration — management UI for Docker
Observability — centralized logging with Loki

Talos Kubernetes on Proxmox

Sat, 28 Mar 2026 00:00:00 +0000

Why Talos

Kubernetes the hard way (kubeadm) requires 15+ steps and manual certificate management. Talos gives you a declarative cluster that manages its own certificates, API server rotation, and upgrades — all through a single machine config.

The trade-off: Talos is opinionated. You don’t get a traditional kubelet. But for infrastructure that should just work, this is a feature.

Air-gapped requirement: My homelab can’t reach public registries. Every container pull route redirects through my Harbor mirror. Talos’s registry mirror config makes this seamless.

Talos automatically rotates certificates before they expire. No manual intervention needed for cluster certificate management.

Module Capabilities

The tf-module-proxmox-talos module provisions a complete Talos-based Kubernetes cluster on Proxmox VE in a single Terraform apply:

Talos Image Factory — generates custom ISOs with specific extensions
Machine Configuration — generates Talos machine configs with networking
ISO Upload — downloads and uploads to Proxmox datastore
Node Provisioning — provisions control plane and worker VMs across host pool
Cluster Bootstrap — applies machine configs and bootstraps Kubernetes
Day-0 GitOps — optionally installs Flux or Argo CD during bootstrap
Registry Mirrors — configures container registry redirects

Quick Start

module "talos_cluster" {
  source  = "registry.example.com/namespace/tf-module-proxmox-talos/talos"
  version = "1.2.1"

  configuration = {
    cluster = {
      name = "prod-k8s"
      datastore = { id = "nas", node = "alpha" }
      talos = { version = "v1.12.4" }
      kubernetes_version = "v1.35.0"
    }

    host_pool = {
      alpha = { datastore_id = "local-lvm" }
      charlie = { datastore_id = "local-lvm" }
      foxtrot = { datastore_id = "local-lvm" }
    }

    control_plane_nodes = {
      nodes = [
        { size = "control_plane", networks = { dmz = { address = "192.168.62.21/24", gateway = "192.168.62.1" } } }
      ]
      host_pool = ["alpha", "charlie", "foxtrot"]
      vip = { enabled = true, address = "192.168.62.20" }
    }

    worker_nodes = {
      nodes = [
        { size = "worker", networks = { dmz = { address = "192.168.62.24/24", gateway = "192.168.62.1" } } }
      ]
      host_pool = ["alpha", "charlie", "foxtrot"]
    }

    node_size_configuration = {
      control_plane = { cpu = 4, memory = 8192, os_disk = 128 }
      worker = { cpu = 10, memory = 49152, os_disk = 128, data_disk = 512 }
    }
  }
}

Talos Image Factory

The module uses Talos’s image factory to generate custom ISOs with specific extensions:

# image.tf
resource "talos_image_factory_schematic" "this" {
  schematic = yamlencode({
    customization = {
      systemExtensions = {
        officialExtensions = data.talos_image_factory_extensions_versions.this.extensions_info[*].name
      }
    }
  })
}

The extensions are defined in locals:

locals {
  image = {
    platform = "nocloud"
    customizations = {
      base = [
        "lldp",           # Network topology discovery
        "qemu-guest-agent",  # Proxmox agent integration
        "util-linux-tools",   # Core utilities
        "iscsi-tools",       # NFS storage
        "nfs-utils"        # NFS mounting
      ]
    }
  }
}

The generated schematic ID is used to construct the ISO URL:

resource "proxmox_download_file" "talos_iso" {
  file_name = "talos-${var.configuration.cluster.name}-${var.configuration.cluster.talos.version}-${data.talos_image_factory_urls.this.schematic_id}.iso"
  url      = var.configuration.cluster.talos.iso_mirror != null
    ? replace(data.talos_image_factory_urls.this.urls.iso, "https://", var.configuration.cluster.talos.iso_mirror)
    : data.talos_image_factory_urls.this.urls.iso
}

This allows using mirror registries for air-gapped environments.

Machine Configuration

Talos machine configuration is generated through the Talos provider:

data "talos_machine_configuration" "configurations" {
  cluster_name     = var.configuration.cluster.name
  cluster_version = var.configuration.cluster.talos.version
  
  # Control plane specific config
  machine_type = "controlplane"
  
  # Network configuration
  network = {
    interfaces = [
      for idx, network in var.configuration.control_plane_nodes.nodes[0].networks : {
        interface = keys(network.networks)[0]
       DHCP    = false
        addresses = [values(network.networks)[0].address]
      }
    ]
  }
  
  # Kubernetes configuration  
  kubernetes = {
    version = var.configuration.cluster.kubernetes_version
  }
}

The configuration supports:

Multiple network interfaces per node
Registry mirrors for all major registries
Custom CNI (Cilium) configuration
kube-proxy disable

Registry Mirrors

A key feature is container registry mirror configuration:

configuration = {
  cluster = {
    registry_mirrors = {
      "ghcr.io" = {
        endpoints = ["https://harbor.example.com/v2/gh"]
        override_path = true
      }
      "registry.k8s.io" = {
        endpoints = ["https://harbor.example.com/v2/k8s"]
        override_path = true
      }
      "docker.io" = {
        endpoints = ["https://harbor.example.com/v2/dh"]
        override_path = true
      }
      "quay.io" = {
        endpoints = ["https://harbor.example.com/v2/qi"]
        override_path = true
      }
      "factory.talos.dev" = {
        endpoints = ["https://harbor.example.com/v2/talos"]
        override_path = true
      }
    }
  }
}

All container pulls route through my Harbor registry — essential for air-gapped homelabs.

Multi-Network Support

The module provisions VMs with multiple network interfaces:

network_devices = [
  for network_name, network in each.value.networks : {
    name    = network_name
    enabled = true
    bridge  = network_name
    ipv4 = {
      address = network.address
      gateway = network.gateway
    }
  }
]

My production setup uses:

dmz — frontend network with gateway (192.168.62.0/24)
vmbr1 — backend network for inter-node communication (192.168.192.0/24)

Cluster Bootstrap

The bootstrap sequence is orchestrated by Terraform:

# 1. Generate machine secrets
resource "talos_machine_secrets" "this" {}

# 2. Apply control plane configuration
resource "talos_machine_configuration_apply" "controlplane" {
  for_each = { for idx, node in var.configuration.control_plane_nodes.nodes : idx => node }
  
  node =  module.control_plane_virtual_machine[each.key].virtual_machine.id
  config = data.talos_machine_configuration.configurations[each.key].machine_config
  secrets = talos_machine_secrets.this.secrets
}

# 3. Bootstrap the cluster
resource "talos_machine_bootstrap" "this" {
  node = var.configuration.control_plane_nodes.nodes[0].name
  config = data.talos_machine_configuration.configurations[0].machine_config
  secrets = talos_machine_secrets.this.secrets
}

GitOps Bootstrap

One of the most powerful features — Flux or ArgoCD can be bootstrapped during cluster creation:

configuration = {
  cluster = {
    gitops = {
      provider      = "flux"  # or "argocd"
      namespace     = "flux-system"
      chart_version = "2.18.2"
      
      bootstrap = {
        repo_url              = "https://github.com/your-org/applications.git"
        revision              = "main"
        path                  = "src/k8s/prod"
        destination_namespace = "homelab"
      }
    }
  }
}

This does:

Installs Flux during Talos bootstrap (via inline manifest)
Configures it to sync from the applications-homelab repository
The cluster starts deploying apps immediately after boot

  sequenceDiagram
    participant TF as Terraform
    participant Talos as Talos
    participant Flux as Flux
    participant GH as GitHub
    participant K8s as Kubernetes
    
    TF->>Talos: Apply machine config
    Talos->>Talos: Bootstrap control plane
    Talos->>Flux: Install Flux CRDs
    Flux->>GH: Clone applications-homelab
    GH-->>Flux: Return repo contents
    Flux->>K8s: Deploy applications

Cilium Integration

For advanced networking, the default CNI can be replaced with bundled Cilium:

configuration = {
  cluster = {
    # Disable Talos-managed CNI
    options = {
      disable_default_cni = true
      disable_kube_proxy = true
    }
    
    # Configure Cilium via helm values
    helm_values_override = {
      cilium = {
        operator = { replicas = 1 }
      }
    }
  }
}

The module uses the Helm provider to template the Cilium manifest:

data "helm_template" "cilium" {
  name      = "cilium"
  repo      = "https://cilium.github.io/cilium"
  chart     = "cilium"
  version   = var.configuration.cluster.talos.version
  namespace = "cilium"
  values    = [var.configuration.cluster.helm_values_override]
}

Node Sizing

The node_size_configuration block keeps definitions DRY:

node_size_configuration = {
  control_plane = {
    cpu     = 4
    memory  = 8192   # MB
    os_disk = 128     # GB
  }
  worker = {
    cpu      = 10
    memory  = 49152  # MB
    os_disk = 128
    data_disk = 512  # Extra data disk for PVs
  }
}

My prod-k8s cluster:

3 control plane nodes: 4 vCPU, 8GB RAM, 128GB disk
3 worker nodes: 10 vCPU, 48GB RAM, 128GB OS + 512GB data

Host Pool Scheduling

VMs are distributed across Proxmox nodes via modulo arithmetic:

# In nodes.tf
node_name = var.configuration.control_plane_nodes.host_pool[
  each.key % length(var.configuration.control_plane_nodes.host_pool)
]

With 3 nodes and 6 worker indices:

Worker 0 → alpha (0 % 3)
Worker 1 → charlie (1 % 3)
Worker 2 → foxtrot (2 % 3)
Worker 3 → alpha (3 % 3)
Worker 4 → charlie (4 % 3)
Worker 5 → foxtrot (5 % 3)

This ensures even distribution across the cluster.

Outputs

The module returns cluster credentials for external use:

output "cluster_credentials" {
  value = {
    kubeconfig    = talos_cluster_kubeconfig.this.kubeconfig
    talosconfig = talos_client_configuration.this.talosconfig
    
    # Kubeconfig file is also written locally when debug = true
    talosconfig_path = local.talosconfig_path
    kubeconfig_path = local.kubeconfig_path
  }
}

Credentials are automatically stored in Bitwarden:

resource "bitwarden-secrets_secret" "kubernetes_kubeconfig" {
  key   = "${local.cluster_name}-kubeconfig"
  value = module.kubernetes[0].cluster_credentials.kubeconfig
}

resource "bitwarden-secrets_secret" "kubernetes_talosconfig" {
  key   = "${local.cluster_name}-talosconfig"
  value = module.kubernetes[0].cluster_credentials.talosconfig
}

My Production Configuration

Here’s the actual production YAML configuration:

# configurations/kubernetes/prod-k8s.yaml
cluster:
  name: prod-k8s
  datastore:
    id: nas
    node: alpha
  talos:
    version: v1.12.4
    installer_mirror: harbor.example.com/talos
    iso_mirror: https://proxy.example.com/
  kubernetes_version: v1.35.0
  registry_mirrors:
    ghcr.io: { endpoints: [https://harbor.example.com/v2/gh], override_path: true }
    registry.k8s.io: { endpoints: [https://harbor.example.com/v2/k8s], override_path: true }
    docker.io: { endpoints: [https://harbor.example.com/v2/dh], override_path: true }
    quay.io: { endpoints: [https://harbor.example.com/v2/qi], override_path: true }
    factory.talos.dev: { endpoints: [https://harbor.example.com/v2/talos], override_path: true }
  options:
    disable_default_cni: true
    disable_kube_proxy: true
    disable_scheduling_on_control_plane: true
  gitops:
    provider: flux
    bootstrap:
      repo_url: https://github.com/your-org/applications.git
      path: src/k8s/prod
      destination_namespace: homelab

host_pool:
  alpha: { datastore_id: local-lvm }
  charlie: { datastore_id: local-lvm }
  foxtrot: { datastore_id: local-lvm }

control_plane_nodes:
  nodes: [...]  # 3 control planes
  host_pool: [alpha, charlie, foxtrot]
  vip: { enabled: true, address: 192.168.62.20 }

worker_nodes:
  nodes: [...]  # 3 workers
  host_pool: [alpha, charlie, foxtrot]

node_size_configuration:
  control_plane: { cpu: 4, memory: 8192, os_disk: 128 }
  worker: { cpu: 10, memory: 49152, os_disk: 128, data_disk: 512 }

What’s Next

Current areas of exploration:

Multi-cluster federation — connecting Talos clusters for workload distribution
Nested Talos — running Talos inside Proxmox for testing
Observability — centralized logging with Loki and Grafana

What Most People Get Wrong

“Talos upgrades break clusters” — With proper machine configs and registry mirrors, upgrades are rolling. The immutability is a feature, not a bug.
“Air-gapped is impossible” — Talos’ registry mirror config + image factory handles this. Your nodes don’t need public internet access.
“No kubelet means no logging” — Talos has built-in talosctl logs and talosctl metrics. It’s different from Kubernetes logging, not less capable.

When to Use / When NOT to Use

Use Talos	Stick with kubeadm
Want declarative infrastructure	Need full kubelet control
Air-gapped environments	Custom init systems required
Single apply to cluster	Manual certificate management needed

Use Talos

Use Talos	Stick with kubeadm
Want declarative infrastructure	Need full kubelet control
Air-gapped environments	Custom init systems required
Single apply to cluster	Manual certificate management needed

The foundation is solid — every cluster can be versioned, reviewed, and rolled back.

Terraform-Driven Homelab Architecture

Sun, 15 Mar 2026 00:00:00 +0000

The Problem Space

Homelabs evolve. You start with one Docker container, add some LXCs, then Kubernetes, and suddenly your infrastructure is a house of cards held together by scripts you wrote two years ago and don’t remember.

This architecture solves that through:

Everything in code — from VM provisioning to Kubernetes bootstrap
Versioned modules — each update is a code review opportunity
Self-service via Backstage — templated provisioning, no Slack threads

Numbers: 3 Proxmox nodes, 2 production clusters (Docker Swarm + Talos K8s), ~50 resources defined across 24+ YAML configurations.

Running in production:

3 Proxmox nodes (alpha, charlie, foxtrot)
Docker Swarm clusters with Keepalived HA
Talos Kubernetes clusters with Flux GitOps
GPU passthrough for hardware acceleration
Multi-network topology (dmz + vmbr1)
Private container registry (Harbor)
Private Terraform registry (Cloudflare Workers)

Start with the basic template. All custom modules derive from it — maintaining consistency across the infrastructure.

Module Hierarchy

  graph TB
    subgraph "Root Module"
        A[tf-infra-homelab]
    end
    
    subgraph "Compute Modules"
        B[tf-module-proxmox-lxc]
        C[tf-module-proxmox-vm]
        D[tf-module-proxmox-talos]
        E[tf-module-proxmox-docker]
    end
    
    subgraph "Application Layer"
        F[applications-homelab]
    end
    
    subgraph "Platform"
        G[Proxmox VE]
    end
    
    A --> B
    A --> C
    A --> D
    A --> E
    D --> F
    E --> F
    B --> G
    C --> G
    D --> G
    E --> G

Module	Purpose
terraform-basic-template	Foundation for all modules
tf-module-proxmox-lxc	LXC container provisioning
tf-module-proxmox-vm	Full VM provisioning
tf-module-proxmox-docker	Docker Swarm clusters
tf-module-proxmox-talos	Talos Kubernetes clusters
tf-infra-homelab	Root orchestration
applications-homelab	Kustomize deployments
github-management-plane	GitHub org management

The Dependency Graph

  graph TB
    T[terraform-basic-template]
    L[tf-module-proxmox-lxc]
    V[tf-module-proxmox-vm]
    DT[tf-module-proxmox-docker]
    TT[tf-module-proxmox-talos]
    RH[tf-infra-homelab]
    AH[applications-homelab]
    P[ProxmoxVE]
    
    T --> L
    T --> V
    L --> DT
    V --> DT
    L --> TT
    V --> TT
    DT --> RH
    TT --> RH
    RH --> P
    DT --> AH
    TT --> AH

Key observations:

Template is foundational — all modules derive from the same template
LXC and VM are leaf modules — no dependencies on other custom modules
Docker and Talos are composite — build on LXC/VM modules
Root module is orchestrational — composes modules based on configurations
Applications deploy post-provisioning — GitOps ties into Docker/Talos clusters

Configuration-Driven

All infrastructure is defined in YAML configurations, not ad-hoc Terraform runs:

configurations/
├── docker/
│   ├── dev-docker-lxc.yaml
│   └── prod-docker-lxc.yaml
├── kubernetes/
│   ├── dev-k8s.yaml
│   └── prod-k8s.yaml
└── virtual_machine/
    └── ...

Each config has an enabled flag for gradual rollout:

name: prod-k8s
enabled: true  # Set to false to disable without deletion

cluster:
  name: prod-k8s
  datastore:
    id: nas
    node: alpha

What’s Running

Cluster	Type	Nodes	VIP	Purpose
prod-docker-lxc	Docker Swarm	3x medium (8vCPU/32GB)	192.168.61.20	Container workloads
prod-k8s	Talos K8s	3x CP (4vCPU/8GB) + 3x worker (10vCPU/48GB)	192.168.62.20	Kubernetes workloads

Both clusters span all 3 Proxmox nodes for high availability.

Design Principles

This architecture follows specific principles:

Principle	Implementation
Single configuration object	All modules use unified `configuration` input
Host pools	Resilience through multi-node distribution
Versioned modules	Each module has explicit versions
YAML configurations	Infrastructure as data, not ad-hoc apply
Private registry	Distribution without Terraform Cloud cost
Secrets integration	Bitwarden for credential storage
GitOps	Flux bootstrapped during cluster creation
Multi-network	Separate DMZ and backend networks
GPU passthrough	Device mapping in host pool

What Most People Get Wrong

“More modules = better architecture” — I started with 10+ modules. Consolidated to 5. Over-modularization creates maintenance overhead.
“YAML = Terraform” — Terraform is the engine, YAML is the fuel. Don’t embed YAML in .tf files; load from external files.
“GitOps replaces Terraform” — They work together: Terraform provisions, Flux manages apps. Both are declarative.

Each component has its own detailed post:

Post	Focus
Talos Kubernetes on Proxmox	tf-module-proxmox-talos deep dive — image factory, machine config, bootstrap
Docker Swarm on Proxmox	tf-module-proxmox-docker deep dive — Keepalived HA, provisioning
LXC & VM Modules	tf-module-proxmox-lxc + tf-module-proxmox-vm basics
Backstage Integration	Catalog generation, software templates
Private Terraform Registry	Module distribution via Cloudflare Workers
GitHub Management Plane	Managing GitHub org via Terraform