Skip to content

Instantly share code, notes, and snippets.

@louzt
Created July 22, 2026 22:26
Show Gist options
  • Select an option

  • Save louzt/8e3b86c7398016964699e87d52222cf7 to your computer and use it in GitHub Desktop.

Select an option

Save louzt/8e3b86c7398016964699e87d52222cf7 to your computer and use it in GitHub Desktop.
Cluster de Minecraft auto-escalable en k3s: apagado por inactividad vía RCON (Español)

Cluster de Minecraft auto-escalable en k3s: apagado por inactividad vía RCON

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-all y escala el deployment a cero. El operador lo reactiva con kubectl scale --replicas=1. Resultado neto: ~8 GB de RAM recuperados cuando nadie está jugando.


Por qué existe esto

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.


Topología

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
Loading

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.


Decisiones de stack

k3s como base

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-path StorageClass 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-server viene incluido desde el arranque.
  • El firewall de salida es suficientemente permisivo para que itzg/minecraft-server jale imágenes de registros, pero suficientemente restrictivo como para que bajar binarios externos al iniciar el pod (por ejemplo, kubectl desde dl.k8s.io) falle — mira la sección "Por qué API REST en lugar de kubectl" más abajo.

itzg/minecraft-server como imagen base

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-health que pingea el puerto del juego — perfecto para livenessProbe / readinessProbe en k8s.
  • El chart de Helm minecraft envuelve la imagen con todas las variables de entorno, probes y PVCs correctos.

Chart de Helm para los servidores, manifests crudos para el controlador

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.

Por qué no el HorizontalPodAutoscaler nativo

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: 0 no 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.


El controlador: cómo un solo CronJob mueve todo el ciclo

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
Loading

El script es un solo archivo de Python de 200 líneas que:

  1. Lee el conteo de réplicas en vivo del subrecurso /scale del deployment (es la fuente de verdad — el estado del ConfigMap puede divergir).
  2. Lee el estado persistente del ConfigMap/mc-idle-state.
  3. Si el estado dice replicas: 0 pero el deployment en realidad tiene réplicas corriendo, significa que el operador hizo kubectl scale --replicas=1 a mano. El controlador resetea el contador de inactividad a cero para que el servidor recién despertado tenga sus 30 minutos completos de gracia.
  4. Envía un comando RCON list autenticado al servidor.
  5. 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.
  6. Persiste el nuevo estado de vuelta al ConfigMap.

Protocolo RCON, en 60 líneas de Python

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.

Por qué API REST directa, no kubectl dentro del pod

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.


Estabilidad y trazabilidad

Respaldos

Un CronJob separado corre cada 6 horas por servidor. Hace lo siguiente:

  1. Envía save-off por RCON para desactivar el auto-save.
  2. Envía save-all flush y espera a que termine.
  3. Empaqueta world/, mods/, config/, server.properties y los distintos archivos JSON de apoyo en un archivo tar.gz.
  4. Verifica el archivo (un smoke test rápido con tar -tzf) antes de ponerlo en su lugar.
  5. Envía save-on para reactivar el auto-save.
  6. 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

Máquina de estados

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}

Alcance del RBAC

La ServiceAccount mc-idle-detector solo tiene permiso para:

  • get/patch/update del subrecurso scale de los dos deployments de Minecraft
  • get/patch/update del ConfigMap mc-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".


Consumo: qué te compras con esto

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.


Trade-offs y advertencias honestas

1. Latencia de cold start

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 livenessProbe del chart de Helm usa mc-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.

2. El scale-up es manual, no automático

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=1 cuando 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.

3. El chart de Helm y kubectl patch no siempre se llevan bien

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.

4. RCON inalcanzable se trata como "ya está escalado a 0"

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.


Qué habilita este patrón

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.


Procedimiento de recuperación (recetario del operador)

# 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

Trabajo futuro

  1. 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.
  2. Scaler TCP de KEDA — reemplazar el kubectl scale --replicas=1 manual con un escalado-desde-cero transparente, aceptando el costo de una pieza extra en movimiento.
  3. 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.
  4. Dimensionamiento de recursos — las JVM hoy piden 512 MB pero en realidad usan 3–4 GB. Agregar resources.limits.memory (ya hecho para mc-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.

Licencia

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment