Erich Blume 517080aeab Add reference/tools/ category with Dagger, ArgoCD CLI, Ansible, and Pulumi cards (#178 )

## Summary

- Create `docs/reference/tools/` with four reference cards: Dagger (build engine), ArgoCD CLI (deployment workflows), Ansible (config management), and Pulumi (DNS/Tailscale IaC)
- Move `ansible/roles.md` → `tools/ansible.md`, broadened with CLI patterns and dry-run usage
- Update `reference.md` index: add "Tools" section, remove old "Ansible" section
- Update `update-documentation.md` to reflect Dagger build process (workflow steps, manual build recipe, runner environment)
- Update `adopt-dagger-ci.md` plan to note how-to articles were handled via reference card + existing how-to updates
- Fix all broken `[[roles]]` wiki-links across 5 files → `[[ansible]]`

## Verification

- `docs-check-links` ✓ — no broken wiki-links
- `docs-check-index` ✓ — all docs referenced in category index
- `docs-check-filenames` ✓ — no duplicate filenames
- All pre-commit hooks pass

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/178

2026-02-12 19:18:46 -08:00

2.7 KiB

Raw Blame History

title

modified

Why GitOps?

Note: This article was drafted by AI and reviewed by Erich. I plan to rewrite all explanatory content in my own words - these serve as placeholders to establish the documentation structure.

BlumeOps uses GitOps principles for managing personal infrastructure. This might seem like overkill for a homelab, but there are good reasons.

The Problem with Manual Infrastructure

Traditional server management involves SSHing into machines and running commands. This works, but creates problems:

Drift: The actual state diverges from what you think it is
Amnesia: You forget what you changed and why
Fragility: One bad command can break things with no easy rollback
Bus factor: Only you know how it works (even AI assistants struggle without context)

Git as the Source of Truth

GitOps inverts the model: instead of pushing changes to servers, you commit desired state to Git, and automation pulls it into reality.

Benefits:

Every change is tracked with commit history
Pull requests enable review before deployment
Rollback is just git revert
The repo is the documentation

Why This Matters for a Homelab

A personal homelab isn't a production environment, but it shares the same challenges:

Memory is unreliable - Six months from now, you won't remember why you configured Caddy that way
Experimentation is constant - You try things, break things, want to undo things
AI assistance needs context - Claude can help much more effectively when it can read your infrastructure as code

The BlumeOps Approach

BlumeOps uses layered GitOps:

Layer	Tool	What it manages
Tailnet	[[tailscale	Pulumi]]
Host config	[[ansible	Ansible]]
Kubernetes	[[argocd	ArgoCD]]

Each layer has its own reconciliation loop:

Pulumi applies on mise run tailnet-up
Ansible applies on mise run provision-indri
ArgoCD watches Git and syncs manually or automatically

Trade-offs

GitOps isn't free:

Learning curve - You need to understand Ansible, ArgoCD, Pulumi
Indirection - Can't just apt install something; need to add it to config
Complexity - More moving parts than a simple server

But for BlumeOps, the trade-off is worth it. The infrastructure is complex enough that managing it imperatively would be error-prone, and the GitOps approach enables effective AI-assisted operations.

architecture - How the pieces fit together
argocd - Kubernetes GitOps
ansible - Host configuration

2.7 KiB Raw Blame History