# alexandrelamberty/proxmox-k3s-iac architecture

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

- Interactive diagram: https://gitdiagram.com/alexandrelamberty/proxmox-k3s-iac
- Repository: https://github.com/alexandrelamberty/proxmox-k3s-iac

## Overview

This repository provisions a Proxmox VM fleet and turns it into a highly available K3s cluster. Terraform creates the VMs and Ansible inventory; Ansible then prepares the nodes, initializes the first server, deploys kube-vip, joins the remaining servers through the VIP, and retrieves a kubeconfig. The README documents the runtime workflow, but no source excerpts were provided, so relationships here follow that documentation rather than inspected implementation details.

Main entry points: [`ansible/playbooks/main.yml`](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/main.yml) (Provisioning Workflow), [`terraform/main.tf`](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/main.tf) (Terraform), [`ansible/playbooks/install-other-servers.yml`](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-other-servers.yml) (Join Servers), [`terraform/scripts/render-openbao-env.sh`](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/scripts/render-openbao-env.sh) (OpenBao Env Helper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_infrastructure["Infrastructure"]
  node_terraform["Terraform<br/>[main.tf]"]
  node_inventory["Ansible Inventory<br/>[hosts.yml.example]"]
  node_tfstate[("Terraform State<br/>[backend.tf]")]
  node_envhelper["OpenBao Env Helper"]
end

subgraph group_provisioning["Node Provisioning"]
  node_ansiblemain["Provisioning Workflow<br/>[main.yml]"]
  node_prepare["Prepare Nodes<br/>[prepare.yml]"]
end

subgraph group_cluster["K3s Cluster"]
  node_first["Initialize Server"]
  node_servers["K3s Servers"]
  node_vipinstall["Install kube-vip"]
  node_vip["API Virtual IP"]
  node_join["Join Servers"]
  node_fetch["Fetch Kubeconfig"]
  node_kubeconfig["Control-Machine Kubeconfig"]
end

node_operator(("Operator"))
node_proxmox["Proxmox"]
node_minio[("MinIO S3")]
node_openbao[("OpenBao")]
node_control(("Ansible Control Machine"))
node_clients(("Kubernetes API Clients"))

node_operator -->|"runs"| node_terraform
node_terraform -->|"creates VMs"| node_proxmox
node_terraform -->|"writes inventory"| node_inventory
node_terraform -->|"stores state"| node_tfstate
node_tfstate -->|"uses S3 backend"| node_minio
node_envhelper -->|"reads credentials"| node_openbao
node_envhelper -.->|"provides environment"| node_terraform
node_operator -->|"runs"| node_ansiblemain
node_ansiblemain -->|"imports first"| node_prepare
node_ansiblemain -->|"imports next"| node_first
node_ansiblemain -->|"imports next"| node_vipinstall
node_ansiblemain -->|"imports next"| node_join
node_ansiblemain -->|"imports last"| node_fetch
node_inventory -->|"provides hosts"| node_ansiblemain
node_prepare -->|"prepares nodes"| node_servers
node_first -->|"initializes first"| node_servers
node_vipinstall -->|"deploys"| node_vip
node_vip -->|"announces endpoint"| node_servers
node_join -->|"joins through"| node_vip
node_join -->|"adds remaining"| node_servers
node_fetch -->|"retrieves"| node_kubeconfig
node_control -->|"receives"| node_kubeconfig
node_clients -->|"connects via API"| node_vip

click node_terraform "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/main.tf"
click node_inventory "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/inventory/hosts.yml.example"
click node_tfstate "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/backend.tf"
click node_envhelper "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/scripts/render-openbao-env.sh"
click node_ansiblemain "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/main.yml"
click node_prepare "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/prepare.yml"
click node_first "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-first-server.yml"
click node_vipinstall "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-kube-vip.yml"
click node_join "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-other-servers.yml"
click node_fetch "https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/fetch-kubeconfig.yml"

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_terraform,node_inventory,node_tfstate,node_envhelper,node_clients toneBlue
class node_ansiblemain,node_prepare,node_minio,node_openbao toneAmber
class node_first,node_servers,node_vipinstall,node_vip,node_join,node_fetch,node_kubeconfig toneMint
class node_operator,node_proxmox,node_control toneIndigo
```

## Components

### Infrastructure

- [Terraform](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/main.tf): `terraform/main.tf`
- [Ansible Inventory](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/inventory/hosts.yml.example): `ansible/inventory/hosts.yml.example`
- [Terraform State](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/backend.tf): `terraform/backend.tf`
- [OpenBao Env Helper](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/terraform/scripts/render-openbao-env.sh): `terraform/scripts/render-openbao-env.sh`

### Node Provisioning

- [Provisioning Workflow](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/main.yml): `ansible/playbooks/main.yml`
- [Prepare Nodes](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/prepare.yml): `ansible/playbooks/prepare.yml`

### K3s Cluster

- [Initialize Server](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-first-server.yml): `ansible/playbooks/install-first-server.yml`
- **K3s Servers**
- [Install kube-vip](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-kube-vip.yml): `ansible/playbooks/install-kube-vip.yml`
- **API Virtual IP**
- [Join Servers](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/install-other-servers.yml): `ansible/playbooks/install-other-servers.yml`
- [Fetch Kubeconfig](https://github.com/alexandrelamberty/proxmox-k3s-iac/blob/master/ansible/playbooks/fetch-kubeconfig.yml): `ansible/playbooks/fetch-kubeconfig.yml`
- **Control-Machine Kubeconfig**

### Other components

- **Operator**
- **Proxmox**
- **MinIO S3**
- **OpenBao**
- **Ansible Control Machine**
- **Kubernetes API Clients**

## Connections

- Operator → Terraform: runs
- Terraform → Proxmox: creates VMs
- Terraform → Ansible Inventory: writes inventory
- Terraform → Terraform State: stores state
- Terraform State → MinIO S3: uses S3 backend
- OpenBao Env Helper → OpenBao: reads credentials
- OpenBao Env Helper → Terraform: provides environment
- Operator → Provisioning Workflow: runs
- Provisioning Workflow → Prepare Nodes: imports first
- Provisioning Workflow → Initialize Server: imports next
- Provisioning Workflow → Install kube-vip: imports next
- Provisioning Workflow → Join Servers: imports next
- Provisioning Workflow → Fetch Kubeconfig: imports last
- Ansible Inventory → Provisioning Workflow: provides hosts
- Prepare Nodes → K3s Servers: prepares nodes
- Initialize Server → K3s Servers: initializes first
- Install kube-vip → API Virtual IP: deploys
- API Virtual IP → K3s Servers: announces endpoint
- Join Servers → API Virtual IP: joins through
- Join Servers → K3s Servers: adds remaining
- Fetch Kubeconfig → Control-Machine Kubeconfig: retrieves
- Ansible Control Machine → Control-Machine Kubeconfig: receives
- Kubernetes API Clients → API Virtual IP: connects via API