docs: Add changelog and update role documentation

README.md

@@ -1,7 +1,6 @@
 # TuDatTr IaC
 
-**I do not recommend this project being used for ones own infrastructure, as
+**I do not recommend this project being used for one's own infrastructure, as this project is heavily attuned to my specific host/network setup.**
-this project is heavily attuned to my specific host/network setup**
 
 This Ansible project automates the setup of a K3s Kubernetes cluster on Proxmox VE. It also includes playbooks for configuring Docker hosts, load balancers, and other services.
 
@@ -41,6 +40,7 @@ The following roles are defined:
 - `kubernetes_argocd`: Deploys Argo CD to the Kubernetes cluster.
 - `node_exporter`: Installs the Prometheus Node Exporter for monitoring.
 - `reverse_proxy`: Configures a Caddy-based reverse proxy.
+- `edge_vps`: Placeholder role for Edge VPS configuration.
 
 ## Usage
 

changelog.md

@@ -0,0 +1,75 @@
+# Changelog
+
+Technical evolution of the infrastructure stack, tracking the migration from standalone Docker hosts to a fully automated, GitOps-managed Kubernetes cluster.
+
+## Phase 5: GitOps & Cluster Hardening (July 2025 - Present)
+
+*Shifted control plane management to ArgoCD and expanded storage capabilities.*
+
+- **GitOps Implementation**:
+  - Deployed **ArgoCD** in an App-of-Apps pattern to manage cluster state (`89c51aa`).
+  - Integrated **Sealed Secrets** (implied via vault diffs) and **Cert-Manager** for automated TLS management (`76000f8`).
+  - Migrated core services (Traefik, MetalLB) to Helm charts managed via ArgoCD manifests.
+- **Storage Architecture**:
+  - Implemented **Longhorn** with iSCSI support for distributed block storage (`48aec11`).
+  - Added **NFS Provisioner** (`e1a2248`) for ReadWriteMany volumes capabilities.
+- **Networking**:
+  - Centralized primary server IP logic (`97a5d6c`) to support HA control plane capability.
+  - Replaced Netcup DNS webhooks with **Cloudflare** for Caddy ACME challenges (`9cb90a8`).
+- **Observability**:
+  - Added **healthcheck** definitions to Docker Compose services (`0e8e07e`) and K3s probes.
+
+## Phase 4: IaaC Refactoring & Proxmox API Integration (Nov 2024 - June 2025)
+
+*Refactored Ansible roles for modularity and implemented Proxmox API automation for "click-less" provisioning.*
+
+- **Proxmox Automation**:
+  - Developed `roles/proxmox` to interface with Proxmox API: automated VM creation, cloning from templates, and Cloud-Init injection (`f2ea03b`).
+  - Configured **PCI Passthrough** (`591342f`) and hardware acceleration for media transcoding nodes.
+  - Added cron-based VM state reconciliation (`a1da69a`).
+- **Ansible Restructuring**:
+  - **Inventory Refactor**: Moved from root-level inventory files to a hierarchical `vars/` structure (`609e000`).
+  - **Linting Pipeline**: Integrated `ansible-lint` and `pre-commit` hooks (`6eef96b`) to enforce YAML standards and best practices.
+  - **Vault Security**: Configured `.gitattributes` to enable `ansible-vault view` for cleartext diffs in git (`c3905ed`).
+- **Identity Management**:
+  - Deployed **Keycloak** (`42196a3`) for OIDC/SAML authentication across the stack.
+
+## Phase 3: The Kubernetes Migration (Sep 2024 - Oct 2024)
+
+*Architectural pivot from Docker Compose to K3s.*
+
+- **Control Plane Setup**:
+  - Bootstrapped **K3s** cluster with dedicated server/agent split.
+  - Configured **HAProxy/Nginx** load balancers (`51a49d0`) for API server high availability.
+- **Node Provisioning**:
+  - Standardized node bootstrapping (kernel modules, sysctl params) for K3s compatibility.
+  - Deployed specialized storage nodes for Longhorn (`7d58de9`).
+- **Decommissioning**:
+  - Drained and removed legacy Docker hosts (`0aed818`).
+  - Migrated stateful workloads (Postgres) to cluster-managed resources.
+
+## Phase 2: Docker Service Expansion (2023 - 2024)
+
+*Vertical scaling of Docker hosts and introduction of the monitoring stack.*
+
+- **Service Stack**:
+  - Deployed the **\*arr suite** (Sonarr, Radarr, etc.) and Jellyfin with hardware mapping (`3d7f143`).
+  - Integrated **Paperless-ngx** with Redis and Tika consumption (`3f88065`).
+  - Self-hosted **Gitea** and **GitLab** (later removed) for source control.
+- **Observability V1**:
+  - Deployed **Prometheus** and **Grafana** stack (`b3ae5ef`).
+  - Added **Node Exporter** and **SmartCTL Exporter** (`0a361d9`) to bare metal hosts.
+  - Implemented **Uptime Kuma** for external availability monitoring.
+- **Reverse Proxy**:
+  - Transitioned ingress from Traefik v2 to **Nginx Proxy Manager**, then to **Caddy** for simpler configuration management (`a9af3c7`, `1a1b8cb`).
+
+## Phase 1: Genesis & Networking (Late 2022)
+
+*Initial infrastructure bring-up.*
+
+- **Base Configuration**:
+  - Established Ansible role structure for baseline system hardening (SSH, users, packages).
+  - Configured **Wireguard** mesh for secure inter-node communication (`2ba4259`).
+  - Set up **Backblaze B2** offsite backups via Restic/Rclone (`b371e24`).
+- **Network**:
+  - Experimented with **macvlan** Docker networks for direct container IP assignment.

roles/common/README.md

@@ -1,6 +1,6 @@
 # Ansible Role: common
 
-This role configures a baseline set of common configurations for Debian-based systems.
+This role configures a baseline set of common configurations for Debian-based systems, including time synchronization, essential packages, hostname, and specific developer tools.
 
 ## Requirements
 
@@ -11,33 +11,56 @@ None.
 Available variables are listed below, along with default values (see `vars/main.yml`):
 
 ```yaml
+# A list of common packages to install via apt.
+common_packages:
+  - build-essential
+  - curl
+  - git
+  - iperf3
+  - neovim
+  - rsync
+  - smartmontools
+  - sudo
+  - systemd-timesyncd
+  - tree
+  - screen
+  - bat
+  - fd-find
+  - ripgrep
+  - nfs-common
+  - open-iscsi
+  - parted
+
 # The hostname to configure.
 hostname: "new-host"
-
-# A list of extra packages to install.
-extra_packages:
-  - "htop"
-  - "ncdu"
-  - "stow"
-  - "unzip"
 ```
 
+## Tasks
+
+The role performs the following tasks:
+
+1.  **Configure Time**: Sets up `systemd-timesyncd` and timezone.
+2.  **Configure Packages**: Installs the list of `common_packages`.
+3.  **Configure Hostname**: Sets the system hostname.
+4.  **Configure Extra-Packages**:
+    - Installs `eza` (modern ls replacement).
+    - Installs `bottom` (process viewer).
+    - Installs `neovim` from AppImage and clones a custom configuration.
+5.  **Configure Bash**: Sets up bash aliases and prompt.
+6.  **Configure SSH**: Configures `sshd_config` for security.
+
 ## Dependencies
 
 None.
 
 ## Example Playbook
 
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
-
 ```yaml
 - hosts: servers
   roles:
     - role: common
-      hostname: "my-new-host"
+      vars:
-      extra_packages:
+        hostname: "my-server"
-        - "vim"
-        - "curl"
 ```
 
 ## License

roles/docker_host/README.md

@@ -7,7 +7,7 @@ This role sets up a Docker host, installs Docker, and configures it according to
 ### General
 
 - `docker_host_package_common_dependencies`: A list of common packages to be installed on the host.
-  - Default: `nfs-common`, `firmware-misc-nonfree`, `linux-image-amd64`
+  - Default: `nfs-common`
 - `apt_lock_files`: A list of apt lock files to check.
 - `arch`: The architecture of the host.
   - Default: `arm64` if `ansible_architecture` is `aarch64`, otherwise `amd64`.
@@ -82,4 +82,4 @@ To use this role, include it in your playbook and set the required variables.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+MIT

roles/edge_vps/README.md

@@ -0,0 +1,31 @@
+# Edge VPS
+
+(Work In Progress)
+
+## Description
+
+This role is currently a placeholder for configuring Edge VPS instances. It is intended to contain tasks for setting up and managing VPS hosts at the edge of the infrastructure.
+
+## Requirements
+
+None.
+
+## Role Variables
+
+None defined yet.
+
+## Dependencies
+
+None.
+
+## Example Playbook
+
+```yaml
+- hosts: all
+  roles:
+    - role: edge_vps
+```
+
+## License
+
+MIT

roles/kubernetes_argocd/README.md

@@ -20,7 +20,6 @@ Available variables are listed below, along with default values (see `defaults/m
 The following tasks are performed by this role:
 
 - **Install ArgoCD**: Creates the ArgoCD namespace and applies the installation manifests.
-- **Apply ArgoCD Ingress**: Applies an Ingress resource for the ArgoCD server. **Note:** The template file `ingress.yml.j2` is missing from the role.
 - **Apply ArgoCD CM**: Applies a ConfigMap with command parameters for ArgoCD.
 - **Apply ArgoCD repository**: Creates a Secret with Git repository credentials.
 - **Apply ArgoCD Root Application**: Creates a root Application resource for ArgoCD.

roles/node_exporter/README.md

@@ -0,0 +1,37 @@
+# Node Exporter
+
+This role installs and configures the Prometheus Node Exporter on target hosts.
+
+## Requirements
+
+None.
+
+## Role Variables
+
+Available variables are listed below, along with default values (see `vars/main.yaml`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `version` | `latest` | The version of Node Exporter to install. |
+| `bind_port` | `9100` | The port Node Exporter will listen on. |
+| `serve` | `localhost` | The address to bind to. |
+| `options` | `""` | Additional command-line options for Node Exporter. |
+| `bin_path` | `/usr/local/bin/node_exporter` | Installation path for the binary. |
+
+## Dependencies
+
+None.
+
+## Example Playbook
+
+```yaml
+- hosts: all
+  roles:
+    - role: node_exporter
+      vars:
+        version: "1.5.0"
+```
+
+## License
+
+MIT