# tsuyakashi/iac-proxmox-lab architecture

> Architecture diagram of the GitHub repository tsuyakashi/iac-proxmox-lab, 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/tsuyakashi/iac-proxmox-lab
- Repository: https://github.com/tsuyakashi/iac-proxmox-lab

## Overview

This repository is Terraform infrastructure-as-code for provisioning and operating a Proxmox lab. Operators select an environment stack, which derives its Proxmox endpoint and golden-image ID from the target node, provisions VMs, and uses MinIO for remote state and Vault for credentials and SSH keys. The stacks cover general cluster nodes, specialized Immich and Minecraft VMs, poly-nodes, and a CI runner. Documented supporting capabilities include MinIO, Vault, and Tailscale service setup, plus CI-driven and manual Terraform applies. Relationships here follow README documentation; implementation wiring was not sampled.

Main entry points: [`environments/runner`](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/runner) (CI runner), [`environments/nodes`](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/nodes) (Cluster nodes), [`environments/poly-nodes`](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/poly-nodes) (Poly-nodes), [`environments/immich-node`](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/immich-node) (Immich VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stacks["Environment stacks"]
  node_nodes["Cluster nodes"]
  node_poly["Poly-nodes"]
  node_immich["Immich VM"]
  node_minecraft["Minecraft VM"]
  node_runner["CI runner"]
end

subgraph group_provisioning["VM provisioning"]
  node_vm_module["Proxmox VM module"]
end

subgraph group_services["Lab services"]
  node_minio[("MinIO state")]
  node_vault[("Vault secrets")]
  node_tailscale["Tailscale access"]
end

subgraph group_operations["Operations"]
  node_ci_workflow["CI pipeline<br/>[pipeline.yml]"]
  node_manual_apply["Manual apply"]
  node_minio_init["MinIO setup<br/>[minio-lxc-init.sh]"]
  node_vault_init["Vault setup<br/>[vault-lxc-init.sh]"]
  node_approle["AppRole setup"]
  node_userpass["Manual login setup"]
  node_tailscale_init["Tailscale setup"]
  node_runner_init["Runner setup"]
end

node_operator(("Operator"))
node_github(("GitHub Actions"))
node_proxmox["Proxmox cluster"]
node_swarm["swarm-lab Ansible"]

node_operator -->|"applies"| node_nodes
node_operator -->|"applies"| node_poly
node_operator -->|"applies"| node_immich
node_operator -->|"applies"| node_minecraft
node_operator -->|"applies"| node_runner
node_github -->|"triggers"| node_ci_workflow
node_ci_workflow -->|"applies"| node_runner
node_ci_workflow -->|"gets credentials"| node_vault
node_nodes -->|"uses"| node_vm_module
node_poly -->|"uses"| node_vm_module
node_immich -->|"uses"| node_vm_module
node_minecraft -->|"uses"| node_vm_module
node_runner -->|"uses"| node_vm_module
node_nodes -->|"provisions VMs"| node_proxmox
node_poly -->|"provisions VMs"| node_proxmox
node_immich -->|"provisions VM"| node_proxmox
node_minecraft -->|"provisions VM"| node_proxmox
node_runner -->|"provisions VM"| node_proxmox
node_nodes -->|"stores state"| node_minio
node_poly -->|"stores state"| node_minio
node_immich -->|"stores state"| node_minio
node_minecraft -->|"stores state"| node_minio
node_runner -->|"stores state"| node_minio
node_nodes -->|"reads secrets"| node_vault
node_poly -->|"reads secrets"| node_vault
node_immich -->|"reads secrets"| node_vault
node_minecraft -->|"reads secrets"| node_vault
node_runner -->|"reads secrets"| node_vault
node_operator -->|"runs"| node_manual_apply
node_manual_apply -->|"authenticates"| node_vault
node_minio_init -->|"initializes"| node_minio
node_vault_init -->|"initializes"| node_vault
node_approle -->|"configures AppRole"| node_vault
node_userpass -->|"configures login"| node_vault
node_tailscale_init -->|"initializes"| node_tailscale
node_runner_init -->|"registers"| node_runner
node_runner -.->|"delegates configuration"| node_swarm
node_proxmox -->|"hosts service"| node_tailscale

click node_nodes "https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/nodes"
click node_poly "https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/poly-nodes"
click node_immich "https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/immich-node"
click node_minecraft "https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/minecraft-node"
click node_runner "https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/runner"
click node_vm_module "https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/modules/proxmox-vm"
click node_ci_workflow "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/.github/workflows/pipeline.yml"
click node_manual_apply "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-apply-wrapper.sh"
click node_minio_init "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/minio-lxc-init.sh"
click node_vault_init "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-lxc-init.sh"
click node_approle "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-approle-init.sh"
click node_userpass "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-userpass-init.sh"
click node_tailscale_init "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/tailscale-lxc-init.sh"
click node_runner_init "https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/register-github-runner.sh"

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_nodes,node_poly,node_immich,node_minecraft,node_runner toneBlue
class node_vm_module toneAmber
class node_minio,node_vault,node_tailscale toneMint
class node_ci_workflow,node_manual_apply,node_minio_init,node_vault_init,node_approle,node_userpass,node_tailscale_init,node_runner_init toneRose
class node_operator,node_github,node_proxmox,node_swarm toneIndigo
```

## Components

### Environment stacks

- [Cluster nodes](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/nodes): `environments/nodes`
- [Poly-nodes](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/poly-nodes): `environments/poly-nodes`
- [Immich VM](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/immich-node): `environments/immich-node`
- [Minecraft VM](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/minecraft-node): `environments/minecraft-node`
- [CI runner](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/environments/runner): `environments/runner`

### VM provisioning

- [Proxmox VM module](https://github.com/tsuyakashi/iac-proxmox-lab/tree/main/modules/proxmox-vm): `modules/proxmox-vm`

### Lab services

- **MinIO state**
- **Vault secrets**
- **Tailscale access**

### Operations

- [CI pipeline](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/.github/workflows/pipeline.yml): `.github/workflows/pipeline.yml`
- [Manual apply](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-apply-wrapper.sh): `scripts/vault-apply-wrapper.sh`
- [MinIO setup](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/minio-lxc-init.sh): `scripts/minio-lxc-init.sh`
- [Vault setup](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-lxc-init.sh): `scripts/vault-lxc-init.sh`
- [AppRole setup](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-approle-init.sh): `scripts/vault-approle-init.sh`
- [Manual login setup](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/vault-userpass-init.sh): `scripts/vault-userpass-init.sh`
- [Tailscale setup](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/tailscale-lxc-init.sh): `scripts/tailscale-lxc-init.sh`
- [Runner setup](https://github.com/tsuyakashi/iac-proxmox-lab/blob/main/scripts/register-github-runner.sh): `scripts/register-github-runner.sh`

### Other components

- **Operator**
- **GitHub Actions**
- **Proxmox cluster**
- **swarm-lab Ansible**

## Connections

- Operator → Cluster nodes: applies
- Operator → Poly-nodes: applies
- Operator → Immich VM: applies
- Operator → Minecraft VM: applies
- Operator → CI runner: applies
- GitHub Actions → CI pipeline: triggers
- CI pipeline → CI runner: applies
- CI pipeline → Vault secrets: gets credentials
- Cluster nodes → Proxmox VM module: uses
- Poly-nodes → Proxmox VM module: uses
- Immich VM → Proxmox VM module: uses
- Minecraft VM → Proxmox VM module: uses
- CI runner → Proxmox VM module: uses
- Cluster nodes → Proxmox cluster: provisions VMs
- Poly-nodes → Proxmox cluster: provisions VMs
- Immich VM → Proxmox cluster: provisions VM
- Minecraft VM → Proxmox cluster: provisions VM
- CI runner → Proxmox cluster: provisions VM
- Cluster nodes → MinIO state: stores state
- Poly-nodes → MinIO state: stores state
- Immich VM → MinIO state: stores state
- Minecraft VM → MinIO state: stores state
- CI runner → MinIO state: stores state
- Cluster nodes → Vault secrets: reads secrets
- Poly-nodes → Vault secrets: reads secrets
- Immich VM → Vault secrets: reads secrets
- Minecraft VM → Vault secrets: reads secrets
- CI runner → Vault secrets: reads secrets
- Operator → Manual apply: runs
- Manual apply → Vault secrets: authenticates
- MinIO setup → MinIO state: initializes
- Vault setup → Vault secrets: initializes
- AppRole setup → Vault secrets: configures AppRole
- Manual login setup → Vault secrets: configures login
- Tailscale setup → Tailscale access: initializes
- Runner setup → CI runner: registers
- CI runner → swarm-lab Ansible: delegates configuration
- Proxmox cluster → Tailscale access: hosts service