nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity
homelab/ansible/DEVELOPMENT-SETUP.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

3.1 KiB
Raw Blame History

Development Setup Manifest

Version: 1.0
Target Environment: Ansible Control Node & Local Workstation

This document outlines the software and configurations required to develop, lint, and execute Ansible playbooks within this ecosystem.

1. CLI Tools (The Engine Room)

These tools must be installed on your Control Node. If you are developing locally, they should also be installed on your workstation.

Tool Function Purpose Cost
Ansible-Core Execution Engine Processes YAML playbooks and manages SSH connections. Free
Ansible-Lint Static Analysis Validates code against best practices and idempotency rules. Free
Molecule Testing Framework Runs playbooks against temporary containers to verify roles. Free
Ansible-Vault Secret Management Encrypts sensitive data (passwords/API keys) at rest. Free
Proxmoxer Python API Library Allows Ansible to communicate with the Proxmox VE API. Free
ssh-pass Auth Utility Enables password-based login during the initial key-copy phase. Free

Installation Command (Debian/Ubuntu)

sudo apt update && sudo apt install -y ansible ansible-lint sshpass python3-pip
pip3 install proxmoxer --break-system-packages

2. VSCode Extensions (The Cockpit)

For the best development experience, install these extensions in Visual Studio Code.

Ansible (by Red Hat)

  • What it does: Provides syntax highlighting, jinja2 auto-completion, and direct linting integration.
  • Why you want it: It catches "broken" YAML and missing parameters while you type.
  • Cost: Free

YAML (by Red Hat)

  • What it does: Validates the structure of .yml and .yaml files.
  • Why you want it: Ansible is hypersensitive to indentation; this extension prevents 90% of syntax errors.
  • Cost: Free

GitLens (by GitKraken)

  • What it does: Provides "blame" annotations and repository heatmaps.
  • Why you want it: Crucial for tracking why a system configuration was changed three months ago.
  • Cost: Free Core (Pro features available via sub)

Remote - SSH (by Microsoft)

  • What it does: Connects VSCode directly to your Control Node over SSH.
  • Why you want it: Allows you to code on your main PC but use the environment/tools installed on the Control Node.
  • Cost: Free

3. Configuration Files

To ensure the tools above work correctly, the following files should exist in your project root:

  1. .ansible-lint: Defines the "Safety" profile to enforce architecture standards.
  2. ansible.cfg: Configures default inventory paths and SSH behavior.
  3. .ssh/id_ed25519: The private key used for node authentication.

4. LLM Context Hook

When using an LLM to generate code for this project, provide the following context to ensure compatibility:

"My environment uses Ansible-Core with the Proxmoxer API library. I enforce standards via Ansible-Lint using the safety profile. All playbooks must pass these checks and use ED25519 keys for authentication."