eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions

Add Kubernetes migration plan documentation #24

Merged
eblume merged 21 commits from feature/k8s-migration-plan into main 2026-01-17 17:34:54 -08:00
Conversation 0 Commits 21 Files changed 2 +1220
eblume commented 2026-01-17 13:12:50 -08:00
Owner
Copy link

Summary

  • Comprehensive phased plan for migrating blumeops services to minikube
  • Technical decisions documented: Zot registry, Podman driver, CloudNativePG, Tailscale Operator
  • 9 migration phases with verification and rollback procedures
  • LaunchAgent absolute path requirements documented
  • Observability requirements (zk docs, logging, metrics, dashboards) for new services

Deployment and Testing

  • Plan document created at docs/k8s-migration.md
  • Review plan phases for completeness
  • Validate technical decisions align with requirements

🤖 Generated with Claude Code

## Summary - Comprehensive phased plan for migrating blumeops services to minikube - Technical decisions documented: Zot registry, Podman driver, CloudNativePG, Tailscale Operator - 9 migration phases with verification and rollback procedures - LaunchAgent absolute path requirements documented - Observability requirements (zk docs, logging, metrics, dashboards) for new services ## Deployment and Testing - [x] Plan document created at `docs/k8s-migration.md` - [x] Review plan phases for completeness - [x] Validate technical decisions align with requirements 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Comprehensive phased plan for migrating blumeops services from direct
hosting on indri to a minikube cluster. Documents technical decisions
(Zot registry, Podman driver, CloudNativePG, Tailscale Operator) and
9 migration phases with verification and rollback procedures.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add 16 numbered steps with specific files, code, and testing commands
- Add Tailscale service creation order warning (must create in admin
  console BEFORE running tailscale serve)
- Add comprehensive verification checklist and rollback procedures
- Document indri-services-check updates for zot and minikube
- Include zk documentation templates

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Brewfile is for development tooling on gilbert, not for indri services.
Ansible roles handle homebrew installations on indri directly.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Use 'grants' not 'acls' (that's the newer format)
- Show exact line numbers and locations for each change
- Include tagOwners, grants, and tests sections
- Follow existing pattern with tag:blumeops in tagOwners

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Registry access restricted to admins (who already have full access).
Members don't need to push/pull container images.
K8s accesses registry locally on indri, not via Tailscale.
Added note about Zot htpasswd auth for future reference.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
K8s workloads (like Woodpecker CI) need to push/pull images from Zot.
They'll get Tailscale identity via the operator (Phase 1) with tag:k8s.
Added grant and test case for tag:k8s → tag:registry access.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Added Zot config.json template showing sync extension for pull-through
- Documented namespace convention:
  - registry.../docker.io/* → cached from Docker Hub
  - registry.../ghcr.io/* → cached from GHCR
  - registry.../blumeops/* → private images
- Added testing steps for both pull-through and private push
- Updated zk template with namespace table and build/push commands
- Updated verification checklist

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Zot isn't in homebrew. Following existing pattern (like kiwix-tools),
clone to ~/code/3rd/zot on indri and build with 'make binary'.
Updated defaults and LaunchAgent template to use built binary path.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Updated Step 0.3 to clone zot from forge mirror instead of GitHub
- Added "Third-Party Projects" section to CLAUDE.md explaining:
  - Ask user to mirror 3rd party repos to forge first
  - Clone from mirror to ~/code/3rd/
  - Avoids external dependencies

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
mcquack is Erich's own project, not a third-party mirror.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Use localhost:3001 for forge clone (hairpinning limitation)
- Document mise go@1.25 setup in repo directory
- Correct build command: mise x -- make binary
- Mark prerequisites as already completed with verification

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update to match Phase 0 details:
- Built from source, not homebrew
- Config at ~/.config/zot/config.json
- Data at ~/zot/
- Binary path documented

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove tag:k8s from Phase 0 Step 0.1 (not needed until Tailscale
  Kubernetes Operator is deployed)
- Add tag:k8s ACL setup as new Step 1 in Phase 1
- Clarify Step 0.10: no special Tailscale service needed for K8s API
  (admin wildcard grant covers it)
- Add sed commands to replace localhost with indri in kubeconfig

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Config template and namespace docs now match defaults/main.yml

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
registry.tail8d86e.ts.net isn't available until tailscale serve
is configured in Step 0.4. Keep localhost tests in Step 0.3.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Ansible handler restarts alloy automatically when config changes

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename docs/k8s-migration.md to plans/k8s-migration.md
- Create plans/completed/ for finished plans
- Add Plan Completion section with instructions to archive when done

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Use 'started successfully' instead of just 'started' for changed_when
- Use specific failed_when: rc not in [0, 125] instead of false
- 125 = already exists (init) or already running (start)

Tested manually on indri - podman machine initialized and running.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add manual step for enabling NFS on Synology DSM
- Document NFS permissions config for k8s-volumes share
- Include verification commands for testing NFS mount
- Bump minikube disk-size from 100g to 200g
- Add note explaining storage options (hostPath, NFS, SMB)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Nothing in Phase 0 requires NFS, and it's per-share config anyway.
Will add when actually needed.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Bump podman disk-size to 220G (> minikube's 200G)
- Fix Step 0.3 test to use curl instead of podman (not installed yet)
- Simplify Step 0.5 zot metrics to just zot_up for now
- Add Backup Strategy section to Technical Decisions
- Add zot restart handler to Step 0.3
- Move dashboard steps to Phase 0 Follow-up section
- Renumber steps (0.14->0.12, 0.15->0.13)
- Fix Modified Files Summary (tag:k8s deferred to Phase 1)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
eblume merged commit c8433467c1 into main 2026-01-17 17:34:54 -08:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
eblume/blumeops!24
No description provided.