feat(ansible): restructure Ansible configuration and add essential files for infrastructure management

ansible/.ansible-lint

@@ -20,15 +20,12 @@ skip_list:
 exclude_paths:
   - .cache/
   - .git/
+  - archive/               # Legacy reference files
   - roles/external/        # Don't lint roles downloaded from Galaxy
 
-# Enforce specific tagging for organization
+# Enable offline mode for airgapped environments
-require_status:
+offline: false
-  - shared
-  - production
 
-# Custom configurations for specific rules
+# Enable FQCN enforcement (Fully Qualified Collection Names)
-# Ensures we always use Fully Qualified Collection Names (FQCN)
 # e.g., ansible.builtin.copy instead of just 'copy'
-fqcn:
+# This is now enforced by the 'safety' profile by default
-  - ansible.builtin

ansible/README.md

@@ -1 +1,47 @@
-# ansible folder
+# Ansible Infrastructure Automation
+
+This directory contains the Ansible automation framework for homelab infrastructure management.
+
+## 📁 Directory Structure
+
+```
+ansible/
+├── .ansible-lint              # Linting rules (enforces safety & best practices)
+├── .ansible-standards.md      # Architectural standards and conventions
+├── DEVELOPMENT-SETUP.md       # Control node setup requirements
+├── README.md                  # This file
+└── archive/                   # ⚠️ REFERENCE ONLY - Legacy implementation
+```
+
+---
+
+## ⚠️ Important: Archive Directory
+
+**The `archive/` directory contains the previous iteration of the Ansible infrastructure.**
+
+- **Purpose:** Reference and migration source only
+- **Status:** Not actively maintained
+- **Action:** Do NOT execute playbooks or use configurations directly from `archive/`
+- **Migration Status:** In progress - components are being refactored into the new structure
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+Refer to [DEVELOPMENT-SETUP.md](DEVELOPMENT-SETUP.md) for:
+- Required CLI tools (ansible-core, ansible-lint, proxmoxer)
+- VSCode extensions (recommended for development)
+- SSH key generation and vault configuration
+
+### Control Node Setup
+
+Watchtower (10.0.0.200) is the designated Ansible control node for this lab.
+
+---
+
+## 📚 Additional Resources
+
+- **Standards:** See [.ansible-standards.md](.ansible-standards.md) for architectural requirements
+- **Legacy Documentation:** Available in `archive/documentation/` for historical reference

ansible/ansible.cfg

@@ -0,0 +1,36 @@
+[defaults]
+# Inventory configuration
+inventory = inventory/hosts.ini
+host_key_checking = False
+deprecation_warnings = False
+interpreter_python = auto_silent
+
+# Paths (relative to this ansible/ directory)
+roles_path = ./roles:~/.ansible/roles:/usr/share/ansible/roles
+
+# Vault configuration
+vault_password_file = vault/.vault_pass
+
+# Performance tuning
+forks = 5
+timeout = 30
+gathering = smart
+fact_caching = jsonfile
+fact_caching_connection = /tmp/ansible_facts
+fact_caching_timeout = 3600
+
+# Callbacks for better output
+callbacks_enabled = timer, profile_tasks
+
+# Logging
+log_path = ansible.log
+
+[privilege_escalation]
+become = True
+become_method = sudo
+become_user = root
+become_ask_pass = False
+
+[ssh_connection]
+ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no
+pipelining = True

ansible/group_vars/all.yml

@@ -0,0 +1,37 @@
+---
+# Global variables for all hosts
+# These apply to every host in the inventory unless overridden
+
+# Network Configuration
+network:
+  gateway: 10.0.0.2
+  dns_servers:
+    - 10.0.0.2
+    - 8.8.8.8
+  subnet: 10.0.0.0/24
+
+# Time and Locale
+timezone: America/New_York
+locale: en_US.UTF-8
+
+# SSH Configuration
+ssh_port: 22
+ssh_key_type: ed25519
+
+# Docker Configuration
+docker:
+  version: latest
+  compose_version: latest
+  registry_mirrors: []
+
+# Security Defaults
+security:
+  ufw_enabled: false
+  fail2ban_enabled: false
+  automatic_updates: true
+
+# Maintenance Windows
+maintenance:
+  reboot_allowed: true
+  reboot_time: "03:00"
+  update_cache_valid_time: 3600

ansible/inventory/hosts.ini

@@ -0,0 +1,29 @@
+# Ansible Inventory for Homelab Infrastructure
+# This is the active inventory - do NOT use archive/inventory/hosts.ini
+
+# =============================================================================
+# Control Plane
+# =============================================================================
+[control_plane]
+watchtower ansible_host=10.0.0.200 ansible_user=chester
+
+# =============================================================================
+# Add your managed nodes below
+# =============================================================================
+
+# Example structure:
+# [docker_swarm_managers]
+# heimdall ansible_host=10.0.0.X ansible_user=chester
+
+# [docker_swarm_workers]
+# waldorf ansible_host=10.0.0.X ansible_user=chester
+
+# [proxmox_cluster]
+# pve-node1 ansible_host=10.0.0.X ansible_user=root
+
+# =============================================================================
+# Group Variables
+# =============================================================================
+[all:vars]
+ansible_python_interpreter=/usr/bin/python3
+ansible_ssh_private_key_file=~/.ssh/id_ed25519

ansible/playbooks/test-connection.yml

@@ -0,0 +1,14 @@
+---
+# Test playbook to verify Ansible control node setup
+# Usage: ansible-playbook playbooks/test-connection.yml
+
+- name: Test connection to all hosts
+  hosts: all
+  gather_facts: true
+  tasks:
+    - name: Ping all hosts
+      ansible.builtin.ping:
+
+    - name: Display host information
+      ansible.builtin.debug:
+        msg: "Connected to {{ inventory_hostname }} ({{ ansible_host }})"

ansible/requirements.yml

@@ -0,0 +1,33 @@
+---
+# Ansible Galaxy requirements
+# Install with: ansible-galaxy install -r requirements.yml
+#
+# This file tracks all external collections and roles required by this repository.
+# Version pinning ensures reproducible deployments.
+#
+# Last updated: 2026-01-10
+
+collections:
+  # Community General Collection
+  # Used for: proxmox modules, docker modules, general utilities
+  # Docs: https://docs.ansible.com/ansible/latest/collections/community/general/
+  - name: community.general
+    version: ">=8.0.0"
+
+  # Community Docker Collection
+  # Used for: docker_swarm, docker_container, docker_network modules
+  # Docs: https://docs.ansible.com/ansible/latest/collections/community/docker/
+  - name: community.docker
+    version: ">=3.0.0"
+
+  # Ansible POSIX Collection
+  # Used for: authorized_key, synchronize, sysctl modules
+  # Docs: https://docs.ansible.com/ansible/latest/collections/ansible/posix/
+  - name: ansible.posix
+    version: ">=1.5.0"
+
+# roles:
+  # Add external roles here as needed
+  # Example:
+  # - name: geerlingguy.docker
+  #   version: "6.1.0"

ansible/vault/.gitignore

@@ -0,0 +1,6 @@
+# Vault password files should NEVER be committed
+.vault_pass
+*.vault_pass
+
+# Encrypted variables can be committed
+# vault.yml