Cómo generar automáticamente la configuración de Homer Dashboard desde objetos Ingress en Kubernetes

Problema

En entornos de homelab con varios servicios expuestos mediante Ingress de Kubernetes, mantener actualizada la página de inicio de Homer Dashboard se vuelve tedioso. Cada nuevo Ingress implica agregar manualmente una tarjeta en el archivo config.yml de Homer, lo que genera:

• Inconsistencias entre lo que está realmente disponible y lo que muestra el portal.
• Retrasos para que los usuarios internos encuentren los servicios recién desplegados.
• Riesgo de errores tipográficos o de URL al copiar datos a mano.

El patrón que afecta a muchos administradores es la falta de sincronización automática entre los recursos de Kubernetes y la configuración estática de un panel de acceso.

Causa

1. Separación de fuentes – Ingress es gestionado por Helm/ArgoCD, mientras que Homer lee un archivo YAML estático. No hay vínculo declarativo entre ambos.
2. Ausencia de operador o controlador – Kubernetes no dispone por defecto de un controlador que convierta recursos Ingress en objetos de configuración de terceros.
3. Variabilidad de anotaciones – Los equipos suelen usar anotaciones personalizadas para describir iconos, grupos o etiquetas, pero sin un proceso que las interprete.
4. Escalado manual – Cada nuevo servicio requiere editar config.yml, lo que no escala cuando el número de Ingress supera decenas.

Estas causas aparecen en la mayoría de clústers de homelab que combinan Traefik, HAProxy o NGINX como ingress y un portal de acceso como Homer.

Solución

Implementar un operador que observe los objetos Ingress y genere la sección services del config.yml de Homer. La solución se divide en tres partes:

1. Definir un esquema de anotaciones que el operador leerá para rellenar los campos de Homer (título, descripción, icono, grupo).
2. Desplegar el operador (por ejemplo, el proyecto homer-operator disponible en GitHub) mediante Helm o kustomize.
3. Configurar un ConfigMap que el operador actualizará automáticamente; Homer lo monta como archivo de configuración.

1. Esquema de anotaciones

Ejemplo de Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: radarr
  annotations:
    homer/name: "Radarr"
    homer/description: "Gestor automático de películas"
    homer/icon: "film"
    homer/group: "Media"
spec:
  rules:
  - host: radarr.tld
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: radarr-svc
            port:
              number: 80

2. Despliegue del operador

El operador se instala como un Deployment que corre con privilegios de lectura sobre Ingress y escribe en un ConfigMap llamado homer-config. El manifiesto básico es:

kubectl apply -f https://raw.githubusercontent.com/arch-anes/homer-operator/main/deploy/operator.yaml

Opcionalmente, se pueden pasar parámetros de tolerancia a fallos o de intervalo de reconciliación mediante el ConfigMap homer-operator-config.

3. Montaje en Homer

El pod de Homer debe montar el ConfigMap como /etc/homer/config.yml. En el Helm chart de Homer, agrega:

extraVolumes:
  - name: homer-config
    configMap:
      name: homer-config
extraVolumeMounts:
  - name: homer-config
    mountPath: /etc/homer/config.yml
    subPath: config.yml

Con esto, cada vez que el operador detecta un Ingress nuevo o actualizado, recrea el ConfigMap y Homer recarga la página (Homer detecta cambios en el archivo y refresca automáticamente).

Cuándo aplicar esta solución

Aplica cuando:

• Tienes al menos 5 servicios expuestos mediante Ingress y deseas que el portal refleje automáticamente los cambios.
• Ya utilizas un gestor de GitOps (ArgoCD, Flux) y puedes versionar el ConfigMap generado.
• Necesitas una vista única para usuarios internos y deseas evitar edición manual de config.yml.

No aplica si:

• Solo manejas uno o dos servicios estáticos; el coste de operar el controlador supera el beneficio.
• Tu dashboard de acceso es otro producto que no permite montar un archivo de configuración externo.
• No puedes añadir anotaciones a los Ingress existentes (por ejemplo, en clústers gestionados donde no tienes control de metadatos).

Código

# 1. Instalar el operador
kubectl apply -f https://raw.githubusercontent.com/arch-anes/homer-operator/main/deploy/operator.yaml

# 2. Crear el ConfigMap vacío (el operador lo actualizará)
kubectl create configmap homer-config --from-literal=config.yml="services: []"

# 3. Añadir anotaciones a un Ingress existente (ejemplo Radarr)
kubectl annotate ingress radarr \
  homer/name="Radarr" \
  homer/description="Gestor automático de películas" \
  homer/icon="film" \
  homer/group="Media"

# 4. Verificar que el ConfigMap contiene la entrada generada
kubectl get configmap homer-config -o yaml | grep -A3 "Radarr"

Verificación

1. Revisar el ConfigMap: kubectl describe configmap homer-config. Debe contener una sección services con los campos name, subtitle, icon, url y group.
2. Acceder al panel: Abrir la URL de Homer en el navegador. La nueva tarjeta debe aparecer bajo el grupo indicado.
3. Cambiar una anotación: Modificar homer/description y observar que el panel se actualiza en menos de 30 s (intervalo de reconciliación por defecto).
4. Eliminar un Ingress: Borrar el recurso y confirmar que la tarjeta desaparece del ConfigMap y del UI.

Si alguna de estas etapas falla, revisar los logs del pod homer-operator:

kubectl logs -l app=homer-operator -c operator

Los mensajes indican si falta alguna anotación obligatoria o si ocurre un conflicto de nombres.

Notas adicionales

• Idempotencia – El operador sobrescribe la entrada completa por Ingress, por lo que cambios parciales (solo descripción) son seguros.
• Orden de grupos – Homer muestra los grupos en orden alfabético. Si deseas un orden específico, incluye un prefijo numérico en homer/group (ej. 01‑Media).
• Escalado – En clústers con cientos de Ingress, aumenta --reconcile-interval del operador para reducir la carga de la API.
• Seguridad – Las anotaciones son datos públicos; evita incluir credenciales o información sensible en ellas.
• Backup – El ConfigMap generado puede versionarse con GitOps; así cualquier cambio accidental se revierte fácilmente.

Con este enfoque, la configuración de Homer siempre refleja el estado real de los servicios expuestos, eliminando el trabajo manual y reduciendo errores de sincronización en cualquier homelab basado en Kubernetes.