71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
# Ansible Documentation
|
|
|
|
This folder contains **Ansible-specific** technical documentation for the homelab automation framework.
|
|
|
|
## Documentation Organization
|
|
|
|
The homelab uses a **domain-based separation** for documentation:
|
|
|
|
### Ansible-Specific Documentation (This Folder)
|
|
|
|
Documentation about **how Ansible works** in this homelab:
|
|
|
|
- **[ansible-knowledge/](ansible-knowledge/)** — Ansible syntax, YAML/Jinja2 reference, technical constraints
|
|
- **[playbooks/](playbooks/)** — Operational guides for running specific playbooks
|
|
- **[playbooks/README.md](playbooks/README.md)** — Playbook runbook index, including Watchtower monitoring onboarding and self-healing
|
|
- **[standards/ansible-quality-gates.md](standards/ansible-quality-gates.md)** — Ansible linting rules, security checklist, review workflow
|
|
|
|
### Homelab-Wide Documentation (Root `/documentation/`)
|
|
|
|
Documentation about **what the homelab allows** and architectural decisions:
|
|
|
|
- **[/documentation/architecture/](../../documentation/architecture/)** — Architectural contracts (control-plane, compute-plane, networking, storage, access-identity)
|
|
- **[/documentation/standards/](../../documentation/standards/)** — Homelab-wide standards (naming conventions, environment constraints, architecture decisions)
|
|
- **[/documentation/policies/](../../documentation/policies/)** — Operational policies (networking policy, etc.)
|
|
- **[/documentation/handover.md](../../documentation/handover.md)** — Primary project handover document
|
|
|
|
## Quick Reference
|
|
|
|
### When Troubleshooting Ansible Issues
|
|
|
|
1. **Syntax errors?** → [ansible-knowledge/ansible-syntax.md](ansible-knowledge/ansible-syntax.md)
|
|
2. **Playbook not working?** → [playbooks/README.md](playbooks/README.md) for operational guides
|
|
3. **Monitoring stack onboarding?** → [playbooks/watchtower-monitoring-onboarding.md](playbooks/watchtower-monitoring-onboarding.md)
|
|
4. **Linting failures?** → [standards/ansible-quality-gates.md](standards/ansible-quality-gates.md)
|
|
|
|
### When Designing Infrastructure
|
|
|
|
1. **What services can run where?** → [/documentation/architecture/compute-plane.md](../../documentation/architecture/compute-plane.md)
|
|
2. **Network topology?** → [/documentation/architecture/networking.md](../../documentation/architecture/networking.md)
|
|
3. **Storage architecture?** → [/documentation/architecture/storage.md](../../documentation/architecture/storage.md)
|
|
4. **Naming conventions?** → [/documentation/standards/naming-conventions.md](../../documentation/standards/naming-conventions.md)
|
|
|
|
## Files in This Folder
|
|
|
|
```text
|
|
ansible/documentation/
|
|
├── README.md # You are here
|
|
├── ansible-knowledge/ # Ansible syntax and technical reference
|
|
│ └── ansible-syntax.md
|
|
├── playbooks/ # Operational guides for playbooks
|
|
│ ├── README.md
|
|
│ ├── manage_docker_environment.md
|
|
│ ├── mount_nfs_shares.md
|
|
│ ├── onboard_new_host.md
|
|
│ ├── onboard-ansible-secrets.md
|
|
│ └── watchtower-monitoring-onboarding.md
|
|
├── reports/ # Analysis and audit reports
|
|
│ └── prompt-analysis-2026-01-09.md
|
|
└── standards/ # Ansible-specific standards
|
|
└── ansible-quality-gates.md
|
|
```
|
|
|
|
## Contributing
|
|
|
|
When adding new documentation:
|
|
|
|
- **Ansible-specific content** (syntax, modules, playbook operations) → Add to this folder
|
|
- **Homelab-wide content** (architecture, contracts, policies) → Add to `/documentation/` at the repository root
|
|
|
|
If unsure, ask: "Is this about how Ansible works, or about what the homelab architecture allows?"
|