Add Docker Registry configuration for k8s-server with TLS and authentication

2025-12-16 10:47:15 +01:00
parent a83976c615
commit dd943ffd16
6 changed files with 310 additions and 0 deletions
@@ -115,6 +115,117 @@ Access examples:
 - Permissions: ensure `/data/daten` and `/data/daten/share` exist and are writable (`systemd-tmpfiles` creates them)
 - Firewall: SMB ports 139/445 are open by module config

+---
+
+## K8s-Server: Docker Registry
+
+The k8s-server runs a private Docker Registry v2 with self-signed TLS certificate. Authentication is handled by Caddy for external access.
+
+**Access:**
+- External URL: `https://registry.home.lindenfelser.de` (authenticated via Caddy)
+- Internal URL: `https://10.202.82.7:5000` (direct, no auth - K8s pods)
+- Default credentials: `admin` / `changeme` (Caddy basic auth)
+- Storage: `/var/lib/docker-registry` (root partition)
+
+### 1) Login from external machine
+
+```bash
+# Login to registry
+docker login registry.home.lindenfelser.de
+# Username: admin
+# Password: changeme
+```
+
+### 2) Push an image
+
+```bash
+# Tag your image
+docker tag myapp:latest registry.home.lindenfelser.de/myapp:latest
+
+# Push to registry
+docker push registry.home.lindenfelser.de/myapp:latest
+```
+
+### 3) Pull from Kubernetes pods
+
+The k8s cluster is configured to authenticate automatically. Create a deployment:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myapp
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: myapp
+  template:
+    metadata:
+      labels:
+        app: myapp
+    spec:
+      containers:
+      - name: myapp
+        image: registry.home.lindenfelser.de/myapp:latest
+```
+
+### 4) Change registry password
+
+Authentication is handled by Caddy. Generate new password hash and update:
+
+```bash
+# Generate new password hash locally
+caddy hash-password --plaintext 'yournewpassword'
+```
+
+Then update the hash in [modules/gateway.nix](modules/gateway.nix) in the `basicauth` section and redeploy:
+
+```bash
+make deploy-gateway
+```
+
+### 5) Monitor storage usage
+
+Check daily storage logs:
+
+```bash
+# View growth tracking
+sudo journalctl -u docker-registry-growth-tracker
+
+# View last 30 days of size tracking
+sudo tail -n 30 /var/log/docker-registry-growth.log
+
+# Check current usage
+sudo du -sh /var/lib/docker-registry
+df -h /
+```
+
+### 6) Manual garbage collection
+
+Garbage collection runs automatically every Sunday at 03:00. To run manually:
+
+```bash
+sudo systemctl start docker-registry-garbage-collect
+sudo journalctl -u docker-registry-garbage-collect -e
+```
+
+### 7) List images in registry
+
+```bash
+# List all repositories
+curl -u admin:changeme https://registry.home.lindenfelser.de/v2/_catalog
+
+# List tags for a specific image
+curl -u admin:changeme https://registry.home.lindenfelser.de/v2/myapp/tags/list
+```
+
+### Troubleshooting
+- **TLS certificate errors**: Registry uses self-signed certificate. External Docker clients need to add to insecure registries or install the cert
+- **Authentication fails**: Verify Caddy basicauth configuration in [modules/gateway.nix](modules/gateway.nix). K8s pods access registry directly without auth.
+- **Storage full**: Check root partition usage with `df -h /` and run garbage collection
+- **K8s pods can't pull**: Verify `registries.yaml` points to internal registry (10.202.82.7:5000) and restart k3s: `sudo systemctl restart k3s`
+
 ````

 ---