k3s/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a personal K3s Kubernetes cluster repository containing manifests and maintenance scripts for self-hosted services. The cluster runs on 3 nodes (vm120 master + vm121/vm122 workers) at 192.168.42.120.

Quick Connection

ssh ubuntu@192.168.42.120
sudo -i
cd /root/k8s

Git Workflow

1. Local edits happen in /Users/timmy/42_120/k8s/
2. Remote path on cluster: /root/k8s
3. Git repo: http://192.168.42.124:31337/timmy/k3s.git

After local changes:

git add -A && git commit -m "description" && git push
# Then on remote: git -C /root/k8s pull

Architecture

Ingress & Routing

• Traefik is the ingress controller
• Services exposed via Ingress with subdomains: <service>.lotimmy.com
• TLS is handled at the ingress level

Storage

• Longhorn provides persistent storage
• PVCs use Longhorn storage class for data persistence
• PVCs are NOT deleted by stop.sh - data is preserved

Naming Conventions

Manifests in each app's manifests/ directory are prefixed with numbers for ordering:

• 00-*.yaml - Middleware/config
• 01-*.yaml - Secrets
• 02-*.yaml - PVCs
• 03-*.yaml - Database deployments
• 04-*.yaml - Database services
• 05-*.yaml - App deployments
• 06-*.yaml - App services
• 07-*.yaml - Ingress

App Directory Structure

Each app in apps/ follows this structure:

apps/<appname>/
├── manifests/          # Kubernetes YAML files
├── deploy.sh           # Apply manifests and wait for rollout
├── stop.sh             # Delete Deployment/Service/Ingress (keeps PVC/Secret)
├── status.sh           # Show pods, services, PVC, ingress status
├── backup.sh           # Backup data to local backup/ directory
├── restore.sh          # Restore from backup (if available)
└── backup/             # Local backups (gitignored)

Common Commands

Deploy an app

cd apps/<appname>/
./deploy.sh

Check app status

cd apps/<appname>/
./status.sh

Stop an app (preserves data)

cd apps/<appname>/
./stop.sh

Cluster diagnostics

cd cluster/
./check_all.sh          # Run all diagnostics
./check_nodes.sh        # Node status
./check_storage.sh      # Longhorn volumes
./check_resources.sh    # Pod/Service/PVC summary

Manual kubectl

kubectl get pods -A
kubectl get ingress -A
kubectl get pvc -A
kubectl logs -f <pod-name>

Adding a New App

1. Copy the template: cp -r apps/template apps/your-app
2. Replace placeholders in manifests and scripts:
   • {{APP_NAME}} - app name
   • {{IMAGE}} - Docker image
   • {{TAG}} - version tag
   • {{PORT}} - container port
   • {{HOST}} - domain name
   • {{SIZE}} - storage size (e.g., 10Gi)
3. Make scripts executable: chmod +x apps/your-app/*.sh
4. Deploy: cd apps/your-app && ./deploy.sh

Deployed Services

App	Purpose	Ingress
CodiMD	Markdown collaborative notes	codimd.lotimmy.com
Opengist	Git snippets management	opengist.lotimmy.com
Vaultwarden	Password manager	vaultwarden.lotimmy.com
Adminer	Database management tool	adminer.lotimmy.com
PostgreSQL	General database service	Cluster-internal only

Important Notes

• Always run status.sh before making changes to understand current state
• PVCs are never deleted by stop.sh - data persists across deployments
• Secrets are stored in manifests - these are committed to git (private repo)
• Manifest ordering matters - use number prefixes for correct apply order
• Database apps (like CodiMD) include both app and database deployments