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
This commit is contained in:
parent
9c789a1868
commit
517080aeab
13 changed files with 237 additions and 48 deletions
61
docs/reference/tools/ansible.md
Normal file
61
docs/reference/tools/ansible.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
---
|
||||
title: Ansible
|
||||
modified: 2026-02-12
|
||||
tags:
|
||||
- ansible
|
||||
- reference
|
||||
---
|
||||
|
||||
# Ansible
|
||||
|
||||
Configuration management for native services on [[indri]]. The primary playbook is `ansible/playbooks/indri.yml`.
|
||||
|
||||
## CLI Patterns
|
||||
|
||||
```bash
|
||||
# Full provisioning
|
||||
mise run provision-indri
|
||||
|
||||
# Specific role only
|
||||
mise run provision-indri -- --tags caddy
|
||||
|
||||
# Dry run (preview changes)
|
||||
mise run provision-indri -- --check --diff
|
||||
```
|
||||
|
||||
## Available Roles
|
||||
|
||||
| Role | Purpose | Service |
|
||||
|------|---------|---------|
|
||||
| **alloy** | Observability collector | [[alloy]] |
|
||||
| **borgmatic** | Backup automation | [[borgmatic]] |
|
||||
| **borgmatic_metrics** | Backup metrics exporter | [[borgmatic]] |
|
||||
| **caddy** | Reverse proxy & TLS | [[routing]] |
|
||||
| **forgejo** | Git forge | [[forgejo]] |
|
||||
| **jellyfin** | Media server | [[jellyfin]] |
|
||||
| **jellyfin_metrics** | Media metrics exporter | [[jellyfin]] |
|
||||
| **minikube** | Kubernetes cluster | [[cluster]] |
|
||||
| **minikube_metrics** | Cluster metrics | [[cluster]] |
|
||||
| **zot** | Container registry | [[zot]] |
|
||||
| **zot_metrics** | Registry metrics | [[zot]] |
|
||||
|
||||
## Role Structure
|
||||
|
||||
Each role follows Ansible conventions:
|
||||
```
|
||||
ansible/roles/<role>/
|
||||
├── defaults/main.yml # Default variables
|
||||
├── tasks/main.yml # Task definitions
|
||||
├── handlers/main.yml # Handlers (restarts, etc.)
|
||||
├── templates/ # Jinja2 templates
|
||||
└── files/ # Static files
|
||||
```
|
||||
|
||||
## Secrets
|
||||
|
||||
Roles that need secrets use 1Password via the playbook's `pre_tasks`. Secrets are gathered at playbook start and passed to roles as variables.
|
||||
|
||||
## Related
|
||||
|
||||
- [[indri]] — Target host
|
||||
- [[observability]] — Metrics collection
|
||||
54
docs/reference/tools/argocd-cli.md
Normal file
54
docs/reference/tools/argocd-cli.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: ArgoCD CLI
|
||||
modified: 2026-02-12
|
||||
tags:
|
||||
- reference
|
||||
- gitops
|
||||
- argocd
|
||||
---
|
||||
|
||||
# ArgoCD CLI
|
||||
|
||||
Command-line workflows for deploying and managing applications via [[argocd]].
|
||||
|
||||
## CLI Commands
|
||||
|
||||
```bash
|
||||
argocd app list # List all applications and sync status
|
||||
argocd app get <app> # Show app details, health, and resources
|
||||
argocd app diff <app> # Preview what would change on sync
|
||||
argocd app sync <app> # Apply pending changes
|
||||
argocd app sync apps # Sync the app-of-apps (picks up new Application manifests)
|
||||
```
|
||||
|
||||
## Login
|
||||
|
||||
```bash
|
||||
argocd login argocd.ops.eblu.me \
|
||||
--username admin \
|
||||
--password "$(op read 'op://vg6xf6vvfmoh5hqjjhlhbeoaie/srogeebssulhtb6tnqd7ls6qey/password')"
|
||||
```
|
||||
|
||||
## Branch-Testing Workflow
|
||||
|
||||
Test changes from a feature branch before merging:
|
||||
|
||||
```bash
|
||||
# 1. Point the app at your branch
|
||||
argocd app set <service> --revision <branch>
|
||||
|
||||
# 2. Sync to deploy the branch version
|
||||
argocd app sync <service>
|
||||
|
||||
# 3. Test the changes...
|
||||
|
||||
# 4. After merge, reset to main and sync
|
||||
argocd app set <service> --revision main
|
||||
argocd app sync <service>
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [[argocd]] — Service reference (URLs, credentials, sync policy)
|
||||
- [[apps]] — Full application registry
|
||||
- [[forgejo]] — Git source
|
||||
78
docs/reference/tools/dagger.md
Normal file
78
docs/reference/tools/dagger.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: Dagger
|
||||
modified: 2026-02-12
|
||||
tags:
|
||||
- reference
|
||||
- ci-cd
|
||||
- dagger
|
||||
---
|
||||
|
||||
# Dagger
|
||||
|
||||
Build engine for BlumeOps CI/CD pipelines. Replaces shell-based build scripts with Python functions that run identically locally and in CI.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Module** | `blumeops-ci` |
|
||||
| **Engine Version** | v0.19.11 |
|
||||
| **SDK** | Python |
|
||||
| **Source** | `.dagger/src/blumeops_ci/main.py` |
|
||||
| **Config** | `dagger.json` |
|
||||
|
||||
## Functions
|
||||
|
||||
| Function | Signature | Description |
|
||||
|----------|-----------|-------------|
|
||||
| `build` | `(src, container_name) → Container` | Build a container from `containers/<name>/Dockerfile` |
|
||||
| `publish` | `(src, container_name, version, registry?) → str` | Build and push to registry (default: `registry.ops.eblu.me`) |
|
||||
| `build_changelog` | `(src, version) → Directory` | Run towncrier to collect changelog fragments |
|
||||
| `build_docs` | `(src, version) → File` | Build changelog then Quartz site, return docs tarball |
|
||||
|
||||
## CLI Examples
|
||||
|
||||
```bash
|
||||
# Build a container
|
||||
dagger call build --src=. --container-name=devpi
|
||||
|
||||
# Drop into container shell for inspection
|
||||
dagger call build --src=. --container-name=devpi terminal
|
||||
|
||||
# Debug a failure interactively
|
||||
dagger call --interactive build --src=. --container-name=devpi
|
||||
|
||||
# Publish a container to zot
|
||||
dagger call publish --src=. --container-name=devpi --version=v1.1.0
|
||||
|
||||
# Build docs tarball locally
|
||||
dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz
|
||||
|
||||
# Debug a docs build failure
|
||||
dagger call --interactive build-docs --src=. --version=dev
|
||||
```
|
||||
|
||||
## Secrets
|
||||
|
||||
Dagger has a first-class `Secret` type — values are never logged or cached. Pass secrets from environment variables using the `env:VAR` syntax:
|
||||
|
||||
```bash
|
||||
dagger call release-docs \
|
||||
--src=. --version=v1.6.0 \
|
||||
--forgejo-token=env:FORGEJO_TOKEN \
|
||||
--argocd-token=env:ARGOCD_TOKEN
|
||||
```
|
||||
|
||||
In [[forgejo]] Actions, secrets are injected as env vars. Locally, mise tasks call `op read` to populate them.
|
||||
|
||||
## Caveats
|
||||
|
||||
- **Pre-1.0 API** — Current version is v0.19.x. Pin the CLI version and test upgrades on a branch before adopting.
|
||||
- **Privileged container** — The Dagger engine requires privileged container access. The Forgejo runner's DinD sidecar provides this.
|
||||
|
||||
## Related
|
||||
|
||||
- [[forgejo]] — CI/CD trigger layer
|
||||
- [[zot]] — Container registry (publish target)
|
||||
- [[docs]] — Documentation site (build target)
|
||||
- [[adopt-dagger-ci]] — Adoption plan (phases 1–3 complete)
|
||||
53
docs/reference/tools/pulumi.md
Normal file
53
docs/reference/tools/pulumi.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
title: Pulumi
|
||||
modified: 2026-02-12
|
||||
tags:
|
||||
- reference
|
||||
- iac
|
||||
- pulumi
|
||||
---
|
||||
|
||||
# Pulumi
|
||||
|
||||
Infrastructure-as-Code for DNS and Tailscale ACL management. Two independent projects, both using the Python SDK with uv toolchain.
|
||||
|
||||
## Projects
|
||||
|
||||
| Project | Stack | Source | Manages |
|
||||
|---------|-------|--------|---------|
|
||||
| `blumeops-dns` | `eblu-me` | `pulumi/gandi/` | DNS records for `eblu.me` via Gandi LiveDNS |
|
||||
| `blumeops-tailnet` | `tail8d86e` | `pulumi/tailscale/` | ACL policy, device tags, auth keys |
|
||||
|
||||
### DNS (`blumeops-dns`)
|
||||
|
||||
Manages `*.ops.eblu.me` wildcard and base records pointing to [[indri]]'s Tailscale IP, plus public CNAME records for services routed via [[flyio-proxy]].
|
||||
|
||||
### Tailnet (`blumeops-tailnet`)
|
||||
|
||||
Manages the ACL policy (`policy.hujson`), device tags for [[indri]] and [[sifaka]], and auth keys for the Fly.io proxy.
|
||||
|
||||
## CLI Patterns
|
||||
|
||||
All operations use mise tasks that wrap `pulumi` with the correct stack and working directory:
|
||||
|
||||
```bash
|
||||
# DNS
|
||||
mise run dns-preview # Preview DNS changes
|
||||
mise run dns-up # Apply DNS changes
|
||||
|
||||
# Tailscale
|
||||
mise run tailnet-preview # Preview ACL/tag changes
|
||||
mise run tailnet-up # Apply ACL/tag changes
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
- **Gandi**: `GANDI_PERSONAL_ACCESS_TOKEN` environment variable
|
||||
- **Tailscale**: `TAILSCALE_API_KEY` environment variable
|
||||
- **Pulumi state**: Local backend (no Pulumi Cloud)
|
||||
|
||||
## Related
|
||||
|
||||
- [[gandi]] — DNS hosting
|
||||
- [[tailscale]] — Tailnet configuration
|
||||
- [[routing]] — How DNS records map to services
|
||||
Loading…
Add table
Add a link
Reference in a new issue