Escalado horizontal

Ejecuta varias réplicas de Ayakaleaf Pro detrás de un balanceador de carga con sesiones persistentes.

Una réplica usa la CPU de un solo nodo para todas las compilaciones: en nuestros nodos de prueba con 2 vCPU, seis compilaciones simultáneas tardaron tres veces más que una, mientras los demás nodos permanecían inactivos. Varias réplicas reparten a los usuarios, y sus compilaciones, entre los nodos.

Esto sigue el diseño de Escalado horizontal de Overleaf, trasladado a Kubernetes:

Requisito	Aquí
MongoDB y Redis compartidos	10-mongo.yaml y 20-redis.yaml de la instalación
Secretos compartidos	el Secret overleaf-secrets del paso 2 ya los contiene
Archivos e historial de los proyectos en S3 (no NFS)	cualquier servicio S3; consulta S3; allí se usa Garage como ejemplo dentro del clúster
Un disco local por réplica para compilaciones y subidas	hostPath /srv/overleaf-ha en cada nodo
Enrutamiento persistente, WebSockets, tiempos de espera de 10 min, subidas de 50 MB	HAProxy con la configuración de ejemplo de Overleaf
git-bridge como instancia única junto a una réplica	git-bridge con overleaf-0 como contenedor hermano

Planifica S3 desde el principio. Una instancia que ya guarda archivos en su volumen necesita primero la migración a S3. Esta configuración sustituye al Deployment del paso 5: elimínalo (kubectl delete -f 40-overleaf.yaml) antes de aplicar el StatefulSet.

1. Almacenamiento S3

   Configura los tres buckets y los dos usuarios como se describe en S3, con tu servicio S3 o con Garage en el clúster, y pon las cuatro claves en el Secret overleaf-s3. La configuración siguiente usa el ejemplo de Garage de esa página.

2. Configuración

   Este ConfigMap sustituye a 30-config.yaml. Añade S3 y git-bridge y hace que OVERLEAF_SITE_URL apunte al balanceador de carga:

   60-config.yaml

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: overleaf-env
     namespace: overleaf
   data:
     OVERLEAF_APP_NAME: Ayakaleaf Pro
     OVERLEAF_SITE_URL: http://192.0.2.10:30081      # the load balancer (HAProxy) URL
     OVERLEAF_ADMIN_EMAIL: [e-mail]
     # Emails: add the sender and the SMTP server together, see Email delivery
     OVERLEAF_MONGO_URL: mongodb://mongo-0.mongo:27017,mongo-1.mongo:27017,mongo-2.mongo:27017/sharelatex?replicaSet=overleaf
     OVERLEAF_REDIS_HOST: redis
     REDIS_HOST: redis
     ENABLED_LINKED_FILE_TYPES: project_file,project_output_file,url
     ENABLE_CONVERSIONS: "true"
     EMAIL_CONFIRMATION_DISABLED: "true"
     OVERLEAF_TRUSTED_PROXY_IPS: loopback,10.244.0.0/16   # HAProxy runs in the pod CIDR
     # Sandboxed compiles, node paths: each replica owns /srv/overleaf-ha on its node
     SANDBOXED_COMPILES: "true"
     SANDBOXED_COMPILES_SIBLING_CONTAINERS: "true"
     DOCKER_RUNNER: "true"
     SANDBOXED_COMPILES_HOST_DIR_COMPILES: /srv/overleaf-ha/data/compiles
     SANDBOXED_COMPILES_HOST_DIR_OUTPUT: /srv/overleaf-ha/data/output
     SANDBOXED_COMPILES_HOST_DIR_CACHE: /srv/overleaf-ha/data/cache
     ALL_TEX_LIVE_DOCKER_IMAGES: ghcr.io/ayaka-notes/texlive-full:2026.1
     ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: TeX Live 2026
     TEX_LIVE_DOCKER_IMAGE: ghcr.io/ayaka-notes/texlive-full:2026.1
     # S3 (required for more than one replica); keys are in the Secret overleaf-s3
     OVERLEAF_FILESTORE_BACKEND: s3
     OVERLEAF_FILESTORE_TEMPLATE_FILES_BUCKET_NAME: overleaf-template-files
     OVERLEAF_FILESTORE_S3_ENDPOINT: http://garage:3900
     OVERLEAF_FILESTORE_S3_PATH_STYLE: "true"
     OVERLEAF_FILESTORE_S3_REGION: garage
     OVERLEAF_HISTORY_BACKEND: s3
     OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET: overleaf-project-blobs
     OVERLEAF_HISTORY_CHUNKS_BUCKET: overleaf-chunks
     OVERLEAF_HISTORY_S3_ENDPOINT: http://garage:3900
     OVERLEAF_HISTORY_S3_PATH_STYLE: "true"
     OVERLEAF_HISTORY_S3_REGION: garage
     # Git integration: one git-bridge, its sibling is overleaf-0
     GIT_BRIDGE_ENABLED: "true"
     GIT_BRIDGE_HOST: 10.96.100.80      # the git-bridge Service's fixed ClusterIP, see 75-git-bridge.yaml
     GIT_BRIDGE_PORT: "8000"
   
3. Réplicas

   70-overleaf.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: overleaf-hl
     namespace: overleaf
   spec:
     clusterIP: None            # stable DNS per replica: overleaf-0.overleaf-hl, ...
     selector:
       app: overleaf-ha
     ports:
       - {name: http, port: 80}
       - {name: web, port: 3000}       # git-bridge API (sibling only)
       - {name: history, port: 3100}   # history-v1, used by git-bridge via V1_HISTORY_URL
   ---
   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: overleaf
     namespace: overleaf
   spec:
     serviceName: overleaf-hl
     replicas: 3
     # OrderedReady: overleaf-0 runs the migrations alone before the next replica starts
     podManagementPolicy: OrderedReady
     selector:
       matchLabels:
         app: overleaf-ha
     template:
       metadata:
         labels:
           app: overleaf-ha
       spec:
         terminationGracePeriodSeconds: 60
         # Keep the environment to the ConfigMap and Secrets: no REDIS_PORT=tcp://..., GIT_BRIDGE_PORT=tcp://...
         enableServiceLinks: false
         affinity:
           podAntiAffinity:            # one replica per node: each uses that node's Docker and disk
             requiredDuringSchedulingIgnoredDuringExecution:
               - labelSelector:
                   matchLabels:
                     app: overleaf-ha
                 topologyKey: kubernetes.io/hostname
         containers:
           - name: sharelatex
             image: ghcr.io/ayaka-notes/overleaf-pro:6.3.2
             env:
               - name: POD_NAME
                 valueFrom:
                   fieldRef:
                     fieldPath: metadata.name
               # Each replica hands out history URLs with its own stable name, so git-bridge can reach them
               - name: V1_HISTORY_URL
                 value: http://$(POD_NAME).overleaf-hl.overleaf.svc.cluster.local:3100/api
             envFrom:
               - configMapRef: {name: overleaf-env}
               - secretRef: {name: overleaf-secrets}
               - secretRef: {name: overleaf-s3}
             ports:
               - containerPort: 80
             readinessProbe:
               httpGet: {path: /status, port: 80}
               periodSeconds: 10
             resources:
               requests: {cpu: 500m, memory: 1536Mi}
               limits: {memory: 3Gi}
             volumeMounts:
               - {name: local, mountPath: /var/lib/overleaf}
               - {name: docker-sock, mountPath: /var/run/docker.sock}
         volumes:
           # Local disk for ephemeral files (compiles, output, uploads); the HOST_DIR_* paths are under it
           - name: local
             hostPath: {path: /srv/overleaf-ha, type: DirectoryOrCreate}
           - name: docker-sock
             hostPath: {path: /var/run/docker.sock, type: Socket}
   

   • StatefulSet, no Deployment. Cada réplica recibe un nombre estable (overleaf-0, overleaf-1, …) al que hacen referencia la cookie del balanceador de carga y git-bridge, y OrderedReady arranca primero overleaf-0 por sí sola, de modo que solo una réplica ejecuta las migraciones de la base de datos.
   • Una réplica por nodo. Cada réplica inicia sus compilaciones mediante el Docker de su nodo y las guarda en el /srv/overleaf-ha de su nodo.
   • V1_HISTORY_URL por réplica. Cada réplica entrega los enlaces del historial con su propio nombre, para que git-bridge pueda llegar a ellos.
4. git-bridge

   75-git-bridge.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: git-bridge
     namespace: overleaf
   spec:
     # Fixed ClusterIP (inside the service CIDR): the sharelatex image's nginx proxies /git/ with
     # `resolver 127.0.0.11` (Docker's DNS), which does not exist in Kubernetes, so GIT_BRIDGE_HOST is this IP
     clusterIP: 10.96.100.80
     selector:
       app: git-bridge
     ports:
       - {name: http, port: 8000}
   ---
   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: git-bridge
     namespace: overleaf
   spec:
     serviceName: git-bridge
     replicas: 1
     selector:
       matchLabels:
         app: git-bridge
     template:
       metadata:
         labels:
           app: git-bridge
       spec:
         # Service "git-bridge" would inject GIT_BRIDGE_PORT=tcp://..., which git-bridge reads as its port
         enableServiceLinks: false
         containers:
           - name: git-bridge
             image: ghcr.io/ayaka-notes/overleaf-pro/git-bridge:6.3.2   # same version as the sharelatex image
             command: ["/server-pro-start.sh"]
             securityContext:
               runAsUser: 0
             env:
               - {name: GIT_BRIDGE_API_BASE_URL, value: "http://overleaf-0.overleaf-hl.overleaf.svc.cluster.local:3000/api/v0/"}
               - {name: GIT_BRIDGE_OAUTH2_SERVER, value: "http://overleaf-0.overleaf-hl.overleaf.svc.cluster.local"}
               - {name: GIT_BRIDGE_POSTBACK_BASE_URL, value: "http://git-bridge.overleaf.svc.cluster.local:8000"}
               - {name: GIT_BRIDGE_ROOT_DIR, value: /data/git-bridge}
             ports:
               - containerPort: 8000
             resources:
               requests: {cpu: 100m, memory: 256Mi}
               limits: {memory: 768Mi}
             volumeMounts:
               - {name: data, mountPath: /data/git-bridge}
     volumeClaimTemplates:
       - metadata:
           name: data
         spec:
           accessModes: [ReadWriteOnce]
           resources:
             requests:
               storage: 5Gi
   

   Consulta Integración con Git para saber por qué GIT_BRIDGE_HOST es una dirección IP fija.

5. Balanceador de carga

   La configuración de HAProxy es el ejemplo de Overleaf con cinco cambios: /project/<id>/mcp enrutado a overleaf-0 igual que /git/ (consulta Servidor MCP), HTTP sin cifrar en el puerto 8080 (la imagen se ejecuta como usuario no root, que no puede usar el puerto 80 con containerd), servidores localizados mediante el DNS del clúster (las IP de los pods cambian en cada reinicio), un DaemonSet para que todos los nodos respondan, y balance leastconn en lugar del roundrobin por defecto (consulta las preguntas y respuestas más abajo).

   80-haproxy.yaml

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: haproxy-config
     namespace: overleaf
   data:
     haproxy.cfg: |
       global
         log stdout format raw local0 info
   
       resolvers kubedns
         parse-resolv-conf
         hold valid 10s
   
       defaults
         mode                    http
         # New sessions go to the replica with the fewest open connections (editors keep a WebSocket open)
         balance                 leastconn
         option                  httpchk HEAD /status
         http-check              expect status 200
         default-server          check resolvers kubedns init-addr none
         log                     global
         option                  httplog
         # Reroute to a different backend if the sticky one is down
         option                  redispatch 1
         retries                 3
         # Sticky session for 24h of inactivity -- compile output is deleted after 24h
         cookie                  server-pro-ha insert maxidle 24h
         timeout queue           1m
         timeout connect         15s
         timeout client          1m
         # Allow slow compiles -- hard-coded limit in clsi is 10min
         timeout server          10m
         # Disconnect the editor after 23h
         timeout tunnel          23h
         # Lower than NGINX_KEEPALIVE_TIMEOUT (65s) in the sharelatex container
         timeout http-keep-alive 60s
   
       listen overleaf
         bind :8080
         option forwardfor
         # When TLS ends in front of HAProxy, also pass:  http-request set-header X-Forwarded-Proto https
         # git requests go to the git-bridge sibling
         use-server overleaf-0 if { path_beg /git/ }
         # MCP clients send no cookie: keep compile, log and PDF download on one replica
         use-server overleaf-0 if { path_reg ^/project/[0-9a-f]{24}/mcp(/|$) }
         http-response add-header X-Served-By %s
         stats enable
         stats uri /haproxy
         server overleaf-0 overleaf-0.overleaf-hl.overleaf.svc.cluster.local:80 cookie overleaf-0
         server overleaf-1 overleaf-1.overleaf-hl.overleaf.svc.cluster.local:80 cookie overleaf-1
         server overleaf-2 overleaf-2.overleaf-hl.overleaf.svc.cluster.local:80 cookie overleaf-2
   ---
   apiVersion: apps/v1
   # DaemonSet: one HAProxy per node, so the NodePort answers on every node with externalTrafficPolicy
   # Local. The cookie holds the replica name, so stickiness works whichever HAProxy a request hits.
   kind: DaemonSet
   metadata:
     name: haproxy
     namespace: overleaf
   spec:
     selector:
       matchLabels:
         app: haproxy
     template:
       metadata:
         labels:
           app: haproxy
         annotations:
           config-hash: "1"   # bump to restart after editing the ConfigMap
       spec:
         containers:
           - name: haproxy
             image: haproxy:lts-alpine
             ports:
               - containerPort: 8080
             resources:
               requests: {cpu: 50m, memory: 32Mi}
               limits: {memory: 256Mi}
             volumeMounts:
               - {name: config, mountPath: /usr/local/etc/haproxy}
         volumes:
           - name: config
             configMap:
               name: haproxy-config
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: haproxy
     namespace: overleaf
   spec:
     type: NodePort
     externalTrafficPolicy: Local    # keep the client IP (no SNAT); only nodes running HAProxy answer
     selector:
       app: haproxy
     ports:
       - {name: http, port: 80, targetPort: 8080, nodePort: 30081}
   

   kubectl delete -f 40-overleaf.yaml --ignore-not-found
   kubectl apply -f 60-config.yaml -f 70-overleaf.yaml -f 75-git-bridge.yaml -f 80-haproxy.yaml
   kubectl -n overleaf rollout status statefulset/overleaf --timeout=20m
   curl -sI http://192.0.2.10:30081/login | grep -i x-served-by
   

   externalTrafficPolicy: Local conserva las direcciones IP de los usuarios en X-Forwarded-For.

6. TLS

   Termina HTTPS en HAProxy como se describe en Proxy TLS y, después, establece OVERLEAF_SITE_URL en la dirección https:// y OVERLEAF_SECURE_COOKIE: "true" en 60-config.yaml.

​

Qué esperar

Probamos tres réplicas en tres nodos con 2 vCPU y 4 GB cada uno, con MongoDB, Redis, Garage, git-bridge y HAProxy en los mismos nodos:

• 12 usuarios compilando a la vez un documento de 600 páginas: los 12 compilaron y obtuvieron su PDF, 4 usuarios por réplica; una ronda tardó entre 8 y 18 segundos. Cada nodo mantuvo al menos 1,3 GB de memoria disponible.
• Cada usuario permanece en una réplica (cookie server-pro-ha), incluida la descarga del PDF, que debe proceder de la réplica que lo compiló. Lo mismo ocurre con HTTPS, incluido el WebSocket del editor.
• Cuando una réplica se detiene, sus usuarios reciben errores durante unos 15 a 20 segundos, hasta que HAProxy la marca como caída; después pasan a otra réplica y siguen con la sesión iniciada, porque las sesiones residen en Redis.

​

Preguntas y respuestas

¿Por qué balance leastconn?

Respuesta: Con el ejemplo de Overleaf (roundrobin, un HAProxy por nodo), 12 usuarios nuevos acabaron repartidos en 8, 3 y 1 entre las tres réplicas en nuestra prueba, y la réplica más cargada hizo esperar 29 segundos a los usuarios más lentos. Con leastconn, que prefiere la réplica con menos conexiones abiertas (cada editor mantiene un WebSocket abierto), la misma prueba dio 4, 4 y 4, y 18 segundos. La persistencia no cambia: procede de la cookie.

¿Puedo usar mi controlador de ingress en lugar de HAProxy?

Respuesta: Sí, siempre que enrute mediante una cookie a una réplica estable, admita WebSockets, permita tiempos de petición de 10 minutos y subidas de 50 MB, mantenga su tiempo de espera keep-alive por debajo de 65 segundos, envíe X-Forwarded-For y X-Forwarded-Proto, y envíe /git/ y /project/<id>/mcp a overleaf-0. Enruta a los nombres propios de las réplicas (overleaf-N.overleaf-hl), no a un Service que reparta cada petición.

¿Cómo añado una cuarta réplica?

Respuesta: Añade un nodo con Docker y las imágenes de TeX Live, establece replicas: 4 en 70-overleaf.yaml y añade una línea server overleaf-3 ... a la configuración de HAProxy (e incrementa config-hash para que HAProxy se reinicie).