# honiggiralico-lang/k8s-proxmox-flask-project architecture

> Architecture diagram of the GitHub repository honiggiralico-lang/k8s-proxmox-flask-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/honiggiralico-lang/k8s-proxmox-flask-project
- Repository: https://github.com/honiggiralico-lang/k8s-proxmox-flask-project

## Overview

#### Purpose and Operating Model
This repository automates a small self-hosted Kubernetes platform on Proxmox VE and deploys a Flask/Redis application to it. A Fedora control node runs Terraform, Ansible, Podman, kubectl, and the GitHub Actions self-hosted runner; Proxmox hosts one K3s control-plane VM and two worker VMs.

#### Infrastructure Provisioning
Terraform creates the Proxmox VM fleet using Cloud-Init templates, network configuration, API credentials, SSH keys, and capacity-oriented VM settings. Its boundary is the Proxmox API: it produces reachable node infrastructure but does not install Kubernetes.
- `1_terraform/main.tf`
- `1_terraform/provider.tf`
- `1_terraform/variables.tf`

#### Cluster Bootstrap and Node Roles
Ansible consumes a manually populated inventory using Terraform-discovered IPs. It installs and initializes K3s on the master, obtains its join state, and joins worker nodes. K3s is the runtime boundary between VM configuration and Kubernetes workload scheduling.
- `2_ansible/k3s-setup.yml`
- `2_ansible/inventory.ini.example`

#### Private Image Distribution
The control node hosts a Podman `registry:2` container on port 5000. Nodes are configured to treat that HTTP registry as an allowed image source, allowing K3s/containerd to pull application images without a public registry. Registry startup and image build/push are control-node operations; node-side registry configuration is automated by Ansible.
- `2_ansible/registry-setup.yml`
- `app/Dockerfile`

#### Application Image and Runtime
The application is a Python Flask container, with Redis forming the second application tier. Python dependencies and image construction are contained within the application directory; the resulting image is tagged and pushed to the local registry before Kubernetes deployment.
- `app/app.py`
- `app/requirements.txt`
- `app/Dockerfile`

#### Kubernetes Workload Exposure
A single manifest deploys the application workload and its supporting Kubernetes resources. It exposes the Flask service through both cluster networking and K3s’s bundled Traefik ingress, routing `flask.local` traffic to the service. Local DNS resolution is intentionally outside the repository, via the control node’s hosts file.
- `3_kubernetes/app-deployment.yaml`

#### Delivery Flow
On pushes to `main` affecting `app/`, GitHub Actions runs on the self-hosted control-node runner. The workflow builds a Podman image, pushes it to the local registry, and requests a Kubernetes rolling restart so pods pull/run the updated image. This makes the control node both CI executor and private artifact source.
- `.github/workflows/ci-cd.yml`

#### End-to-End Control Flow
Terraform provisions Proxmox VMs → Ansible turns them into a K3s cluster and configures registry access → Podman builds/pushes Flask images to the control-node registry → kubectl applies Kubernetes resources → K3s schedules pods and Traefik receives HTTP ingress. Primary external dependencies are Proxmox VE/API, Cloud-Init VM templates, GitHub Actions, the LAN, and the control-node-hosted registry.

Main entry points: [`2_ansible/k3s-setup.yml`](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml) (Ansible), [`3_kubernetes/app-deployment.yaml`](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml) (Flask Pods), [`.github/workflows/ci-cd.yml`](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/.github/workflows/ci-cd.yml) (Self-hosted Runner), [`2_ansible/registry-setup.yml`](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/registry-setup.yml) (Local Registry :5000)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Fedora Control Node"]
  node_terraform["Terraform<br/>infrastructure provisioning<br/>[main.tf]"]
  node_ansible["Ansible<br/>cluster bootstrap<br/>[k3s-setup.yml]"]
  node_runner["Self-hosted Runner<br/>GitHub Actions runner<br/>[ci-cd.yml]"]
  node_podman["Podman Build<br/>container build"]
  node_registry[("Local Registry :5000<br/>private OCI registry<br/>[registry-setup.yml]")]
  node_inventory["Ansible Inventory<br/>manual node inventory"]
  node_flask_image["Flask Image<br/>Python application image<br/>[app.py]"]
end

subgraph group_proxmox["Proxmox VE"]
  node_proxmox_api["Proxmox API<br/>virtualization API<br/>[provider.tf]"]
  node_cloud_init["Cloud-Init Templates<br/>VM initialization<br/>[variables.tf]"]
  node_vm_fleet["K3s VM Fleet<br/>control plane and workers<br/>[main.tf]"]
end

subgraph group_cluster["K3s Cluster"]
  node_k3s_control["K3s Control Plane<br/>Kubernetes control plane<br/>[k3s-setup.yml]"]
  node_k3s_workers["K3s Workers<br/>Kubernetes worker nodes<br/>[k3s-setup.yml]"]
  node_registry_access["Registry Access Config<br/>containerd registry configuration<br/>[registry-setup.yml]"]
  node_k8s_manifest["Application Manifest<br/>Kubernetes resources"]
  node_flask_pods["Flask Pods<br/>application workload"]
  node_redis[("Redis<br/>application data tier")]
  node_traefik["Traefik Ingress<br/>K3s ingress controller"]
end

node_github{{"GitHub Actions<br/>CI trigger"}}
node_lan_clients["LAN Clients<br/>HTTP clients"]

node_terraform -->|"provisions through"| node_proxmox_api
node_cloud_init -->|"initializes"| node_vm_fleet
node_proxmox_api -->|"creates"| node_vm_fleet
node_vm_fleet -.->|"IPs populate"| node_inventory
node_inventory -->|"targets"| node_ansible
node_ansible -->|"initializes"| node_k3s_control
node_ansible -->|"joins"| node_k3s_workers
node_ansible -->|"configures"| node_registry_access
node_github -->|"push to main triggers"| node_runner
node_runner -->|"builds"| node_podman
node_podman -->|"produces"| node_flask_image
node_flask_image -->|"pushes"| node_registry
node_registry_access -.->|"permits pulls from"| node_registry
node_runner -->|"requests rolling restart"| node_k8s_manifest
node_k8s_manifest -->|"applied with kubectl"| node_k3s_control
node_k3s_control -->|"schedules workloads"| node_k3s_workers
node_registry -->|"image pull"| node_flask_pods
node_k3s_workers -->|"runs"| node_flask_pods
node_flask_pods -->|"uses"| node_redis
node_k8s_manifest -->|"configures ingress"| node_traefik
node_lan_clients -->|"HTTP flask.local"| node_traefik
node_traefik -->|"routes to service"| node_flask_pods

click node_terraform "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/main.tf"
click node_ansible "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml"
click node_runner "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/.github/workflows/ci-cd.yml"
click node_podman "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/app/Dockerfile"
click node_registry "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/registry-setup.yml"
click node_proxmox_api "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/provider.tf"
click node_cloud_init "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/variables.tf"
click node_vm_fleet "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/main.tf"
click node_inventory "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/inventory.ini.example"
click node_k3s_control "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml"
click node_k3s_workers "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml"
click node_registry_access "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/registry-setup.yml"
click node_k8s_manifest "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml"
click node_flask_image "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/app/app.py"
click node_flask_pods "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml"
click node_redis "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml"
click node_traefik "https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml"

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_ansible,node_runner,node_podman,node_registry,node_inventory,node_flask_image toneBlue
class node_proxmox_api,node_cloud_init,node_vm_fleet toneAmber
class node_k3s_control,node_k3s_workers,node_registry_access,node_k8s_manifest,node_flask_pods,node_redis,node_traefik toneMint
class node_github,node_lan_clients toneNeutral
```

## Components

### Fedora Control Node

Automation, CI, and private image distribution.

- [Terraform](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/main.tf): infrastructure provisioning · `1_terraform/main.tf`
- [Ansible](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml): cluster bootstrap · `2_ansible/k3s-setup.yml`
- [Self-hosted Runner](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/.github/workflows/ci-cd.yml): GitHub Actions runner · `.github/workflows/ci-cd.yml`
- [Podman Build](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/app/Dockerfile): container build · `app/Dockerfile`
- [Local Registry :5000](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/registry-setup.yml): private OCI registry · Podman registry:2 container on the control node. · `2_ansible/registry-setup.yml`
- [Ansible Inventory](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/inventory.ini.example): manual node inventory · Populated with Terraform-discovered IPs. · `2_ansible/inventory.ini.example`
- [Flask Image](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/app/app.py): Python application image · `app/app.py`

### Proxmox VE

Virtual machine infrastructure.

- [Proxmox API](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/provider.tf): virtualization API · `1_terraform/provider.tf`
- [Cloud-Init Templates](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/variables.tf): VM initialization · `1_terraform/variables.tf`
- [K3s VM Fleet](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/1_terraform/main.tf): control plane and workers · One control-plane VM and two worker VMs. · `1_terraform/main.tf`

### K3s Cluster

Kubernetes runtime and workload exposure.

- [K3s Control Plane](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml): Kubernetes control plane · `2_ansible/k3s-setup.yml`
- [K3s Workers](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/k3s-setup.yml): Kubernetes worker nodes · `2_ansible/k3s-setup.yml`
- [Registry Access Config](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/2_ansible/registry-setup.yml): containerd registry configuration · Allows pulls from the HTTP local registry. · `2_ansible/registry-setup.yml`
- [Application Manifest](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml): Kubernetes resources · Defines Flask, Redis, Service, and ingress resources. · `3_kubernetes/app-deployment.yaml`
- [Flask Pods](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml): application workload · `3_kubernetes/app-deployment.yaml`
- [Redis](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml): application data tier · `3_kubernetes/app-deployment.yaml`
- [Traefik Ingress](https://github.com/honiggiralico-lang/k8s-proxmox-flask-project/blob/main/3_kubernetes/app-deployment.yaml): K3s ingress controller · Routes flask.local traffic to the Flask service. · `3_kubernetes/app-deployment.yaml`

### Other components

- **GitHub Actions**: CI trigger
- **LAN Clients**: HTTP clients · Resolve flask.local through control-node hosts configuration outside the repository.

## Connections

- Terraform → Proxmox API: provisions through
- Cloud-Init Templates → K3s VM Fleet: initializes
- Proxmox API → K3s VM Fleet: creates
- K3s VM Fleet → Ansible Inventory: IPs populate
- Ansible Inventory → Ansible: targets
- Ansible → K3s Control Plane: initializes
- Ansible → K3s Workers: joins
- Ansible → Registry Access Config: configures
- GitHub Actions → Self-hosted Runner: push to main triggers
- Self-hosted Runner → Podman Build: builds
- Podman Build → Flask Image: produces
- Flask Image → Local Registry :5000: pushes
- Registry Access Config → Local Registry :5000: permits pulls from
- Self-hosted Runner → Application Manifest: requests rolling restart
- Application Manifest → K3s Control Plane: applied with kubectl
- K3s Control Plane → K3s Workers: schedules workloads
- Local Registry :5000 → Flask Pods: image pull
- K3s Workers → Flask Pods: runs
- Flask Pods → Redis: uses
- Application Manifest → Traefik Ingress: configures ingress
- LAN Clients → Traefik Ingress: HTTP flask.local
- Traefik Ingress → Flask Pods: routes to service