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,
• 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.

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.

Usage

Documentation

• Module Technical Documentation
• Input Variables Documentation

Example

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

If you think a feature is worth being implemented inside this terraform/tofu module, feel free starting a community discussion. You can also look for existing feature requests created in the issue tracker which is governed by the author's homelab project.

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.