nathan
63fd1eb034
- 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.
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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)
|
|
```bash
|
|
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." |