La documentación de un homelab suele fallar por exceso de ambición. Empiezas queriendo tenerlo todo ordenado, montas una wiki, haces un diagrama precioso, apuntas media red, creas una plantilla para servicios y durante tres días te sientes una persona seria. Luego cambias dos contenedores, mueves una VM, renuevas el proxy, se te olvida actualizar la wiki y ya tienes un museo de mentiras.
Por eso cada vez me gustan más los runbooks pequeños. Notas operativas, no documentación para presumir. Textos cortos que responden a una situación concreta: “no funciona DNS”, “no entra la VPN”, “el backup ha fallado”, “la VM no arranca”, “un disco está lleno”, “Home Assistant se ha quedado tonto”.
Un runbook casero no tiene que explicar toda la arquitectura. Tiene que ayudarte cuando algo cae y tú estás cansado. Esa es la prueba. Si la nota solo sirve cuando tienes tiempo, café y ganas, no es un runbook. Es literatura interna.
Por qué empecé a tomármelos en serio#
Durante mucho tiempo confié demasiado en la memoria. Sabía dónde corría cada cosa, qué contenedor dependía de qué base de datos, qué proxy apuntaba a qué puerto y qué servicio podía reiniciar sin romper nada. El problema es que esa información caduca. También caduca mi paciencia.
El homelab se toca a ratos. Una noche cambias DNS. Otro día pruebas un reverse proxy nuevo. Un sábado migras un servicio. Luego pasan tres semanas y algo falla. La configuración sigue ahí, pero el contexto se ha ido. ¿Por qué hice esto así? ¿Este volumen era importante? ¿Este contenedor se puede borrar? ¿Este servicio depende de una base de datos compartida?
La respuesta “ya me acordaré” envejece fatal.
Los runbooks me sirven para sacar de la cabeza las decisiones operativas. No intentan capturar todo. Capturan lo que duele olvidar. Y en un homelab con servicios reales, eso marca la diferencia entre arreglar algo en diez minutos o perder una noche excavando en tu propia arqueología técnica.
Qué debe tener un runbook útil#
Mi plantilla mental es sencilla. Cada runbook responde a seis preguntas:
- Qué síntoma estoy viendo.
- Qué servicios o equipos pueden estar implicados.
- Qué miro primero.
- Qué puedo reiniciar sin miedo.
- Qué no debo tocar a ciegas.
- Cómo vuelvo a una situación segura.
La clave está en el orden. Cuando algo falla, no quiero una explicación enciclopédica. Quiero una primera comprobación sensata. Después una segunda. Después una salida segura.
Por ejemplo, para DNS interno no empezaría explicando toda la teoría de resolución de nombres. Apuntaría algo así:
- Confirmar si falla en todos los dispositivos o solo en uno.
- Probar resolución contra el DNS interno y contra un resolver externo.
- Revisar si el contenedor o VM de DNS está activo.
- Revisar si el router está entregando el DNS correcto por DHCP.
- Si hace falta, cambiar temporalmente el cliente a un DNS externo.
- No tocar reglas de firewall hasta confirmar que el servicio DNS escucha.
Esto no es glamuroso. Esa es la gracia. Cuando todo arde, lo glamuroso estorba.
Runbooks para incidentes, no para servicios#
Una trampa habitual es documentar por servicio: “Página de Pi-hole”, “Página de Proxmox”, “Página de NAS”, “Página de Docker”. Eso está bien como inventario, pero para operar prefiero documentar por incidente.
Cuando internet “no funciona”, la persona que se queja no sabe si el problema es DNS, WiFi, fibra, firewall o el portátil. El runbook debería seguir el síntoma, no la herramienta.
Mis runbooks favoritos son de este estilo:
- No resuelve DNS en casa.
- No puedo entrar desde fuera.
- Un servicio web da error 502.
- El backup nocturno falla.
- Un disco o pool marca aviso.
- Una VM crítica no arranca.
- Un contenedor actualizó y rompió la app.
- La domótica responde lenta o no responde.
- El almacenamiento remoto no monta.
- El certificado de un servicio ha caducado.
Cada uno puede enlazar a documentación más larga si hace falta, pero el primer nivel tiene que ser operativo. Síntoma, diagnóstico, acciones seguras y plan de salida.
Esto encaja muy bien con un mantenimiento mensual de homelab, porque cada revisión suele descubrir incidentes recurrentes. Si algo lo miras dos veces, merece una nota. Si lo buscas tres veces, merece un runbook.
El runbook de backups es el primero que escribiría#
Si tuviese que elegir uno, empezaría por backups. No por Kubernetes, no por el proxy, no por el dashboard. Backups.
Un buen runbook de backups debería decir:
- Qué servicios tienen copia.
- Dónde está cada copia.
- Qué frecuencia tiene.
- Cómo comprobar el último resultado.
- Cómo restaurar un archivo pequeño.
- Cómo restaurar una base de datos.
- Qué credenciales hacen falta.
- Qué hacer si el destino está lleno.
- Qué datos no están cubiertos todavía.
La última línea duele, pero es necesaria. “Qué no está cubierto” es una de las notas más útiles que puedes escribir. Evita la mentira cómoda de pensar que todo está protegido porque hay una herramienta de backup instalada.
También pondría un apartado de restauración mínima. No hace falta restaurar todo el servidor en cada prueba, pero sí tener un camino conocido para recuperar algo pequeño. Si no has probado nunca una restauración, el runbook todavía es teoría.
El runbook de red te ahorra discusiones domésticas#
La red de casa tiene una característica preciosa: cuando falla, todo el mundo piensa que falla “internet”. Da igual que el problema sea DNS local, WiFi saturado, un túnel, el firewall o el proveedor. Para el usuario normal, no va.
Un runbook de red doméstica debería separar capas:
- ¿Hay conexión del operador?
- ¿El router responde?
- ¿El WiFi está activo?
- ¿Funciona por cable?
- ¿Resuelve DNS?
- ¿Hay salida a internet por IP directa?
- ¿Fallan solo los servicios internos?
- ¿Fallan solo los servicios publicados?
Esta separación evita tocar lo que no toca. Si puedes hacer ping a una IP externa pero no resolver nombres, no reinicies medio rack. Mira DNS. Si DNS funciona pero un servicio interno no carga, mira proxy o servicio. Si desde fuera no entras pero dentro sí, mira túnel, VPN o publicación.
También conviene apuntar una ruta de emergencia. Por ejemplo, cómo poner un cliente con DNS público temporal, cómo entrar por VPN alternativa o cómo acceder al panel del router si el DNS interno está muerto. No porque quieras vivir así, sino porque quieres recuperar control rápido.
El runbook de actualizaciones evita la ruleta#
Actualizar servicios en casa tiene un punto ridículo. Nadie te obliga, pero tú decides tocar una cosa que funciona porque hay una versión nueva. A veces sale bien. A veces te preguntas por qué no estarías viendo una serie como una persona normal.
El runbook de actualización no tiene que listar cada paquete. Tiene que definir una política:
- Qué servicios se actualizan automáticamente.
- Qué servicios requieren backup previo.
- Qué servicios requieren snapshot.
- Qué servicios conviene actualizar manualmente.
- Qué comprobación confirma que todo sigue bien.
- Cómo volver atrás.
Para contenedores con base de datos, añado siempre una comprobación posterior real. No basta con que el contenedor esté “up”. Tiene que cargar la web, iniciar sesión si aplica y mostrar datos recientes. Muchos fallos de actualización no se ven en el estado del contenedor.
También apunto ventanas malas. Si un servicio lo usa la familia por la noche, no lo actualizo justo antes de cenar. Si una app guarda fotos, documentos o contraseñas, no la actualizo sin copia reciente. Esto parece obvio hasta que una imagen nueva rompe una migración y te acuerdas tarde.
Qué no pongo en un runbook#
No pongo teoría larga. No pongo comandos que no entiendo. No pongo pasos destructivos sin una advertencia enorme. No pongo veinte alternativas si sé cuál uso de verdad.
Un runbook tiene que reducir opciones, no multiplicarlas. Si necesito una investigación profunda, enlazo a una nota técnica aparte. Pero el runbook principal debe ser corto y usable.
También intento evitar credenciales en texto plano. Puede parecer cómodo, pero es una mala costumbre. Prefiero apuntar dónde están guardadas, qué cuenta se usa y qué permisos necesita. Si el runbook acaba siendo una caja fuerte cutre, he mezclado problemas.
Y no documento cada comando exacto si depende mucho del entorno. Prefiero explicar la intención y dejar comandos genéricos solo cuando son seguros. En homelab hay demasiadas rutas, nombres de contenedores y volúmenes distintos. Copiar y pegar sin pensar es una forma elegante de romper cosas.
Formato simple que sí mantengo#
El formato que mejor me funciona es casi siempre este:
| |
Es feo, directo y útil. Perfecto.
Si quiero algo más cómodo, lo meto en una wiki, en Markdown dentro de un repositorio privado o en una carpeta sincronizada. Lo importante no es la herramienta. Lo importante es que pueda abrirlo cuando la red está medio rota. Por eso no pondría los únicos runbooks dentro de un servicio que depende del propio homelab para funcionar. Una copia local o exportada vale oro.
Cuándo automatizar y cuándo dejarlo escrito#
Hay pasos que deberían automatizarse. Comprobaciones de backup, alertas de espacio, certificados próximos a caducar, servicios caídos. Si una máquina puede mirarlo cada día, que lo mire.
Pero no todo debe ser automatización. Algunas decisiones necesitan contexto. Reiniciar un contenedor secundario puede ser automático. Restaurar una base de datos no. Cambiar DNS global no. Borrar snapshots antiguos sin revisar no, salvo que la política esté muy clara.
El runbook vive justo en ese punto medio. Ayuda a decidir qué hacer cuando la alerta llega. La automatización detecta. El runbook guía. Tú decides.
Esta separación evita otro problema clásico: scripts viejos haciendo cosas que ya no recuerdas. Si automatizo algo, también apunto qué hace, cuándo corre, dónde loguea y cómo se desactiva. Un cron misterioso es una bomba lenta con nombre de tarea.
La prueba del cansancio#
La mejor forma de evaluar un runbook es leerlo cuando no tienes ganas. Si exige demasiada concentración, falla. Si tiene párrafos enormes, falla. Si no deja claro qué es seguro y qué no, falla. Si depende de que recuerdes nombres internos, falla.
Un runbook bueno parece casi infantil:
- Mira esto.
- Si pasa esto, haz esto.
- Si no, mira esto otro.
- No toques esto sin backup.
- Para volver atrás, usa este camino.
Esa simplicidad no es falta de nivel. Es respeto por el momento en el que vas a necesitarlo.
Cómo empezaría hoy#
No intentaría documentar todo el homelab. Elegiría cinco incidentes:
- DNS no resuelve.
- No puedo entrar desde fuera.
- Backup fallido.
- Servicio web con error 502.
- Disco o almacenamiento casi lleno.
Con esos cinco ya cubres una parte enorme de los sustos domésticos. Después añadiría runbooks según dolor real. Si algo falla una vez y era obvio, quizá no hace falta. Si algo te hace perder una tarde, escribe la nota antes de olvidarlo.
El objetivo no es parecer una empresa. Es dejar pistas para el peor momento. Un homelab con buenos runbooks sigue siendo un laboratorio, pero deja de depender tanto de la memoria y del humor del día.
Y eso, aunque suene aburrido, es una mejora enorme. Porque cuando algo se rompe a las once de la noche, no necesitas una arquitectura perfecta. Necesitas una nota clara, una copia reciente y no tener que adivinar qué demonios pensabas hace tres meses.