About

A terraform/tofu module for creating a Kubernetes cluster on Proxmox VE, using Talos Linux as the governing declarative K8S OS.

What's in the pocket

You will get:

• Kubernetes cluster based on
• Talos Linux (a secure, immutable, and minimal distribution, explecitely designed for K8S) with
• Cilium as a CNI and IngressController,
• Gateway API as next-generation Kubernetes Ingress,
• Proxmox CSI Plugin for providing storage,
• Sealed Secrets providing a safe store for your Secrets – even inside a public repository –,
• all running as QEMU/KVM VMs on Proxmox VE.

Everything is set up with a simple terragrunt apply command.

Usage

For seeing an example usage of the module, please be referred to the author's implementation of the module in isejalab/homelab. You will see this module being used in a multi-environment (e.g. dev, qa, prod), not only leveraging Terragrunt as a DRY-style wrapper for terraform/tofu. Copious amounts of YAML using kustomize and its transformer, patches and components features will provide more DRY capabilities.

Roadmap and more features

This module is designed for being minimalistic by bootstrapping a Kubernetes cluster with core intrastructure CNI, CSI and Secrets. Of course, you can add more Kubernetes features, e.g. Argo CD and Cert-manager, by defining kustomize YAML code on-top.

If you think a feature is worth being implemented inside this terraform/tofu module, feel free starting a community discussion.

Requirements

1. Required: You need to have one or more Proxmox nodes to run the VMs on. A Proxmox cluster is required in the case of multiple nodes.

2. Free Choice: The module is tested to running well with OpenTofu, while it should be compatible with Terraform as well.

3. Recommended: It's recommended using Terragrunt as a wrapper when aiming for multiple incarnations of the module. Plain terraform/tofu calling without using terragrunt as a wrapper should also work.

4. Recommended: It's recommended using SOPS for encrypting your Terraform credentials (e.g. Proxmox login). This allows storing all your Terraform configuration in version control.

5. Recommended: For daily operations of the cluster you should have K8S CLI tools such als kubectl, kustomize, cilium, and kubeseal.

6. Optional: You could have CLI tool talosctl for checking your Talos cluster. It's not really needed because even upgrades are done using declarative IaC – in a good and bad manner (see siderolabs/terraform-provider-talos#140).

   Upgrades are handled setting the nodes.[].update variable to true, subsequently for all nodes.

Credits

This module would not exist without Vegard Stenhjem Hagen's excellent work on his @vehagn/homelab/tofu/kubernets implementation. Besides variables and releases/tags, some other small changes got added, making this terraform module more usable in different environments. See the Changelog for a full list of changes. And don't miss out checking Vegard's helpful blog, where he's giving brilliant explainations on Kubernetes topics, and of course his homelab implementation.