🚧Work in Progress🚧: This project is currently under development and is not yet complete. Features, configurations, and documentation may change frequently as work continues. Feedback and suggestions are welcome, but please be aware that the repository may not yet be fully functional or stable.
This repository offers an easy-to-use and customizable solution for setting up a Kubernetes cluster in a Proxmox VE home lab environment.
Key Features:
- Automated Provisioning: Streamlines cluster setup by leveraging OpenTofu to automate the deployment and configuration of Talos Linux nodes.
- Advanced Network Security and Observability: Utilizes Cilium to enforce fine-grained network policies and provide robust observability within the Kubernetes cluster.
- Secure Secret Management: Protects sensitive Kubernetes secrets with Sealed Secrets, ensuring secure encryption and storage in Git.
- GitOps-Driven Workflow: Implements ArgoCD for automated continuous delivery, maintaining alignment between application deploy 8000 ments and the desired state defined in Git repositories.
- Infrastructure as Code (IaC): Adheres to IaC best practices, ensuring infrastructure configurations are reproducible, version-controlled, and easy to manage.
- Hardened Kubernetes Environment: Delivers a secure and reliable cluster through the integration of GitOps practices, automated provisioning, Cilium network policies, Kyverno Policies and Sealed Secrets.
This project provides a streamlined and reproducible way to deploy Talos Kubernetes clusters on Proxmox VE using OpenTofu and GitOps with ArgoCD.
Make sure the following tools are installed:
- Proxmox VE server(s)
- OpenTofu CLI [
brew install opentofu] - talosctl CLI [
brew install siderolabs/tap/talosctl] - kubectl CLI [
brew install kubernetes-cli] - k9s [
brew install k9s] (optional but recommended) - ArgoCD CLI [
brew install argocd] (optional, for GitOps workflows)
git clone https://github.com/erwinkersten/homelab.git
cd homelab/infrastructure/kubernetesEvery Talos release supports a specific set of Kubernetes versions. Setting a mismatched kubernetes_version in environment.prod.tfvars will cause the machine config apply to fail.
Check the official support matrix before filling in the versions: https://docs.siderolabs.com/talos/latest/getting-started/support-matrix
Quick reference for the latest Talos releases (November 2026):
| Talos version | Supported Kubernetes versions |
|---|---|
| v1.14.x | 1.33 – 1.37 |
| v1.13.x | 1.31 – 1.36 |
| v1.12.x | 1.30 – 1.35 |
Always verify against the official matrix — the table above may lag behind the latest releases. Each version's page lists only that release and the one before it; replace
latestin the URL with a version such asv1.13for older releases.
Set the versions in environment.prod.tfvars:
cluster = {
talos_version = "v1.14.5" # Talos version the nodes run; needs an entry in images.prod.tfvars
kubernetes_version = "1.36.4" # must be in the supported range above
talos_config_version = "v1.13.3" # machine configuration format OpenTofu generates; stays pinned
...
}There are two Talos versions on purpose:
| Setting | Meaning | When it changes |
|---|---|---|
talos_version |
The Talos version the nodes run. tofu-images.sh must have downloaded its image, and image.file_id points at that image. |
After every Talos upgrade. |
talos_config_version |
The Talos version whose machine configuration format OpenTofu generates, also called the version contract. Nodes accept configuration in an older format. | Rarely, and only on purpose after reviewing the plan. It must not be newer than talos_version. |
From Talos v1.14 the generated configuration uses a new multi-document format. The patches in talos/machine-config/ still use the older v1alpha1 layout, so keep talos_config_version at v1.13.x or lower until they are migrated. With a v1.14 format the plan rewrites every node's configuration and, for example, adds a Flannel CNI section next to Cilium. The Talos Terraform provider documentation also recommends keeping the contract pinned to the version the cluster was created with.
Copy and edit the environment and image configuration files:
cp environment.prod.tfvars.example environment.prod.tfvars
cp images/images.tfvars.example images.prod.tfvarsEdit both files to match your Proxmox setup, node IPs, storage names, Talos version, and Kubernetes version.
The config/{env}/ directory holds runtime files (kubeconfig, talos config, certificates). It is gitignored and must be set up after every fresh clone. Run:
./setup-config.sh prodThis creates config/prod/certificates/ and generates the RSA key pair used by Sealed Secrets. The script is idempotent — it skips generation if the certificates already exist.
The certificates are read by OpenTofu during the plan phase, so this step must complete before running
tofu-deploy.sh.tofu-deploy.shcallssetup-config.shautomatically, but you can also run it standalone.
See config/README.md for a full description of what lives in the config directory and how to seal secrets with kubeseal.
Each secret has a corresponding *.yaml_encrypt.example file committed alongside it. Copy each example to a _encrypt file (gitignored) and fill in your real values:
# Example for the Cloudflare API token:
cp kubernetes/core/controllers/cert-manager/cloudflare-api-token-sealed.yaml_encrypt.example \
kubernetes/core/controllers/cert-manager/cloudflare-api-token-sealed.yaml_encryptEdit each _encrypt file and replace the <INSERT: ...> placeholders with the real secret values.
Seal the secrets (requires a running cluster with Sealed Secrets installed):
export KUBECONFIG="$(pwd)/config/prod/kube-config.yaml"
cd hack && ./generate-sealed-secrets.shThe sealed output files can be committed to git — they are encrypted with the cluster's public key.
Re-run
generate-sealed-secrets.shany time you change a secret value or after rotating the Sealed Secrets keypair.
Image management is decoupled from cluster provisioning. Run this script once per new Talos version — it uploads the image to Proxmox and only re-downloads if the version is new:
./tofu-images.sh prodThe script prints the file_id and installer_image values for each image. Copy the file_id into environment.prod.tfvars under the image block:
image = {
file_id = "data:iso/talos-<schematic-id>-v1.12.8-nocloud-amd64.img"
}./tofu-deploy.sh prodThis single command does everything in sequence:
- Provisions Talos VMs on Proxmox and bootstraps the Kubernetes cluster
- Installs the initial Cilium CNI (needed for the cluster health check to pass)
- Creates Sealed Secrets bootstrap keys and Proxmox CSI credentials in Kubernetes
- Runs
kubernetes/core/deploy-core.shwhich installs the full component stack:- Gateway API CRDs
- Cilium (full config with L2 announcements and IP pool)
- Gateway API resources
- ArgoCD
- Cert-manager
- Sealed Secrets controller
- Proxmox CSI plugin
⚠️ One-time manual step: after the cluster is ready, hand control to ArgoCD's App-of-Apps pattern.
export KUBECONFIG="$(pwd)/../../config/prod/kube-config.yaml"
kubectl apply -k kubernetes/argo-apps/From this point ArgoCD manages all infrastructure and application deployments from Git. The deploy-core.sh step is only needed on a fresh cluster — on subsequent changes, GitOps handles reconciliation.
Upgrades run with talos-upgrade.sh. It reads the nodes, their roles and addresses, and the target versions from environment.<env>.tfvars, and upgrades one node at a time:
- Pre-flight. Checks that every node in the tfvars is reachable, Ready, and has the expected hostname and address, that the cluster has no nodes missing from the tfvars, and that
talosctl healthpasses. It refuses targets that skip a minor version, downgrades, and an installer image that does not match the nodes' platform. - Talos. Control plane nodes first, then workers. Before each node it asks for approval and checks cluster health. After each node it checks the Talos version, platform, hostname, address, Ready state and cluster health, and stops at the first failure.
- Kubernetes. Runs
talosctl upgrade-k8s --dry-runas a pre-check, then upgrades the control plane components on each control plane node, then the kubelet on each node, control planes first. Each node needs approval. Finally it offers to runtalosctl upgrade-k8sto sync the bootstrap manifests.
The Talos API endpoint and Kubernetes API server used for each step are always a control plane node other than the one being upgraded, so the checks keep working while that node reboots.
Rules the script cannot check for you:
- Use the platform-specific installer. The VMs run the
nocloudplatform, so the installer must befactory.talos.dev/nocloud-installer/.... The genericfactory.talos.dev/installer/...is for bare metal: a node upgraded with it ignores the Proxmox cloud-init data and comes back with a DHCP address and a generated hostname.tofu-images.shprints the correct installer, and the script refuses one that does not match the node's platform. - Do not touch
cluster.talos_config_versionduring an upgrade. It sets the machine configuration format, not the running version (see Choose Talos and Kubernetes Versions). The script refuses to run when it is newer than a node's Talos version. - Do not copy versions from the example blindly.
environment.prod.tfvars.examplecarries Renovate's latesttalos_versionandkubernetes_version; an existing cluster's tfvars must describe what its nodes run. - Check Kubernetes support for the target Talos version in the support matrix. Upgrade Talos first when the current Talos release does not support the Kubernetes version you want.
- Avoid the nightly backup window between 00:00 and 01:00 UTC. The script warns when you start it then.
- GitHub releases — full changelog and release notes: https://github.com/siderolabs/talos/releases
- Talos Image Factory — browse versions, select system extensions, and preview the schematic ID that will be generated from your
talos/image/schematic.yaml: https://factory.talos.dev
The schematic ID is derived automatically from talos/image/schematic.yaml when you run tofu-images.sh. If you change the extensions in that file, a new schematic ID is computed and a new image is downloaded on the next run.
Only skip this step for a Kubernetes-only upgrade. images.prod.tfvars is git-ignored, so Renovate cannot bump it. Add the next minor version and keep the current one:
images = {
"v1-13-3" = { # current version, keep until all nodes are upgraded
version = "v1.13.3"
proxmox_nodes = ["pve-01"]
proxmox_iso_ds = "data"
}
"v1-14-5" = { # target version (next minor only)
version = "v1.14.5"
proxmox_nodes = ["pve-01"]
proxmox_iso_ds = "data"
}
}./tofu-images.sh prodCopy the printed values for the target version into the image block. Leave file_id and cluster.talos_version on the current version for now:
image = {
file_id = "data:iso/talos-<schematic-id>-v1.13.3-nocloud-amd64.img" # current image (unchanged)
update_file_id = "data:iso/talos-<schematic-id>-v1.14.5-nocloud-amd64.img" # new image
installer_image = "factory.talos.dev/nocloud-installer/<schematic-id>:v1.14.5" # target Talos version
}For a Kubernetes upgrade, set cluster.kubernetes_version to the next minor version. Leave it unchanged to skip the Kubernetes upgrade, and leave installer_image at null to skip the Talos upgrade.
./talos-upgrade.sh prod --checkThis runs all pre-flight checks and prints the current and target version of every node, without changing anything.
./talos-upgrade.sh prodAnswer y to upgrade a node, s to skip it, or q to stop. Talos drains each node before it reboots. Wait for the script to report the node healthy before approving the next one. The script refuses to upgrade any kubelet while a control plane node still runs the old API server version.
When the script has finished, it prints what to change:
- In
environment.prod.tfvars, setcluster.talos_versionto the new version, setimage.file_idto the new image, and setupdate_file_idandinstaller_imageback tonull. Leavecluster.talos_config_versionunchanged. - Remove the old version from
images.prod.tfvarsand remove its image from Proxmox:./tofu-images.sh prod
- Review the plan before applying it. After a Kubernetes upgrade it should only change the image tags the script already patched onto the nodes. Stop if it changes anything else.
talos_versiondoes not affect the generated configuration; onlytalos_config_versiondoes. Changingtalos_config_versionnever touches the machine secrets, becausetalos/config.tofuignores that field ontalos_machine_secrets, but it does change the configuration of every node.tofu plan -var-file=environment.prod.tfvars ./tofu-deploy.sh prod
About
update = true: the nodes block still supportsupdate = true, which upgrades Talos throughtalos/scripts/upgrade-node.shduringtofu-deploy.sh. That path runs with-parallelism=2and does not wait between nodes of the same type, and it also applies all other pending machine configuration changes. Prefertalos-upgrade.sh.
./tofu-destroy.sh prodThe script will ask whether to override the prevent_destroy guard on VMs. Answer yes to proceed with a full teardown. The override is automatically removed after a successful destroy.
infrastructure/kubernetes/
├── images/ # Talos image download module (independent state)
│ ├── main.tofu
│ ├── variables.tofu
│ ├── outputs.tofu
│ └── images.tfvars.example
├── talos/ # Talos cluster provisioning module
│ ├── image.tofu # Node-to-image mapping
│ ├── virtual_machines.tofu # Proxmox VM resources
│ ├── config.tofu # Machine config, bootstrap, upgrades
│ ├── machine-config/ # Control plane and worker config templates
│ ├── inline-manifests/ # Cilium installation manifests
│ └── scripts/
│ └── upgrade-node.sh # Called by OpenTofu for nodes with update = true
├── bootstrap/
│ ├── sealed-secrets/ # Pre-generated encryption keys
│ ├── proxmox-csi-plugin/ # Proxmox CSI role, user, token, and K8s secret
│ └── argocd/ # ArgoCD Helm release
├── tofu-images.sh # Download Talos images to Proxmox
├── talos-upgrade.sh # Upgrade Talos and Kubernetes node by node
├── tofu-deploy.sh # Create or update the cluster
├── tofu-destroy.sh # Destroy the cluster
└── tofu-import-skip-health.sh # Import existing VMs into Terraform state
kubernetes/
├── core/ # Talos bootstrapping components (CRs, secrets, etc.)
├── argo-apps/ # ArgoCD App-of-Apps configuration
├── infra/ # Cluster-wide infrastructure (e.g. ingress, certs)
└── apps/ # Application workloads and services
Contains the base components needed to initialize the Talos cluster.
Defines the ArgoCD App-of-Apps hierarchy. Entry point for GitOps bootstrapping.
Infrastructure resources deployed via ArgoCD: networking, storage, and other cluster-wide components.
Application workloads deployed via ArgoCD. Each application has its own directory with manifests and configuration.
- Proxmox VE: https://www.proxmox.com/en/
- Talos Linux: https://www.talos.dev/
- OpenTofu: https://opentofu.org/
- Kubernetes: https://kubernetes.io/
- ArgoCD: https://argo-cd.readthedocs.io/
- Cilium: https://cilium.io/
- CertManager: https://cert-manager.io/
- Sealed Secrets: https://github.com/bitnami-labs/sealed-secrets