Scalabilità orizzontale

Eseguire più repliche di Ayakaleaf Pro dietro un load balancer con sessioni sticky.

Una sola replica usa la CPU di un solo nodo per ogni compilazione: sui nostri nodi di test con 2 vCPU, sei compilazioni simultanee hanno impiegato il triplo del tempo di una sola, mentre gli altri nodi restavano inattivi. Più repliche distribuiscono gli utenti, e le loro compilazioni, tra i nodi.

Questo segue il modello di Scalabilità orizzontale di Overleaf, adattato a Kubernetes:

Requisito	Qui
MongoDB e Redis condivisi	10-mongo.yaml e 20-redis.yaml dall’installazione
Segreti condivisi	il Secret overleaf-secrets del passaggio 2 li contiene già
File e cronologia dei progetti in S3 (non NFS)	qualsiasi servizio S3, vedi S3; lì Garage come esempio interno al cluster
Un disco locale per replica per compilazioni e caricamenti	hostPath /srv/overleaf-ha su ogni nodo
Instradamento persistente, WebSocket, timeout di 10 min, caricamenti da 50 MB	HAProxy con la configurazione di esempio di Overleaf
git-bridge come singleton accanto a una replica	git-bridge con overleaf-0 come sibling

Pianifica S3 fin dall’inizio. Un’istanza che conserva già i file sul proprio volume richiede prima la migrazione a S3. Questa configurazione sostituisce il Deployment del passaggio 5: eliminalo (kubectl delete -f 40-overleaf.yaml) prima di applicare lo StatefulSet.

1. Storage S3

   Configura i tre bucket e i due utenti come descritto in S3, con il tuo servizio S3 o con Garage nel cluster, e inserisci le quattro chiavi nel Secret overleaf-s3. La configurazione seguente usa l’esempio di Garage di quella pagina.

2. Configurazione

   Questa ConfigMap sostituisce 30-config.yaml. Aggiunge S3 e git-bridge e fa puntare OVERLEAF_SITE_URL al load balancer:

   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. Repliche

   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, non Deployment. Ogni replica riceve un nome stabile (overleaf-0, overleaf-1, …) a cui fanno riferimento il cookie del load balancer e git-bridge, e OrderedReady avvia prima overleaf-0 da solo, così solo una replica esegue le migrazioni del database.
   • Una replica per nodo. Ogni replica avvia le proprie compilazioni tramite il Docker del proprio nodo e le conserva nella /srv/overleaf-ha del proprio nodo.
   • V1_HISTORY_URL per replica. Ogni replica distribuisce i link della cronologia con il proprio nome, in modo che git-bridge possa raggiungerli.
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
   

   Vedi Integrazione Git per sapere perché GIT_BRIDGE_HOST è un indirizzo IP fisso.

5. Load balancer

   La configurazione di HAProxy è l’esempio di Overleaf con cinque modifiche: /project/<id>/mcp instradato a overleaf-0 come /git/ (vedi Server MCP), HTTP semplice sulla porta 8080 (l’immagine viene eseguita come utente non root, che non può collegarsi alla porta 80 con containerd), server individuati tramite il DNS del cluster (gli IP dei pod cambiano a ogni riavvio), un DaemonSet affinché ogni nodo risponda, e balance leastconn al posto del roundrobin predefinito (vedi le domande e risposte più sotto).

   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 mantiene gli indirizzi IP degli utenti in X-Forwarded-For.

6. TLS

   Termina HTTPS in HAProxy come descritto in Proxy TLS, quindi imposta OVERLEAF_SITE_URL sull’indirizzo https:// e OVERLEAF_SECURE_COOKIE: "true" in 60-config.yaml.

​

Cosa aspettarsi

Abbiamo testato tre repliche su tre nodi con 2 vCPU e 4 GB ciascuno, con MongoDB, Redis, Garage, git-bridge e HAProxy sugli stessi nodi:

• 12 utenti che compilano contemporaneamente un documento di 600 pagine: tutti e 12 hanno compilato e scaricato il proprio PDF, 4 utenti per replica; un ciclo ha richiesto da 8 a 18 secondi. Ogni nodo ha mantenuto almeno 1,3 GB di memoria disponibile.
• Ogni utente resta su una replica (cookie server-pro-ha), incluso il download del PDF, che deve provenire dalla replica che lo ha compilato. Lo stesso vale su HTTPS, incluso il WebSocket dell’editor.
• Quando una replica si arresta, i suoi utenti ricevono errori per circa 15-20 secondi, finché HAProxy non la contrassegna come non disponibile; poi passano a un’altra replica e restano connessi, perché le sessioni risiedono in Redis.

​

Domande e risposte

Perché balance leastconn?

Risposta: Con l’esempio di Overleaf (roundrobin, un HAProxy per nodo), nel nostro test 12 nuovi utenti sono finiti distribuiti 8, 3 e 1 sulle tre repliche, e la replica più carica ha fatto attendere gli utenti più lenti 29 secondi. Con leastconn, che preferisce la replica con meno connessioni aperte (ogni editor mantiene aperto un WebSocket), lo stesso test ha dato 4, 4 e 4 e 18 secondi. La stickiness resta invariata: deriva dal cookie.

Posso usare il mio ingress controller al posto di HAProxy?

Risposta: Sì, se instrada tramite un cookie verso una replica stabile, supporta i WebSocket, consente tempi di richiesta di 10 minuti e caricamenti di 50 MB, mantiene il proprio timeout di keep-alive sotto i 65 secondi, invia X-Forwarded-For e X-Forwarded-Proto e invia /git/ e /project/<id>/mcp a overleaf-0. Instrada verso i nomi propri delle repliche (overleaf-N.overleaf-hl), non verso un Service che bilancia ogni richiesta.

Come aggiungo una quarta replica?

Risposta: Aggiungi un nodo con Docker e le immagini TeX Live, imposta replicas: 4 in 70-overleaf.yaml e aggiungi una riga server overleaf-3 ... alla configurazione di HAProxy (e incrementa config-hash in modo che HAProxy si riavvii).