Skalowanie poziome

Uruchamianie kilku replik Ayakaleaf Pro za load balancerem z sesjami sticky.

Jedna replika wykorzystuje do każdej kompilacji procesor jednego węzła: na naszych węzłach testowych z 2 vCPU sześć jednoczesnych kompilacji trwało trzy razy dłużej niż jedna, podczas gdy pozostałe węzły były bezczynne. Kilka replik rozkłada użytkowników i ich kompilacje na węzły.

Jest to projekt Skalowania poziomego Overleaf przeniesiony na Kubernetes:

Wymaganie	Tutaj
Współdzielone MongoDB i Redis	10-mongo.yaml i 20-redis.yaml z instalacji
Współdzielone sekrety	Secret overleaf-secrets z kroku 2 już je zawiera
Pliki projektów i historia w S3 (nie NFS)	dowolna usługa S3, zobacz S3; tam Garage jako przykład wewnątrz klastra
Lokalny dysk dla każdej repliki na kompilacje i przesłane pliki	hostPath /srv/overleaf-ha na każdym węźle
Trwały routing, WebSockety, limity czasu 10 min, przesyłanie plików do 50 MB	HAProxy z przykładową konfiguracją Overleaf
git-bridge jako pojedyncza instancja obok jednej repliki	git-bridge z overleaf-0 jako rodzeństwem (sibling)

Zaplanuj S3 od samego początku. Instancja, która już przechowuje pliki na swoim wolumenie, wymaga najpierw migracji do S3. Ta konfiguracja zastępuje Deployment z kroku 5: usuń go (kubectl delete -f 40-overleaf.yaml), zanim zastosujesz StatefulSet.

1. Magazyn S3

   Skonfiguruj trzy buckety i dwóch użytkowników zgodnie z opisem w S3, przy użyciu swojej usługi S3 lub Garage w klastrze, i umieść cztery klucze w Secret overleaf-s3. Poniższa konfiguracja korzysta z przykładu Garage z tamtej strony.

2. Konfiguracja

   Ten ConfigMap zastępuje 30-config.yaml. Dodaje S3 i git-bridge oraz kieruje OVERLEAF_SITE_URL na 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. Repliki

   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, a nie Deployment. Każda replika otrzymuje stabilną nazwę (overleaf-0, overleaf-1, …), do której odwołują się ciasteczko load balancera i git-bridge, a OrderedReady uruchamia najpierw samodzielnie overleaf-0, więc migracje bazy danych wykonuje tylko jedna replika.
   • Jedna replika na węzeł. Każda replika uruchamia swoje kompilacje przez Dockera swojego węzła i przechowuje je w /srv/overleaf-ha swojego węzła.
   • V1_HISTORY_URL dla każdej repliki. Każda replika rozdaje linki do historii z własną nazwą, aby git-bridge mógł się z nimi połączyć.
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
   

   Dlaczego GIT_BRIDGE_HOST jest stałym adresem IP, wyjaśniono w Integracja z Git.

5. Load balancer

   Konfiguracja HAProxy to przykład Overleaf z pięcioma zmianami: /project/<id>/mcp kierowane do overleaf-0 tak jak /git/ (zobacz Serwer MCP), zwykłe HTTP na porcie 8080 (obraz działa jako użytkownik inny niż root, który pod containerd nie może powiązać portu 80), serwery wyszukiwane przez DNS klastra (adresy IP podów zmieniają się przy każdym restarcie), DaemonSet, aby odpowiadał każdy węzeł, oraz balance leastconn zamiast domyślnego roundrobin (zobacz Pytania i odpowiedzi poniżej).

   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 zachowuje adresy IP użytkowników w X-Forwarded-For.

6. TLS

   Zakończ HTTPS w HAProxy zgodnie z opisem w Proxy TLS, a następnie ustaw w 60-config.yaml OVERLEAF_SITE_URL na adres https:// oraz OVERLEAF_SECURE_COOKIE: "true".

​

Czego się spodziewać

Przetestowaliśmy trzy repliki na trzech węzłach z 2 vCPU i 4 GB każdy, z MongoDB, Redis, Garage, git-bridge i HAProxy na tych samych węzłach:

• 12 użytkowników kompilujących jednocześnie 600-stronicowy dokument: wszystkich 12 skompilowało i pobrało swój PDF, po 4 użytkowników na replikę; jedna runda trwała od 8 do 18 sekund. Na każdym węźle pozostawało dostępne co najmniej 1,3 GB pamięci.
• Każdy użytkownik pozostaje na jednej replice (ciasteczko server-pro-ha), łącznie z pobieraniem PDF, które musi pochodzić z repliki, która go skompilowała. To samo dotyczy HTTPS, łącznie z WebSocketem edytora.
• Gdy replika się zatrzyma, jej użytkownicy otrzymują błędy przez około 15 do 20 sekund, dopóki HAProxy nie oznaczy jej jako niedostępnej; następnie przechodzą na inną replikę i pozostają zalogowani, ponieważ sesje znajdują się w Redis.

​

Pytania i odpowiedzi

Dlaczego balance leastconn?

Odpowiedź: Z przykładem Overleaf (roundrobin, jeden HAProxy na węzeł) w naszym teście 12 nowych użytkowników rozłożyło się na trzy repliki jako 8, 3 i 1, a najbardziej obciążona replika kazała najwolniejszym użytkownikom czekać 29 sekund. Z leastconn, które preferuje replikę z najmniejszą liczbą otwartych połączeń (każdy edytor utrzymuje otwarty WebSocket), ten sam test dał 4, 4 i 4 oraz 18 sekund. Przywiązanie sesji (stickiness) pozostaje bez zmian: wynika z ciasteczka.

Czy mogę użyć mojego kontrolera ingress zamiast HAProxy?

Odpowiedź: Tak, jeśli kieruje ruch na podstawie ciasteczka do stabilnej repliki, obsługuje WebSockety, dopuszcza czas żądań 10 minut i przesyłanie plików do 50 MB, utrzymuje limit czasu keep-alive poniżej 65 sekund, wysyła X-Forwarded-For i X-Forwarded-Proto oraz kieruje /git/ i /project/<id>/mcp do overleaf-0. Kieruj ruch na własne nazwy replik (overleaf-N.overleaf-hl), a nie na Service, który rozkłada każde żądanie.

Jak dodać czwartą replikę?

Odpowiedź: Dodaj węzeł z Dockerem i obrazami TeX Live, ustaw replicas: 4 w 70-overleaf.yaml i dodaj linię server overleaf-3 ... do konfiguracji HAProxy (oraz zwiększ config-hash, aby HAProxy się zrestartował).