L'auto-hébergement de Paperless-ngx sur k3s exige une gestion rigoureuse du stockage GitOps

Un guide technique récent décrit le processus d'auto-hébergement de Paperless-ngx, un système de gestion documentaire open source, sur un cluster Kubernetes k3s mono-nœud en appliquant les principes du GitOps. L'auteur, Dhiraj Shrotri, documente les étapes de configuration spécifiques et les procédures de dépannage nécessaires pour faire tourner l'application sur un mini PC Beelink doté d'un stockage externe, en insistant sur les risques associés à l'élagage automatique des ressources dans Flux.

Ce qui s'est passé

Le projet visait à remplacer les services de numérisation de documents basés sur le cloud par une alternative privée auto-hébergée offrant la reconnaissance optique de caractères (OCR) et la recherche basée sur le contenu. La pile technologique choisie consistait à exécuter Paperless-ngx sur k3s, une distribution Kubernetes légère, gérée par Flux pour la livraison continue GitOps. La configuration utilisait un mini PC Beelink avec un SSD interne pour la base de données et l'index de recherche, tandis qu'un disque dur externe hébergeait les fichiers de documents réels et les sauvegardes. Cette architecture permettait à l'utilisateur de scanner des documents via des applications mobiles comme Swift Paperless ou PaperNext, qui téléversaient ensuite les fichiers sur le serveur local pour traitement.

Une partie significative du guide se concentre sur les dangers liés à l'utilisation de prune: true dans les configurations Flux. En GitOps, ce paramètre garantit que les ressources supprimées du dépôt Git sont également effacées du cluster. Bien qu'utile pour nettoyer les déploiements, il représente un risque majeur pour les volumes de stockage persistant. Si une Demande de Volume Persistant (PVC) est accidentellement retirée du manifeste Git, Flux supprimerait le stockage sous-jacent, entraînant une perte de données permanente. Pour éviter cela, l'auteur a annoté l'espace de noms, les PVC, les Volumes Persistants (PV) et la StorageClass avec kustomize.toolkit.fluxcd.io/prune: disabled. Cette instruction indique à Flux de gérer ces ressources mais de ne jamais les supprimer, même si elles sont absentes du dépôt Git.

Le processus de déploiement a également révélé plusieurs pièges lors de l'amorçage. L'auteur a noté que flux bootstrap ne pousse pas les commits locaux existants vers le dépôt distant ; il ne pousse que ses propres fichiers système. Cela nécessite un flux de travail spécifique : pousser les modifications locales d'abord, exécuter l'amorçage sur le serveur, puis tirer les mises à jour vers la machine locale. De plus, des erreurs d'authentification sont apparues car Flux lisait un fichier kubeconfig obsolète provenant d'une installation MicroK8s précédente. La résolution de ce problème a nécessité la copie de la configuration k3s correcte depuis /etc/rancher/k3s/k3s.yaml vers l'emplacement standard ~/.kube/config.

Détails clés

• Sécurité du stockage : Annoter toutes les ressources Kubernetes liées au stockage avec kustomize.toolkit.fluxcd.io/prune: disabled pour empêcher Flux de supprimer les volumes de données lors des opérations de synchronisation.
• Exigences du système de fichiers : Les disques externes utilisés pour les volumes Kubernetes doivent être formatés en ext4, car NTFS et exFAT ne prennent pas en charge les permissions de propriété de fichiers Linux requises par les conteneurs.
• Flux de travail d'amorçage : Pousser les commits Git locaux avant d'exécuter flux bootstrap, puis tirer le dépôt sur la machine locale pour synchroniser les nouveaux fichiers système de Flux.
• Conflit de kubeconfig : S'assurer que Flux utilise le bon fichier kubeconfig k3s situé dans /etc/rancher/k3s/k3s.yaml pour éviter les erreurs d'autorité de certificat x509.
• Intégration mobile : Aucune application mobile officielle n'existe, mais des clients communautaires comme Swift Paperless (iOS) et PaperNext (Android/iOS) offrent des capacités de numérisation et de téléversement.
• Optimisation des ressources : Désactiver les liens de service via enableServiceLinks: false peut réduire le temps de démarrage et l'utilisation des ressources sur les clusters mono-nœuds.

Contexte

GitOps est un ensemble de pratiques où les configurations d'infrastructure et d'application sont gérées via des dépôts Git. Des outils comme Flux surveillent ces dépôts et appliquent automatiquement toute modification au cluster Kubernetes. Cette approche offre un contrôle de version, des pistes d'audit et une récupération automatisée de l'état de l'infrastructure. Cependant, elle introduit un modèle « déclaratif » où l'état du cluster doit toujours correspondre à l'état Git. Si un objet est supprimé de Git, les outils GitOps supposent qu'il doit être supprimé du cluster sauf indication contraire explicite.

Paperless-ngx est un système d'archivage de documents qui ingère les documents scannés, effectue une OCR pour rendre le texte consultable, et applique un étiquetage et un tri automatiques. Contrairement aux armoires classiques ou aux systèmes basés sur des dossiers comme Nextcloud, il organise les informations en fonction des métadonnées de contenu. Il repose sur plusieurs services backend, notamment PostgreSQL pour les métadonnées, Redis pour la mise en cache, ainsi qu'Apache Tika et Gotenberg pour le traitement de divers formats de fichiers tels que les documents Word et Excel.

Pourquoi c'est important

Pour les équipes et les individus gérant leur propre logiciel, l'intersection entre les applications à état et GitOps présente des défis opérationnels uniques. Les applications à état, telles que les systèmes de gestion documentaire ou les bases de données, dépendent d'un stockage persistant qui survit aux instances individuelles de conteneurs. Les boucles de réconciliation automatisées dans les outils GitOps peuvent involontairement détruire ces données persistantes si des garde-fous ne sont pas mis en place. Comprendre comment annoter les ressources pour les exclure de l'élagage est crucial pour maintenir l'intégrité des données dans les environnements automatisés.

De plus, la complexité de la mise en place d'un environnement auto-hébergé robuste sur du matériel basse consommation met en lumière les compromis entre contrôle et commodité. Bien que l'auto-hébergement offre la confidentialité et évite l'enfermement fournisseur, il nécessite une connaissance approfondie du réseau Kubernetes, des classes de stockage et de la gestion de configuration. Les erreurs dans les chemins kubeconfig ou les permissions de système de fichiers peuvent bloquer entièrement le déploiement, nécessitant une intervention manuelle qui va à l'encontre de l'objectif d'automatisation. Cette expérience souligne la nécessité de tests rigoureux et d'une documentation claire lors de la mise en œuvre de GitOps pour les charges de travail à état.

Que pouvez-vous faire

• Auditer les politiques d'élagage : Examiner tous les manifests Flux ou ArgoCD pour s'assurer que les Volumes Persistants et les Demandes sont protégés contre la suppression automatique grâce aux annotations appropriées.
• Vérifier la compatibilité du système de fichiers : Avant de monter un stockage externe sur les nœuds Kubernetes, confirmer que le disque est formaté avec un système de fichiers natif Linux comme ext4 ou XFS pour prendre en charge la gestion correcte des permissions.
• Standardiser les chemins kubeconfig : Vérifier les conflits de configurations Kubernetes sur les machines hôtes et s'assurer que les outils CI/CD et les CLI locaux pointent vers le fichier de configuration correct du cluster actif.
• Épingler les tags d'images de conteneurs : Éviter d'utiliser les tags :latest dans les dépôts GitOps de production pour prévenir les mises à niveau non intentionnelles lors des redémarrages de pods ; épingler plutôt des versions spécifiques et les mettre à jour via commit.
• Tester la restauration des sauvegardes : Vérifier régulièrement que les sauvegardes stockées sur des volumes externes peuvent être restaurées et que les montages de volumes persistent correctement après les redémarrages des nœuds.
• Désactiver les liens de service inutiles : Ajouter enableServiceLinks: false aux spécifications de pod dans les clusters mono-nœuds pour réduire la surcharge d'injection de variables d'environnement et accélérer l'initialisation des pods.