El autoalojamiento de Paperless-ngx en k3s requiere un manejo cuidadoso del almacenamiento con GitOps

Una guía técnica reciente describe el proceso de autoalojar Paperless-ngx, un sistema de gestión documental de código abierto, en un clúster Kubernetes k3s de nodo único utilizando principios GitOps. El autor, Dhiraj Shrotri, documenta los pasos específicos de configuración y resolución de problemas necesarios para ejecutar la aplicación en un mini PC Beelink con almacenamiento externo, enfatizando los riesgos asociados con la poda automática de recursos en Flux.

Qué ocurrió

El proyecto tenía como objetivo reemplazar servicios de escaneo de documentos basados en la nube con una alternativa privada y autoalojada que ofrece reconocimiento óptico de caracteres (OCR) y búsqueda basada en contenido. La pila elegida implicaba ejecutar Paperless-ngx en k3s, una distribución ligera de Kubernetes, gestionada por Flux para la entrega continua GitOps. La configuración utilizó un mini PC Beelink con un SSD interno para la base de datos y el índice de búsqueda, mientras que un disco duro externo alojaba los archivos de documentos reales y las copias de seguridad. Esta arquitectura permitía al usuario escanear documentos mediante aplicaciones móviles como Swift Paperless o PaperNext, que luego subían los archivos al servidor local para su procesamiento.

Una parte significativa de la guía se centra en los peligros de usar prune: true en las configuraciones de Flux. En GitOps, esta configuración garantiza que los recursos eliminados del repositorio Git también se borren del clúster. Aunque es útil para limpiar despliegues, representa un riesgo grave para los volúmenes de almacenamiento persistente. Si una Solicitud de Volumen Persistente (PVC) se elimina accidentalmente del manifiesto Git, Flux borraría el almacenamiento subyacente, resultando en pérdida permanente de datos. Para prevenir esto, el autor anotó el namespace, las PVC, los Volúmenes Persistentes (PV) y la StorageClass con kustomize.toolkit.fluxcd.io/prune: disabled. Esta instrucción indica a Flux que gestione estos recursos pero nunca los elimine, incluso si faltan en el repositorio Git.

El proceso de despliegue también reveló varias trampas de bootstrap. El autor señaló que flux bootstrap no envía commits locales existentes al repositorio remoto; solo envía sus propios archivos de sistema. Esto requiere un flujo de trabajo específico: enviar primero los cambios locales, ejecutar bootstrap en el servidor y luego extraer las actualizaciones de vuelta a la máquina local. Además, surgieron errores de autenticación porque Flux leía un archivo kubeconfig obsoleto de una instalación anterior de MicroK8s. Resolver esto requirió copiar la configuración correcta de k3s desde /etc/rancher/k3s/k3s.yaml a la ubicación estándar ~/.kube/config.

Detalles clave

• Seguridad del almacenamiento: Anote todos los recursos de Kubernetes relacionados con el almacenamiento con kustomize.toolkit.fluxcd.io/prune: disabled para evitar que Flux elimine volúmenes de datos durante las operaciones de sincronización.
• Requisitos del sistema de archivos: Las unidades externas utilizadas para volúmenes de Kubernetes deben estar formateadas como ext4, ya que NTFS y exFAT no admiten los permisos de propiedad de archivos Linux requeridos por los contenedores.
• Flujo de trabajo de bootstrap: Envíe los commits locales de Git antes de ejecutar flux bootstrap, luego extraiga el repositorio en la máquina local para sincronizar los nuevos archivos de sistema de Flux.
• Conflicto de Kubeconfig: Asegúrese de que Flux utilice el archivo kubeconfig correcto de k3s ubicado en /etc/rancher/k3s/k3s.yaml para evitar errores de autoridad de certificación x509.
• Integración móvil: No existe una aplicación móvil oficial, pero clientes comunitarios como Swift Paperless (iOS) y PaperNext (Android/iOS) proporcionan capacidades de escaneo y subida.
• Optimización de recursos: Deshabilitar los enlaces de servicio mediante enableServiceLinks: false puede reducir el tiempo de inicio y el uso de recursos en clústeres de nodo único.

Antecedentes

GitOps es un conjunto de prácticas donde las configuraciones de infraestructura y aplicación se gestionan a través de repositorios Git. Herramientas como Flux monitorean estos repositorios y aplican automáticamente cualquier cambio al clúster Kubernetes. Este enfoque proporciona control de versiones, registros de auditoría y recuperación automatizada del estado de la infraestructura. Sin embargo, introduce un modelo "declarativo" donde el estado del clúster siempre debe coincidir con el estado de Git. Si un objeto se elimina de Git, las herramientas GitOps asumen que debe eliminarse del clúster a menos que se indique explícitamente lo contrario.

Paperless-ngx es un sistema de archivo de documentos que ingiere documentos escaneados, realiza OCR para hacer el texto buscable y aplica etiquetado y ordenamiento automáticos. A diferencia de los archivadores tradicionales o sistemas basados en carpetas como Nextcloud, organiza la información según metadatos de contenido. Depende de varios servicios backend, incluyendo PostgreSQL para metadatos, Redis para caché, y Apache Tika y Gotenberg para procesar diversos formatos de archivo como documentos Word y Excel.

Por qué importa

Para equipos e individuos que gestionan su propio software, la intersección entre aplicaciones con estado y GitOps presenta desafíos operativos únicos. Las aplicaciones con estado, como los sistemas de gestión documental o bases de datos, dependen de almacenamiento persistente que sobrevive a instancias individuales de contenedores. Los bucles de reconciliación automatizados en las herramientas GitOps pueden destruir inadvertidamente estos datos persistentes si no hay salvaguardas. Comprender cómo anotar recursos para excluirlos de la poda es crítico para mantener la integridad de los datos en entornos automatizados.

Además, la complejidad de configurar un entorno robusto autoalojado en hardware de bajo consumo destaca los compromisos entre control y conveniencia. Si bien el autoalojamiento ofrece privacidad y evita el bloqueo del proveedor, requiere un conocimiento profundo de redes Kubernetes, clases de almacenamiento y gestión de configuraciones. Errores en rutas de kubeconfig o permisos de sistema de archivos pueden detener completamente el despliegue, requiriendo intervención manual que derrota el propósito de la automatización. Esta experiencia subraya la necesidad de pruebas rigurosas y documentación clara al implementar GitOps para cargas de trabajo con estado.

Qué puede hacer

• Auditar políticas de poda: Revise todos los manifiestos de Flux o ArgoCD para asegurar que los Volúmenes Persistentes y Solicitudes estén protegidos contra la eliminación automática mediante anotaciones apropiadas.
• Verificar compatibilidad del sistema de archivos: Antes de montar almacenamiento externo en nodos Kubernetes, confirme que el disco esté formateado con un sistema de archivos nativo de Linux como ext4 o XFS para soportar el manejo adecuado de permisos.
• Estandarizar rutas de kubeconfig: Verifique conflictos de configuraciones de Kubernetes en máquinas host y asegúrese de que las herramientas CI/CD y las CLIs locales apunten al archivo de configuración correcto del clúster activo.
• Fijar etiquetas de imagen de contenedor: Evite usar etiquetas :latest en repositorios GitOps de producción para impedir actualizaciones no deseadas durante reinicios de pods; en su lugar, fije versiones específicas y actualícelas mediante commit.
• Probar restauración de backups: Verifique regularmente que los backups almacenados en volúmenes externos puedan restaurarse y que los montajes de volumen persistan correctamente tras reinicios de nodo.
• Deshabilitar enlaces de servicio innecesarios: Agregue enableServiceLinks: false a las especificaciones de pod en clústeres de nodo único para reducir la sobrecarga de inyección de variables de entorno y acelerar la inicialización del pod.