Resumen — Dos servidores de Minecraft (Fabric con mods + Paper vanilla) corriendo en un cluster k3s de un solo nodo. Un CronJob personalizado revisa RCON cada 5 minutos; si no hay jugadores conectados durante 30 minutos consecutivos, ejecuta
save-ally escala el deployment a cero. El operador lo reactiva conkubectl scale --replicas=1. Resultado neto: ~8 GB de RAM recuperados cuando nadie está jugando.
Un pequeño cluster privado de gaming tenía dos servidores Java corriendo 24/7 para un grupo reducido de amigos. Los heaps de la JVM están fijados a 4 GB cada uno; el RSS real rondaba 3.2 GB para el servidor de Fabric con mods y 4.7 GB para el servidor vanilla con Paper — llámalo 8 GB de RAM constante que no servía para nada durante el 95% del día en que nadie estaba conectado.
Este documento describe el sistema que apaga esos pods automáticamente cuando se quedan inactivos y los vuelve a prender cuando alguien quiere jugar.
graph TD
subgraph k3s["cluster k3s (un solo nodo, 31 GB RAM)"]
subgraph mc_ns["namespace: games-minecraft"]
subgraph mods["Deployment: mc-mods-minecraft (Fabric 1.21.4)"]
mods_pod["Pod<br/>-Xmx4G -Xms4G<br/>RCON :25575<br/>Juego :25565"]
mods_pvc["PVC: 20 Gi<br/>(world + mods)"]
mods_pod --- mods_pvc
end
subgraph vanilla["Deployment: mc-vanilla-minecraft (Paper 1.21.4)"]
vanilla_pod["Pod<br/>-Xmx4G -Xms4G<br/>RCON :25575<br/>Juego :25565"]
vanilla_pvc["PVC: 1 Gi<br/>(world)"]
vanilla_pod --- vanilla_pvc
end
subgraph webclient["Deployment: mc-web-client"]
web_pod["Pod de UI web<br/>(server browser + RCON)"]
end
subgraph cp["Plano de control"]
rbac["ServiceAccount<br/>+ Role + RoleBinding<br/>(mc-idle-detector)"]
cm_scripts["ConfigMap<br/>mc-idle-scripts<br/>(idle_detector.py)"]
cm_state["ConfigMap<br/>mc-idle-state<br/>(contador por servidor)"]
cj_mods["CronJob */5 * * * *<br/>mc-mods-idle-detector"]
cj_vanilla["CronJob */5 * * * *<br/>mc-vanilla-idle-detector"]
cj_backup_mods["CronJob 0 */6 * * *<br/>mc-mods-backup"]
cj_backup_vanilla["CronJob 0 */6 * * *<br/>mc-vanilla-backup"]
end
subgraph secrets["Secrets"]
sec_mods["mc-mods-minecraft-rcon<br/>(contraseña)"]
sec_vanilla["mc-vanilla-minecraft-rcon<br/>(contraseña)"]
end
cj_mods --> cm_scripts
cj_mods --> cm_state
cj_mods --> rbac
cj_mods --> mods_pod
cj_mods --> sec_mods
cj_vanilla --> cm_scripts
cj_vanilla --> cm_state
cj_vanilla --> rbac
cj_vanilla --> vanilla_pod
cj_vanilla --> sec_vanilla
cj_backup_mods --> mods_pvc
cj_backup_vanilla --> vanilla_pvc
end
subgraph host["Nodo (hostPath)"]
backups["/var/backups/minecraft/<br/>mc-{mods,vanilla}/*.tar.gz<br/>(retención 7 días)"]
end
cj_backup_mods -. escribe .-> backups
cj_backup_vanilla -. escribe .-> backups
end
player["Jugador (cliente Minecraft)"] -->|TCP 25565| mods_pod
player -->|TCP 25565| vanilla_pod
player -->|HTTP 80| web_pod
operator["Operador"] -->|kubectl scale --replicas=1| mods
operator -->|kubectl scale --replicas=1| vanilla
Los dos deployments de Minecraft más el cliente web viven en un único
namespace de k3s. Los componentes del plano de control (CronJobs, ConfigMaps,
Secrets, RBAC) están al lado. El filesystem del nodo se monta dentro de los
CronJobs de respaldo para que los tarballs caigan en
/var/backups/minecraft/<servidor>/ y sobrevivan incluso si se borra el
namespace.
Un cluster k3s de un solo nodo corre todo. Se eligió k3s sobre Kubernetes completo porque:
- El cluster cabe en un solo VPS — plano de control + workloads comparten un mismo host.
- Trae
local-pathStorageClass integrado, que mapea PVCs a hostPath, que es exactamente el nivel de durabilidad que queremos para los mundos de Minecraft (sin dependencia de un sistema de archivos de red). metrics-serverviene incluido desde el arranque.- El firewall de salida es suficientemente permisivo para que
itzg/minecraft-serverjale imágenes de registros, pero suficientemente restrictivo como para que bajar binarios externos al iniciar el pod (por ejemplo,kubectldesdedl.k8s.io) falle — mira la sección "Por qué API REST en lugar de kubectl" más abajo.
Se eligió la imagen Docker itzg/minecraft-server
porque:
- Soporta Fabric, Paper, Forge, Vanilla, Spigot mediante la variable
TYPE. - Expone RCON en un puerto configurable con
ENABLE_RCON=true. - Incluye un script
mc-healthque pingea el puerto del juego — perfecto paralivenessProbe/readinessProbeen k8s. - El chart de Helm
minecraftenvuelve la imagen con todas las variables de entorno, probes y PVCs correctos.
Los deployments de Minecraft se manejan con Helm (helm install mc-mods itzg/minecraft --version 5.1.3),
porque el chart maneja muchos detalles chicos (security context, lifecycle
hooks, fijado de versión). El detector de inactividad se entrega como
manifests crudos de Kubernetes porque no encaja en el modelo de plantillas
del chart — es pegamento por namespace, no una app reutilizable.
El HPA nativo escala por CPU/memoria (vía metrics-server) o por métricas
personalizadas (vía Prometheus adapter). Para este caso, ambos se quedan
cortos:
- Las métricas de CPU/memoria mienten. La JVM se queda en 35–72 millicores cuando está inactiva. Escalar por CPU nunca dispararía. Escalar por memoria solo dispararía cuando la JVM está bajo carga — al revés de lo que queremos.
- Las métricas personalizadas requieren un stack. El Prometheus adapter es una dependencia considerable solo para contar jugadores de Minecraft. La información que necesitamos está a un comando RCON de distancia.
minReplicas: 0no se lleva bien con un Service ClusterIP. Cuando el conteo de pods baja a cero, kube-proxy quita los endpoints del Service, y cualquier conexión TCP entrante se rechaza de inmediato. Para tener escalado-desde-cero transparente necesitas el proxy TCP de KEDA o un shim personalizado — mira "Trabajo futuro" más abajo.
Entonces escribimos un CronJob chiquito que hace lo correcto para esta carga de trabajo.
sequenceDiagram
autonumber
participant Cron as CronJob<br/>(cada 5 min)
participant API as API k8s<br/>(REST)
participant CM as ConfigMap<br/>mc-idle-state
participant RCON as Minecraft<br/>:25575
participant Dep as Deployment
Cron->>API: GET deployment/scale
API-->>Cron: replicas=1
Cron->>CM: GET mc-idle-state
CM-->>Cron: {runs: 5, replicas: 1, ...}
Cron->>RCON: AUTH + LIST
RCON-->>Cron: "There are 0 of a max of 20..."
alt necesita scale-down
Note over Cron,rcon: runs ≥ 6 (30 min inactivo)<br/>Y replicas > 0
Cron->>RCON: save-off
Cron->>RCON: save-all flush
Cron->>RCON: save-on
Cron->>API: PATCH deployment/scale {replicas: 0}
API-->>Cron: 200 OK
Cron->>CM: PATCH estado {replicas: 0, runs: 6}
else se detectó scale-up manual
Note over Cron: estado.replicas=0 pero live>0
Cron->>CM: PATCH estado {runs: 0, last_active_at: ahora}
else sigue inactivo, contando
Cron->>CM: PATCH estado {runs: 6, replicas: 1}
end
El script es un solo archivo de Python de 200 líneas que:
- Lee el conteo de réplicas en vivo del subrecurso
/scaledel deployment (es la fuente de verdad — el estado del ConfigMap puede divergir). - Lee el estado persistente del
ConfigMap/mc-idle-state. - Si el estado dice
replicas: 0pero el deployment en realidad tiene réplicas corriendo, significa que el operador hizokubectl scale --replicas=1a mano. El controlador resetea el contador de inactividad a cero para que el servidor recién despertado tenga sus 30 minutos completos de gracia. - Envía un comando RCON
listautenticado al servidor. - Si está inactivo (o no se puede conectar, lo cual tratamos como "ya
estaba escalado a cero"), incrementa el contador de corridas consecutivas.
Si el contador cruza el umbral (por defecto 6 corridas = 30 minutos),
envía
save-off+save-all flush+save-on, y luego aplica PATCH al scale del deployment para ponerlo en cero. - Persiste el nuevo estado de vuelta al ConfigMap.
def _packet(req_id, pkt_type, payload):
body = struct.pack("<ii", req_id, pkt_type) + payload.encode() + b"\x00"
if pkt_type == 3: # login
body += b"\x00"
return struct.pack("<i", len(body)) + body
def rcon_command(host, port, password, command, timeout=10):
sock = socket.create_connection((host, port), timeout=timeout)
sock.settimeout(timeout)
try:
sock.sendall(_packet(1, 3, password)) # auth
time.sleep(0.1)
sock.sendall(_packet(2, 2, command)) # comando
sock.settimeout(2.0)
# el servidor puede concatenar la respuesta de auth + comando;
# drena ambos
buf, last_payload = b"", ""
while time.time() < deadline:
chunk = sock.recv(4096)
if not chunk: break
buf += chunk
while len(buf) >= 4:
length = struct.unpack("<i", buf[:4])[0]
if len(buf) < 4 + length: break
pkt = buf[4:4 + length]; buf = buf[4 + length:]
last_payload = pkt[8:].rstrip(b"\x00").decode()
return last_payload
finally:
sock.close()Sin dependencias externas — solo socket y struct. Referencia:
wiki.vg/RCON.
El cluster tiene la salida restringida: bajar kubectl desde dl.k8s.io al
arrancar el pod falla con 404. En lugar de empacar un binario en una imagen
sidecar, el script del controlador habla directamente con el API de Kubernetes
usando urllib.request más el token de la service account montado en
/var/run/secrets/kubernetes.io/serviceaccount/token. El certificado CA en
/var/run/secrets/.../ca.crt se carga en el contexto SSL para que el
certificado autofirmado del API server de k3s verifique bien.
ctx = ssl.create_default_context()
ctx.load_verify_locations("/var/run/secrets/kubernetes.io/serviceaccount/ca.crt")
req = urllib.request.Request(
f"{API_BASE}/apis/apps/v1/namespaces/games-minecraft/deployments/{name}/scale",
data=json.dumps({"spec": {"replicas": 0}}).encode(),
method="PATCH",
headers={"Authorization": f"Bearer {token}",
"Content-Type": "application/strategic-merge-patch+json"},
)
urllib.request.urlopen(req, context=ctx)Todo el controlador corre en un contenedor Alpine de 50 MB con Python — sin binario de kubectl, sin curl, sin jq.
Un CronJob separado corre cada 6 horas por servidor. Hace lo siguiente:
- Envía
save-offpor RCON para desactivar el auto-save. - Envía
save-all flushy espera a que termine. - Empaqueta
world/,mods/,config/,server.propertiesy los distintos archivos JSON de apoyo en un archivo tar.gz. - Verifica el archivo (un smoke test rápido con
tar -tzf) antes de ponerlo en su lugar. - Envía
save-onpara reactivar el auto-save. - Limpia los tarballs con más de 7 días de antigüedad.
Los tarballs caen en el hostPath del nodo en
/var/backups/minecraft/<servidor>/, lo cual significa que sobreviven al
borrado del namespace, a reconstrucciones del cluster y a helm uninstall.
Integridad verificada listando algunos:
mc-mods-2026-07-22T18-00-23Z.tar.gz 14 MB
mc-mods-2026-07-22T21-15-31Z.tar.gz 14 MB ← snapshot manual antes del cambio
mc-vanilla-2026-07-22T21-15-27Z.tar.gz
El ConfigMap mc-idle-state guarda un documento JSON por servidor:
{
"first_idle_at": "2026-07-22T21:52:37Z",
"last_active_at": null,
"consecutive_idle_runs": 6,
"replicas": 0
}Esto es suficiente para reconstruir el ciclo de vida de cualquier pod: cuándo
tuvo jugadores por última vez, cuándo quedó inactivo, cuánto tiempo estuvo
así, y en qué estado de escala está. Combinado con el kubectl describe y
kubectl logs estándar, cada evento de scale-down deja un rastro de auditoría
completo:
[2026-07-22T21:53:09Z] loaded state: {runs: 1, replicas: 1, ...}
[2026-07-22T21:53:11Z] rcon-idle-check: status=idle players=0
[2026-07-22T21:53:11Z] scale-down triggered: runs=2 >= 1
[2026-07-22T21:53:11Z] running save-all before scale-down
[2026-07-22T21:53:18Z] save-all OK
[2026-07-22T21:53:18Z] scaling mc-mods-minecraft to 0 replicas
[2026-07-22T21:53:18Z] state updated: {runs: 2, replicas: 0}
La ServiceAccount mc-idle-detector solo tiene permiso para:
get/patch/updatedel subrecursoscalede los dos deployments de Minecraftget/patch/updatedel ConfigMapmc-idle-state
Nada más. No pods/exec, no lectura de secrets, no verbos amplios. Si el
pod del controlador se ve comprometido, el radio de impacto es "los dos
servidores de juego se pueden escalar en un momento extraño".
Medido en un cluster k3s de un solo nodo (Debian 12, 31 GB RAM, otros 18 procesos PM2 compitiendo por memoria):
| Estado | RSS antes | RSS después | Δ |
|---|---|---|---|
mc-mods-minecraft corriendo, inactivo |
3.2 GB | — | — |
mc-mods-minecraft escalado a 0 |
— | 0 | −3.2 GB |
mc-vanilla-minecraft corriendo, inactivo |
4.7 GB | — | — |
mc-vanilla-minecraft escalado a 0 |
— | 0 | −4.7 GB |
| Los dos escalados a 0 | 8 GB | 0 | −8 GB |
Esta es memoria que las otras cargas del host (stacks de correo, dashboards, runners de build, plataformas sociales) sí pueden usar. En un host de 31 GB con ~10 GB ya comprometidos por otros servicios, recuperar 8 GB cambia la historia de headroom de "apretado" a "cómodo".
El costo en cómputo es prácticamente cero. El CronJob corre unos 2 segundos cada 5 minutos y usa 64 MB de memoria mientras se ejecuta.
Cuando el operador corre kubectl scale --replicas=1 para despertar un
servidor, la JVM tarda entre 30 y 90 segundos en arrancar, cargar el mundo y
empezar a aceptar conexiones. Los jugadores acostumbrados a conexiones
instantáneas lo van a notar. Dos mitigaciones:
- El
livenessProbedel chart de Helm usamc-health, que respeta este tiempo: le da al pod 30 segundos antes del primer probe (initialDelaySeconds: 30). - Un futuro CronJob de "pre-warm" podría despertar el servidor en horas pico conocidas (viernes por la noche, sábado por la tarde). Todavía no está implementado porque el patrón de juego no es suficientemente regular para codificarlo de forma heurística.
Un jugador que se conecta no puede despertar al servidor. Es un trade-off deliberado:
- Un escalado-desde-cero transparente requiere o el proxy TCP de KEDA (más piezas en movimiento) o un proxy TCP en userspace que haga buffer de las conexiones mientras el pod arranca.
- Para un cluster privado de amigos, que el operador haga
kubectl scale --replicas=1cuando decide jugar está bien. - El controlador detecta el scale-up manual (el estado dice 0 pero el conteo en vivo es > 0) y resetea su contador de inactividad, para que el servidor recién despertado tenga los 30 minutos completos de gracia.
Cuando se les aplicó patch a los deployments de Minecraft para añadirles
resources.limits.memory, Helm no vio esos límites (no estaban en
helm get values). Un helm upgrade futuro los va a sobrescribir sin avisar.
El workaround es:
- Agregar los límites a los values de Helm y volver a actualizar, o
- Mantener un pequeño script de "patch post-render" que corra después de cada actualización del chart.
Si el chequeo de RCON no puede conectarse, el script asume que el pod ya
está escalado a cero e incrementa el contador de inactividad. Esto evita un
loop donde el script sigue intentando escalar un pod que ya está en cero.
El trade-off es que un puerto RCON mal configurado dejaría al pod escalado
a cero sin que el script se diera cuenta. Una mejora futura: un tcpProbe
separado para confirmar que el puerto de juego (25565) responde antes de
declarar al pod desaparecido.
Más allá de los 8 GB de ahorro inmediato, la misma forma funciona para cualquier otra carga de trabajo "siempre prendida pero raramente usada":
- Otros servidores de juego: Valheim, Terraria, Factorio — cualquier cosa con una señal de detección de inactividad similar.
- Entornos internos de desarrollo: un servidor de staging de larga vida que se prende cuando un desarrollador quiere probar una migración y se apaga después de unas horas sin uso.
- Cómputo por lotes: cualquier cosa que pueda publicar un estado "listo/inactivo" por RCON-equivalente (HTTP, gRPC, MQTT).
La forma común es: (a) un canal de control que puede responder "¿estás ocupado?", (b) una señal limpia de apagado, (c) una carga de trabajo con estado cuyos datos sobreviven al proceso. Si tienes esas tres cosas, un script de 200 líneas más unos cuantos manifests de k8s te dan capacidad automática.
# Despertar un servidor manualmente:
kubectl scale deployment mc-mods-minecraft -n games-minecraft --replicas=1
# Esperar unos 60 segundos y luego revisar que el mundo esté intacto:
kubectl logs -n games-minecraft -l app=mc-mods-minecraft --tail=20 | grep "RCON Client"
# Forzar un snapshot antes de cambios riesgosos:
kubectl create job --from=cronjob/mc-mods-backup mc-mods-prechange -n games-minecraft
# Leer el estado de inactividad actual:
kubectl get configmap mc-idle-state -n games-minecraft \
-o jsonpath='{.data.mc-mods}'
# {"first_idle_at": null, "last_active_at": "2026-07-22T22:00:00Z", "consecutive_idle_runs": 1, "replicas": 1}
# Disparar un chequeo fuera de ciclo (debug):
kubectl create job --from=cronjob/mc-mods-idle-detector mc-mods-debug -n games-minecraft
kubectl logs -n games-minecraft job/mc-mods-debug- CronJob de pre-warm — despertar el servidor en horas pico detectadas
de forma heurística con base en los timestamps históricos de
last_active_at. - Scaler TCP de KEDA — reemplazar el
kubectl scale --replicas=1manual con un escalado-desde-cero transparente, aceptando el costo de una pieza extra en movimiento. - Notificación por Slack / webhook — mandar un payload JSON a un webhook cuando dispare el scale-down, para que el operador vea "el servidor quedó inactivo" en su chat de preferencia.
- Dimensionamiento de recursos — las JVM hoy piden 512 MB pero en
realidad usan 3–4 GB. Agregar
resources.limits.memory(ya hecho paramc-mods) protege al host de asignaciones desbocadas, pero todavía no se retroalimenta a los requests. Un ciclo estilo VPA podría redimensionarlos con el tiempo.
Este documento describe un sistema real en producción. El código, los manifests y los detalles del protocolo RCON son públicos; los hostnames reales del servidor, las IPs internas y las credenciales no se incluyen en este gist. Siéntete libre de copiar el patrón.