nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity
homelab/ansible/.ansible-standards.md
nathan 63fd1eb034 chore(ansible): establish development standards and tooling 
- ansible/.ansible-lint: Configure safety profile with strict enforcement
- ansible/.ansible-standards.md: Define architectural standards (idempotency, SSH, naming)
- ansible/DEVELOPMENT-SETUP.md: Document required CLI tools and VSCode extensions

Sets foundation for future infrastructure-as-code automation. Enforces Ansible best practices (FQCN, idempotency, block/rescue) and establishes development environment requirements (ansible-lint, proxmoxer, molecule).

Prepares for automated node provisioning and configuration management workflows.
2026-04-12 00:28:49 -04:00

1.2 KiB
Raw Blame History

Ansible Architectural Standards v1.0

metadata: role: Lead Ansible Architect enforcement: Strict idempotency: Required vault_encryption: Required

1. Project Philosophy

  • Agentless Execution: Rely on SSH and Python 3.
  • Desired State: Tasks must define the result, not the command (e.g., use apt, not shell: apt install).
  • Failure Domains: Use block/rescue for all destructive or system-level changes (updates, partitioning).

2. Technical Specs

  • Connection: SSH via ED25519 keys; ansible_user must have passwordless sudo or Vault-stored credentials.
  • Variables: - defaults/main.yml: Default values (lowest priority).
    • vars/main.yml: Role-specific constants.
    • group_vars/: Environment-specific overrides.
  • Naming: Kebab-case for files (web-server.yml), snake_case for variables (web_server_port).

3. Maintenance Logic

  • Serial Execution: serial: 1 for hypervisor/cluster nodes.
  • Reboot Strategy: Always check for /var/run/reboot-required before initiating a reboot task.
  • Service Verification: Post-task loops must verify that critical services (e.g., pveproxy) are started.