Address PR review feedback for Phase 3 tutorials
Tutorial changes: - Replace what-is-blumeops with adding-a-service tutorial - Update ai-assistance-guide with Mise Tasks table - Update contributing with tooling setup, target revisions, DNS preview - Remove AI-only sections from contributing and exploring-the-docs - Add replicator explanation to exploring-the-docs - Add pre-commit link validation note - Add Core Services phase to replication roadmap - Add docs service to services list in replicating-blumeops New reference cards: - docs.md - Quartz documentation service - tailscale-operator.md - Kubernetes ingress operator - ansible/roles.md - Available ansible roles Other updates: - Add mise to Brewfile - Update docs/index.md to link to exploring-the-docs - Add notes to update exploring-the-docs in future phases - Link tailscale-operator from apps.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
50046f42f8
commit
1e4e72b923
18 changed files with 620 additions and 120 deletions
47
docs/reference/ansible/roles.md
Normal file
47
docs/reference/ansible/roles.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: ansible-roles
|
||||
tags:
|
||||
- ansible
|
||||
- reference
|
||||
---
|
||||
|
||||
# Ansible Roles
|
||||
|
||||
Roles for provisioning services on [[indri]]. Run via `mise run provision-indri`.
|
||||
|
||||
## 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
|
||||
|
|
@ -31,6 +31,7 @@ Individual service reference cards with URLs and configuration details.
|
|||
| [[teslamate]] | Tesla data logger | k8s |
|
||||
| [[transmission]] | BitTorrent daemon | k8s |
|
||||
| [[zot]] | Container registry | indri |
|
||||
| [[docs]] | Documentation site (Quartz) | k8s |
|
||||
|
||||
## Infrastructure
|
||||
|
||||
|
|
@ -48,8 +49,15 @@ Cluster configuration and application registry.
|
|||
|
||||
- [[cluster | Cluster]] - Minikube specs, storage, networking
|
||||
- [[apps | Apps]] - ArgoCD application registry
|
||||
- [[tailscale-operator]] - Tailscale ingress for k8s services
|
||||
- [[external-secrets]] - Secrets management
|
||||
|
||||
## Ansible
|
||||
|
||||
Configuration management for [[indri]]-hosted services.
|
||||
|
||||
- [[reference/ansible/roles | Roles]] - Available ansible roles
|
||||
|
||||
## Storage
|
||||
|
||||
Network storage and backup configuration.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Registry of all applications deployed via [[argocd]].
|
|||
|-----|-----------|-------------|---------|
|
||||
| `apps` | argocd | `argocd/apps/` | App-of-apps root |
|
||||
| `argocd` | argocd | `argocd/manifests/argocd/` | [[argocd]] |
|
||||
| `tailscale-operator` | tailscale | `argocd/manifests/tailscale-operator/` | Tailscale k8s operator |
|
||||
| `tailscale-operator` | tailscale | `argocd/manifests/tailscale-operator/` | [[tailscale-operator]] |
|
||||
| `1password-connect` | 1password | `argocd/manifests/1password-connect/` | [[1password]] |
|
||||
| `external-secrets` | external-secrets | Helm chart | [[1password]] |
|
||||
| `external-secrets-config` | external-secrets | `argocd/manifests/external-secrets-config/` | [[1password]] |
|
||||
|
|
|
|||
40
docs/reference/kubernetes/tailscale-operator.md
Normal file
40
docs/reference/kubernetes/tailscale-operator.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: tailscale-operator
|
||||
tags:
|
||||
- kubernetes
|
||||
- tailscale
|
||||
---
|
||||
|
||||
# Tailscale Kubernetes Operator
|
||||
|
||||
The Tailscale operator enables Kubernetes services to be exposed directly on the Tailscale network via Ingress resources.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Namespace** | `tailscale` |
|
||||
| **Helm Chart** | `tailscale/tailscale-operator` |
|
||||
| **ArgoCD App** | `tailscale-operator` |
|
||||
|
||||
## How It Works
|
||||
|
||||
When you create an Ingress with `ingressClassName: tailscale`:
|
||||
|
||||
1. Operator provisions a Tailscale node for the service
|
||||
2. Service becomes accessible at `<hostname>.tail8d86e.ts.net`
|
||||
3. TLS is handled automatically via Tailscale
|
||||
|
||||
## Limitations
|
||||
|
||||
Services exposed via Tailscale Ingress are **not accessible** from:
|
||||
- Other Kubernetes pods (they're not Tailscale clients)
|
||||
- Docker containers on indri
|
||||
|
||||
For pod-to-service communication, use [[routing | Caddy]] (`*.ops.eblu.me`) instead.
|
||||
|
||||
## Related
|
||||
|
||||
- [[tailscale]] - Network configuration
|
||||
- [[routing]] - Service routing options
|
||||
- [[apps]] - Application registry
|
||||
49
docs/reference/services/docs.md
Normal file
49
docs/reference/services/docs.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: docs
|
||||
tags:
|
||||
- service
|
||||
- documentation
|
||||
---
|
||||
|
||||
# Docs (Quartz)
|
||||
|
||||
Documentation site built with [Quartz](https://quartz.jzhao.xyz/) and served via nginx.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **URL** | https://docs.ops.eblu.me |
|
||||
| **Namespace** | `docs` |
|
||||
| **Container** | `registry.ops.eblu.me/blumeops/quartz:v1.0.0` |
|
||||
| **Source** | `docs/` directory in blumeops repo |
|
||||
| **Build** | Forgejo workflow `build-blumeops.yaml` |
|
||||
|
||||
## Architecture
|
||||
|
||||
1. **Source**: Markdown files in `docs/` with Obsidian-compatible wiki-links
|
||||
2. **Build**: Forgejo workflow builds Quartz static site on push to main
|
||||
3. **Release**: Built assets published as Forgejo release attachments
|
||||
4. **Deploy**: Container downloads release bundle on startup, serves via nginx
|
||||
|
||||
## Release Process
|
||||
|
||||
Documentation is automatically built and released when changes are pushed to main:
|
||||
|
||||
1. Workflow detects changes in `docs/` directory
|
||||
2. Quartz builds static HTML/CSS/JS
|
||||
3. Assets uploaded as release attachment
|
||||
4. ArgoCD deployment updated with new `DOCS_RELEASE_URL`
|
||||
5. Pod restarts and downloads new bundle
|
||||
|
||||
## Configuration
|
||||
|
||||
- **Quartz config**: `quartz.config.ts`
|
||||
- **Layout**: `quartz.layout.ts`
|
||||
- **ArgoCD app**: `argocd/apps/docs.yaml`
|
||||
- **Manifests**: `argocd/manifests/docs/`
|
||||
|
||||
## Related
|
||||
|
||||
- [[argocd]] - Deployment management
|
||||
- [[forgejo]] - Build workflows
|
||||
Loading…
Add table
Add a link
Reference in a new issue