honiggiralico-lang/k8s-proxmox-flask-project

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.