Penskalaan horizontal

Jalankan beberapa replika Ayakaleaf Pro di belakang load balancer dengan sticky session.

Satu replika menggunakan CPU dari satu node untuk setiap kompilasi: pada node uji kami dengan 2 vCPU, enam kompilasi serentak memakan waktu tiga kali lebih lama daripada satu, sementara node lainnya menganggur. Beberapa replika menyebarkan pengguna, beserta kompilasinya, ke seluruh node.

Ini mengikuti desain Penskalaan horizontal dari Overleaf, yang diterjemahkan ke Kubernetes:

Persyaratan	Di sini
MongoDB dan Redis bersama	10-mongo.yaml dan 20-redis.yaml dari instalasi
Secret bersama	Secret overleaf-secrets dari langkah 2 sudah memilikinya
File proyek dan riwayat di S3 (bukan NFS)	layanan S3 apa pun, lihat S3; Garage di sana sebagai contoh di dalam kluster
Disk lokal per replika untuk kompilasi dan unggahan	hostPath /srv/overleaf-ha di setiap node
Routing persisten, WebSocket, timeout 10 menit, unggahan 50 MB	HAProxy dengan konfigurasi contoh dari Overleaf
git-bridge sebagai singleton di samping satu replika	git-bridge dengan overleaf-0 sebagai sibling-nya

Rencanakan S3 sejak awal. Instans yang sudah menyimpan file di volumenya memerlukan migrasi S3 terlebih dahulu. Penyiapan ini menggantikan Deployment dari langkah 5: hapus Deployment tersebut (kubectl delete -f 40-overleaf.yaml) sebelum Anda menerapkan StatefulSet.

1. Penyimpanan S3

   Siapkan tiga bucket dan dua pengguna seperti dijelaskan di S3, dengan layanan S3 Anda atau dengan Garage di dalam kluster, lalu masukkan keempat kunci ke Secret overleaf-s3. Konfigurasi di bawah ini menggunakan contoh Garage dari halaman tersebut.

2. Konfigurasi

   ConfigMap ini menggantikan 30-config.yaml. ConfigMap ini menambahkan S3 dan git-bridge serta mengarahkan OVERLEAF_SITE_URL ke 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. Replika

   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, bukan Deployment. Setiap replika mendapat nama yang stabil (overleaf-0, overleaf-1, …) yang dirujuk oleh cookie load balancer dan git-bridge, dan OrderedReady memulai overleaf-0 sendirian terlebih dahulu, sehingga hanya satu replika yang menjalankan migrasi database.
   • Satu replika per node. Setiap replika memulai kompilasinya melalui Docker di node-nya dan menyimpannya di /srv/overleaf-ha pada node-nya.
   • V1_HISTORY_URL per replika. Setiap replika membagikan tautan riwayat dengan namanya sendiri, sehingga git-bridge dapat menjangkaunya.
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
   

   Lihat Integrasi Git untuk alasan mengapa GIT_BRIDGE_HOST berupa alamat IP tetap.

5. Load balancer

   Konfigurasi HAProxy adalah contoh dari Overleaf dengan lima perubahan: /project/<id>/mcp dirutekan ke overleaf-0 seperti /git/ (lihat MCP Server), HTTP biasa pada port 8080 (image berjalan sebagai pengguna non-root, yang tidak dapat melakukan bind ke port 80 di bawah containerd), server ditemukan melalui DNS kluster (IP pod berubah setiap kali restart), DaemonSet agar setiap node menjawab, dan balance leastconn sebagai pengganti roundrobin default (lihat Tanya Jawab di bawah).

   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 mempertahankan alamat IP pengguna di X-Forwarded-For.

6. TLS

   Terminasikan HTTPS di HAProxy seperti dijelaskan di Proxy TLS, lalu atur OVERLEAF_SITE_URL ke alamat https:// dan OVERLEAF_SECURE_COOKIE: "true" di 60-config.yaml.

​

Apa yang dapat diharapkan

Kami menguji tiga replika pada tiga node dengan masing-masing 2 vCPU dan 4 GB, dengan MongoDB, Redis, Garage, git-bridge, dan HAProxy di node yang sama:

• 12 pengguna mengompilasi dokumen 600 halaman secara bersamaan: kedua belas pengguna berhasil mengompilasi dan mengambil PDF mereka, 4 pengguna per replika; satu putaran memakan waktu 8 hingga 18 detik. Setiap node tetap memiliki setidaknya 1,3 GB memori yang tersedia.
• Setiap pengguna tetap berada di satu replika (cookie server-pro-ha), termasuk unduhan PDF yang harus berasal dari replika yang mengompilasinya. Hal yang sama berlaku melalui HTTPS, termasuk WebSocket editor.
• Saat sebuah replika berhenti, penggunanya mendapat error selama sekitar 15 hingga 20 detik, hingga HAProxy menandainya sebagai down; kemudian mereka berpindah ke replika lain dan tetap login, karena sesi disimpan di Redis.

​

Tanya Jawab

Mengapa balance leastconn?

Jawaban: Dengan contoh dari Overleaf (roundrobin, satu HAProxy per node), 12 pengguna baru terbagi menjadi 8, 3, dan 1 di ketiga replika dalam pengujian kami, dan replika tersibuk membuat pengguna yang paling lambat menunggu 29 detik. Dengan leastconn, yang mengutamakan replika dengan koneksi terbuka paling sedikit (setiap editor membiarkan WebSocket tetap terbuka), pengujian yang sama menghasilkan 4, 4, dan 4 serta 18 detik. Stickiness tidak berubah: berasal dari cookie.

Bisakah saya menggunakan ingress controller saya sebagai pengganti HAProxy?

Jawaban: Ya, jika ingress controller tersebut merutekan berdasarkan cookie ke replika yang stabil, mendukung WebSocket, mengizinkan waktu permintaan 10 menit dan unggahan 50 MB, menjaga timeout keep-alive di bawah 65 detik, mengirim X-Forwarded-For dan X-Forwarded-Proto, serta mengirim /git/ dan /project/<id>/mcp ke overleaf-0. Rutekan ke nama masing-masing replika (overleaf-N.overleaf-hl), bukan ke Service yang menyeimbangkan setiap permintaan.

Bagaimana cara menambahkan replika keempat?

Jawaban: Tambahkan node dengan Docker dan image TeX Live, atur replicas: 4 di 70-overleaf.yaml, dan tambahkan baris server overleaf-3 ... ke konfigurasi HAProxy (serta naikkan config-hash agar HAProxy di-restart).