Self-Hosting von Paperless-ngx auf k3s erfordert sorgfältige Handhabung der GitOps-Speicherung

Ein aktuelles technisches Handbuch skizziert den Prozess des Self-Hostings von Paperless-ngx, einem Open-Source-Dokumentenmanagementsystem, auf einem Single-Node-k3s-Kubernetes-Cluster unter Anwendung von GitOps-Prinzipien. Der Autor, Dhiraj Shrotri, dokumentiert die spezifischen Konfigurationsschritte und die erforderliche Fehlerbehebung, um die Anwendung auf einem Beelink-Mini-PC mit externem Speicher auszuführen, wobei er die Risiken im Zusammenhang mit automatisierter Ressourcenbereinigung in Flux betont.

Was passiert ist

Das Projekt zielte darauf ab, cloud-basierte Dokumentenscandienste durch eine private, selbst gehostete Alternative zu ersetzen, die optische Zeichenerkennung (OCR) und inhaltsbasierte Suche bietet. Der gewählte Stack sah vor, Paperless-ngx auf k3s, einer leichtgewichtigen Kubernetes-Distribution, laufen zu lassen, verwaltet durch Flux für GitOps Continuous Delivery. Das Setup nutzte einen Beelink-Mini-PC mit einer internen SSD für die Datenbank und den Suchindex, während eine externe Festplatte die eigentlichen Dokumentdateien und Backups hostete. Diese Architektur ermöglichte es dem Benutzer, Dokumente über mobile Apps wie Swift Paperless oder PaperNext zu scannen, die dann die Dateien zur Verarbeitung auf den lokalen Server hochluden.

Ein erheblicher Teil des Leitfadens konzentriert sich auf die Gefahren der Verwendung von prune: true in Flux-Konfigurationen. In GitOps stellt diese Einstellung sicher, dass Ressourcen, die aus dem Git-Repository entfernt werden, auch aus dem Cluster gelöscht werden. Obwohl dies nützlich ist, um Deployments aufzuräumen, birgt es ein schwerwiegendes Risiko für persistente Speichervolumes. Wenn eine PersistentVolume Claim (PVC) versehentlich aus dem Git-Manifest entfernt wird, würde Flux den zugrunde liegenden Speicher löschen, was zu dauerhaftem Datenverlust führt. Um dies zu verhindern, annotierte der Autor den Namespace, PVCs, PersistentVolumes (PVs) und StorageClass mit kustomize.toolkit.fluxcd.io/prune: disabled. Diese Anweisung teilt Flux mit, diese Ressourcen zu verwalten, sie aber niemals zu löschen, selbst wenn sie im Git-Repository fehlen.

Der Bereitstellungsprozess offenbarte zudem mehrere Bootstrap-Fallstricke. Der Autor stellte fest, dass flux bootstrap keine vorhandenen lokalen Commits in das Remote-Repository pusht; es werden nur seine eigenen Systemdateien gepusht. Dies erfordert einen spezifischen Workflow: Erst lokale Änderungen pushen, dann Bootstrap auf dem Server ausführen und anschließend die Updates zurück auf den lokalen Rechner pullen. Zusätzlich traten Authentifizierungsfehler auf, weil Flux eine veraltete kubeconfig-Datei aus einer früheren MicroK8s-Installation las. Die Lösung dieses Problems erforderte das Kopieren der korrekten k3s-Konfiguration von /etc/rancher/k3s/k3s.yaml an den Standardort ~/.kube/config.

Wichtige Details

• Speichersicherheit: Annotieren Sie alle speicherbezogenen Kubernetes-Ressourcen mit kustomize.toolkit.fluxcd.io/prune: disabled, um zu verhindern, dass Flux Datenvolumes während Synchronisierungsoperationen löscht.
• Dateisystemanforderungen: Externe Laufwerke, die für Kubernetes-Volumes verwendet werden, müssen als ext4 formatiert sein, da NTFS und exFAT die Linux-Dateibesitzberechtigungen nicht unterstützen, die von den Containern benötigt werden.
• Bootstrap-Workflow: Pushen Sie lokale Git-Commits, bevor Sie flux bootstrap ausführen, und pullen Sie anschließend das Repository auf dem lokalen Rechner, um die neuen Flux-Systemdateien zu synchronisieren.
• Kubeconfig-Konflikt: Stellen Sie sicher, dass Flux die richtige k3s-kubeconfig-Datei am Standort /etc/rancher/k3s/k3s.yaml verwendet, um x509-Zertifizierungsstellenfehler zu vermeiden.
• Mobile Integration: Es existiert keine offizielle mobile App, aber Community-Clients wie Swift Paperless (iOS) und PaperNext (Android/iOS) bieten Scan- und Upload-Funktionen.
• Ressourcenoptimierung: Das Deaktivieren von Service Links über enableServiceLinks: false kann die Startzeit und die Ressourcennutzung auf Single-Node-Clustern reduzieren.

Hintergrund

GitOps ist eine Reihe von Praktiken, bei denen Infrastruktur- und Anwendungskonfigurationen über Git-Repositories verwaltet werden. Tools wie Flux überwachen diese Repositories und wenden Änderungen automatisch auf den Kubernetes-Cluster an. Dieser Ansatz bietet Versionskontrolle, Audit-Trails und automatische Wiederherstellung des Infrastrukturzustands. Er führt jedoch ein „deklaratives“ Modell ein, bei dem der Clusterzustand immer mit dem Git-Zustand übereinstimmen muss. Wenn ein Objekt aus Git gelöscht wird, gehen GitOps-Tools davon aus, dass es auch aus dem Cluster gelöscht werden sollte, es sei denn, es wird explizit anders angewiesen.

Paperless-ngx ist ein Dokumentenarchivsystem, das gescannte Dokumente aufnimmt, OCR durchführt, um Text durchsuchbar zu machen, und automatische Tagging- und Sortierfunktionen anwendet. Im Gegensatz zu traditionellen Aktenschränken oder ordnerbasierten Systemen wie Nextcloud organisiert es Informationen basierend auf Inhaltsmetadaten. Es stützt sich auf mehrere Backend-Dienste, darunter PostgreSQL für Metadaten, Redis für Caching sowie Apache Tika und Gotenberg zur Verarbeitung verschiedener Dateiformate wie Word- und Excel-Dokumente.

Warum es wichtig ist

Für Teams und Einzelpersonen, die ihre eigene Software verwalten, stellt die Schnittstelle von zustandsbehafteten Anwendungen und GitOps einzigartige betriebliche Herausforderungen dar. Zustandsbehaftete Anwendungen, wie Dokumentenmanagementsysteme oder Datenbanken, verlassen sich auf persistenten Speicher, der einzelne Containerinstanzen überlebt. Automatische Reconciliation-Loops in GitOps-Tools können diesen persistenten Daten unwissentlich zerstören, wenn keine Schutzmaßnahmen vorhanden sind. Das Verständnis dafür, wie man Ressourcen annotiert, um sie von der Bereinigung auszuschließen, ist entscheidend für die Aufrechterhaltung der Datenintegrität in automatisierten Umgebungen.

Darüber hinaus verdeutlicht die Komplexität beim Aufbau einer robusten selbst gehosteten Umgebung auf Low-Power-Hardware die Abwägungen zwischen Kontrolle und Komfort. Während Self-Hosting Privatsphäre bietet und Vendor-Lock-in vermeidet, erfordert es tiefgreifende Kenntnisse in Kubernetes-Networking, Storage Classes und Konfigurationsmanagement. Fehler in kubeconfig-Pfaden oder Dateisystemberechtigungen können die Bereitstellung vollständig stoppen und manuelle Eingriffe erfordern, die den Zweck der Automatisierung zunichte machen. Diese Erfahrung unterstreicht die Notwendigkeit rigoroser Tests und klarer Dokumentation bei der Implementierung von GitOps für zustandsbehaftete Workloads.

Was Sie tun können

• Bereinigungsrichtlinien prüfen: Überprüfen Sie alle Flux- oder ArgoCD-Manifeste, um sicherzustellen, dass PersistentVolumes und Claims durch geeignete Annotationen vor automatischer Löschung geschützt sind.
• Dateisystemkompatibilität überprüfen: Bevor Sie externen Speicher an Kubernetes-Nodes mounten, bestätigen Sie, dass die Disk mit einem nativen Linux-Dateisystem wie ext4 oder XFS formatiert ist, um die korrekte Berechtigungsverwaltung zu unterstützen.
• Kubeconfig-Pfade standardisieren: Prüfen Sie auf widersprüchliche Kubernetes-Konfigurationen auf Host-Rechnern und stellen Sie sicher, dass CI/CD-Tools und lokale CLIs auf die korrekte Konfigurationsdatei des aktiven Clusters zeigen.
• Container-Image-Tags fixieren: Vermeiden Sie die Verwendung von :latest-Tags in produktiven GitOps-Repositories, um unbeabsichtigte Upgrades bei Pod-Neustarts zu verhindern; fixieren Sie stattdessen spezifische Versionen und aktualisieren Sie diese per Commit.
• Backup-Wiederherstellung testen: Verifizieren Sie regelmäßig, dass Backups, die auf externen Volumes gespeichert sind, wiederhergestellt werden können und dass die Volume-Mounts Node-Neustarts korrekt überstehen.
• Unnötige Service Links deaktivieren: Fügen Sie enableServiceLinks: false zu Pod-Specs in Single-Node-Clustern hinzu, um den Overhead der Umgebungsvariablen-Injektion zu reduzieren und die Pod-Initialisierung zu beschleunigen.