# leandrosalvas/opentofu-proxmox-kubernetes architecture

> Architecture diagram of the GitHub repository leandrosalvas/opentofu-proxmox-kubernetes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leandrosalvas/opentofu-proxmox-kubernetes
- Repository: https://github.com/leandrosalvas/opentofu-proxmox-kubernetes

## Overview

This repository is OpenTofu infrastructure-as-code for provisioning a Talos-based Kubernetes cluster on Proxmox VE. The main workflow builds VM images and control-plane/worker VMs, bootstraps Talos, installs Cilium, then hands worker lifecycle to Cluster API; it also configures NFS-backed dynamic storage. The README maps these phases to the modules, but no source excerpts were provided, so relationships below are limited to those documented there. The dashboard module is present in the tree, though its behavior is not described in the README.

Main entry points: [`main.tf`](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/main.tf) (OpenTofu Root), [`modules/bootstrap/main.tf`](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/bootstrap/main.tf) (Talos Bootstrap), [`modules/image/main.tf`](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/image/main.tf) (Talos Image), [`modules/compute/main.tf`](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/compute/main.tf) (VM Compute)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provisioning["VM Provisioning"]
  node_tofu["OpenTofu Root<br/>[main.tf]"]
  node_image["Talos Image<br/>[main.tf]"]
  node_compute["VM Compute<br/>[main.tf]"]
end

subgraph group_cluster["Cluster Foundation"]
  node_bootstrap["Talos Bootstrap<br/>[main.tf]"]
  node_kubernetes{{"Kubernetes Cluster"}}
end

subgraph group_platform["Cluster Services"]
  node_cilium["Cilium Networking<br/>[main.tf]"]
  node_capi["Cluster API<br/>[main.tf]"]
  node_storage["NFS Storage<br/>[main.tf]"]
  node_dashboard["Kubernetes Dashboard<br/>[main.tf]"]
end

subgraph group_external["External Infrastructure"]
  node_proxmox["Proxmox VE"]
  node_talos_api["Talos API"]
  node_haproxy["HAProxy Load Balancer"]
  node_nfs_server[("NFS Server")]
end

node_operator(("IaC Operator"))

node_operator -->|"runs"| node_tofu
node_tofu -->|"provisions"| node_image
node_tofu -->|"provisions"| node_compute
node_tofu -->|"bootstraps"| node_bootstrap
node_tofu -->|"installs"| node_cilium
node_tofu -->|"installs"| node_capi
node_tofu -->|"installs"| node_storage
node_image -->|"imports image"| node_proxmox
node_compute -->|"creates VMs"| node_proxmox
node_bootstrap -->|"configures cluster"| node_talos_api
node_bootstrap -->|"bootstraps"| node_kubernetes
node_cilium -->|"adds networking"| node_kubernetes
node_haproxy -->|"forwards API traffic"| node_kubernetes
node_capi -->|"manages workers"| node_kubernetes
node_storage -->|"provisions from"| node_nfs_server

click node_tofu "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/main.tf"
click node_image "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/image/main.tf"
click node_compute "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/compute/main.tf"
click node_bootstrap "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/bootstrap/main.tf"
click node_cilium "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/cilium/main.tf"
click node_capi "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/capi/main.tf"
click node_storage "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/storage/main.tf"
click node_dashboard "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/kubernetes-dashboard/main.tf"
click node_haproxy "https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/infra/lb/haproxy-k8s-api.cfg"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tofu,node_image,node_compute toneBlue
class node_bootstrap,node_kubernetes toneAmber
class node_cilium,node_capi,node_storage,node_dashboard toneMint
class node_proxmox,node_talos_api,node_haproxy,node_nfs_server toneRose
class node_operator toneIndigo
```

## Components

### VM Provisioning

- [OpenTofu Root](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/main.tf): `main.tf`
- [Talos Image](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/image/main.tf): `modules/image/main.tf`
- [VM Compute](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/compute/main.tf): `modules/compute/main.tf`

### Cluster Foundation

- [Talos Bootstrap](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/bootstrap/main.tf): `modules/bootstrap/main.tf`
- **Kubernetes Cluster**

### Cluster Services

- [Cilium Networking](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/cilium/main.tf): `modules/cilium/main.tf`
- [Cluster API](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/capi/main.tf): `modules/capi/main.tf`
- [NFS Storage](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/storage/main.tf): `modules/storage/main.tf`
- [Kubernetes Dashboard](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/modules/kubernetes-dashboard/main.tf): `modules/kubernetes-dashboard/main.tf`

### External Infrastructure

- **Proxmox VE**
- **Talos API**
- [HAProxy Load Balancer](https://github.com/leandrosalvas/opentofu-proxmox-kubernetes/blob/main/infra/lb/haproxy-k8s-api.cfg): `infra/lb/haproxy-k8s-api.cfg`
- **NFS Server**

### Other components

- **IaC Operator**

## Connections

- IaC Operator → OpenTofu Root: runs (evidence: `README.md`)
- OpenTofu Root → Talos Image: provisions (evidence: `README.md`)
- OpenTofu Root → VM Compute: provisions (evidence: `README.md`)
- OpenTofu Root → Talos Bootstrap: bootstraps (evidence: `README.md`)
- OpenTofu Root → Cilium Networking: installs (evidence: `README.md`)
- OpenTofu Root → Cluster API: installs (evidence: `README.md`)
- OpenTofu Root → NFS Storage: installs (evidence: `README.md`)
- Talos Image → Proxmox VE: imports image (evidence: `README.md`)
- VM Compute → Proxmox VE: creates VMs (evidence: `README.md`)
- Talos Bootstrap → Talos API: configures cluster (evidence: `README.md`)
- Talos Bootstrap → Kubernetes Cluster: bootstraps (evidence: `README.md`)
- Cilium Networking → Kubernetes Cluster: adds networking (evidence: `README.md`)
- HAProxy Load Balancer → Kubernetes Cluster: forwards API traffic (evidence: `README.md`)
- Cluster API → Kubernetes Cluster: manages workers (evidence: `README.md`)
- NFS Storage → NFS Server: provisions from (evidence: `README.md`)