Yatay ölçeklendirme

Yapışkan oturumlu (sticky session) bir yük dengeleyicinin arkasında birden fazla Ayakaleaf Pro replikası çalıştırın.

Tek bir replika her derleme için tek bir düğümün CPU’sunu kullanır: 2 vCPU’lu test düğümlerimizde, aynı anda yapılan altı derleme tek bir derlemenin üç katı kadar sürdü, diğer düğümler ise boşta kaldı. Birden fazla replika, kullanıcıları ve onların derlemelerini düğümlere dağıtır.

Bu, Overleaf’in Yatay ölçeklendirme tasarımını Kubernetes’e uyarlar:

Gereksinim	Burada
Paylaşılan MongoDB ve Redis	kurulumdaki 10-mongo.yaml ve 20-redis.yaml
Paylaşılan gizli anahtarlar	2. adımdaki overleaf-secrets Secret’ı bunları zaten içerir
S3’te proje dosyaları ve geçmiş (NFS değil)	herhangi bir S3 hizmeti, bkz. S3; küme içi örnek olarak oradaki Garage
Derlemeler ve yüklemeler için replika başına yerel disk	her düğümde hostPath /srv/overleaf-ha
Kalıcı yönlendirme, WebSocket’ler, 10 dk zaman aşımları, 50 MB yüklemeler	Overleaf’in örnek yapılandırmasıyla HAProxy
Bir replikanın yanında tekil (singleton) git-bridge	kardeşi overleaf-0 olan git-bridge

S3’ü baştan planlayın. Dosyalarını zaten kendi biriminde tutan bir örnek önce S3 geçişi gerektirir. Bu kurulum 5. adımdaki Deployment’ın yerini alır: StatefulSet’i uygulamadan önce onu silin (kubectl delete -f 40-overleaf.yaml).

1. S3 depolama

   Üç bucket’ı ve iki kullanıcıyı S3 sayfasında açıklandığı gibi, kendi S3 hizmetinizle veya kümedeki Garage ile kurun ve dört anahtarı overleaf-s3 Secret’ına koyun. Aşağıdaki yapılandırma o sayfadaki Garage örneğini kullanır.

2. Yapılandırma

   Bu ConfigMap, 30-config.yaml dosyasının yerini alır. S3 ve git-bridge ekler ve OVERLEAF_SITE_URL değerini yük dengeleyiciye yönlendirir:

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

   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}
   

   • Deployment değil, StatefulSet. Her replika, yük dengeleyici çerezinin ve git-bridge’in başvurduğu sabit bir ad (overleaf-0, overleaf-1, …) alır ve OrderedReady önce yalnızca overleaf-0 pod’unu başlatır; böylece veritabanı geçişlerini yalnızca bir replika çalıştırır.
   • Düğüm başına bir replika. Her replika derlemelerini kendi düğümünün Docker’ı üzerinden başlatır ve bunları kendi düğümünün /srv/overleaf-ha dizininde tutar.
   • Replika başına V1_HISTORY_URL. Her replika, git-bridge’in onlara erişebilmesi için geçmiş bağlantılarını kendi adıyla verir.
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
   

   GIT_BRIDGE_HOST değerinin neden sabit bir IP adresi olduğunu öğrenmek için Git entegrasyonu sayfasına bakın.

5. Yük dengeleyici

   HAProxy yapılandırması, Overleaf’in örneğinin beş değişiklik yapılmış hâlidir: /git/ gibi overleaf-0’a yönlendirilen /project/<id>/mcp (bkz. MCP Sunucusu), 8080 portunda düz HTTP (imaj root olmayan bir kullanıcı olarak çalışır ve bu kullanıcı containerd altında 80 portuna bağlanamaz), küme DNS’i üzerinden bulunan sunucular (pod IP’leri her yeniden başlatmada değişir), her düğümün yanıt vermesi için bir DaemonSet ve varsayılan roundrobin yerine balance leastconn (aşağıdaki Soru&Cevap bölümüne bakın).

   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, kullanıcıların IP adreslerini X-Forwarded-For içinde korur.

6. TLS

   HTTPS’i TLS proxy sayfasında açıklandığı gibi HAProxy’de sonlandırın, ardından 60-config.yaml içinde OVERLEAF_SITE_URL değerini https:// adresine ve OVERLEAF_SECURE_COOKIE: "true" olarak ayarlayın.

​

Neler beklenmeli

Her biri 2 vCPU ve 4 GB belleğe sahip üç düğümde, MongoDB, Redis, Garage, git-bridge ve HAProxy aynı düğümlerdeyken üç replikayı test ettik:

• Aynı anda 600 sayfalık bir belgeyi derleyen 12 kullanıcı: 12’si de derledi ve PDF’lerini aldı, replika başına 4 kullanıcı; bir tur 8 ila 18 saniye sürdü. Her düğümde en az 1,3 GB kullanılabilir bellek kaldı.
• Her kullanıcı tek bir replikada kalır (server-pro-ha çerezi); derleyen replikadan gelmesi gereken PDF indirmesi de buna dahildir. Aynısı, düzenleyicinin WebSocket’i dahil HTTPS üzerinden de geçerlidir.
• Bir replika durduğunda, HAProxy onu devre dışı olarak işaretleyene kadar kullanıcıları yaklaşık 15 ila 20 saniye boyunca hata alır; ardından başka bir replikaya geçerler ve oturumlar Redis’te bulunduğu için oturumları açık kalır.

​

Soru&Cevap

Neden balance leastconn?

Cevap: Overleaf’in örneğiyle (roundrobin, düğüm başına bir HAProxy), testimizde 12 yeni kullanıcı üç replikaya 8, 3 ve 1 olarak dağıldı ve en yoğun replika en yavaş kullanıcıları 29 saniye bekletti. En az açık bağlantıya sahip replikayı tercih eden leastconn ile (her düzenleyici bir WebSocket’i açık tutar), aynı test 4, 4 ve 4 dağılımını ve 18 saniyeyi verdi. Yapışkanlık değişmez: çerezden gelir.

HAProxy yerine kendi ingress denetleyicimi kullanabilir miyim?

Cevap: Evet; bir çereze göre sabit bir replikaya yönlendiriyorsa, WebSocket’leri destekliyorsa, 10 dakikalık istek sürelerine ve 50 MB’lık yüklemelere izin veriyorsa, keep-alive zaman aşımını 65 saniyenin altında tutuyorsa, X-Forwarded-For ve X-Forwarded-Proto gönderiyorsa ve /git/ ile /project/<id>/mcp isteklerini overleaf-0’a gönderiyorsa. Her isteği dengeleyen bir Service’e değil, replikaların kendi adlarına (overleaf-N.overleaf-hl) yönlendirin.

Dördüncü bir replikayı nasıl eklerim?

Cevap: Docker ve TeX Live imajlarına sahip bir düğüm ekleyin, 70-overleaf.yaml içinde replicas: 4 ayarlayın ve HAProxy yapılandırmasına bir server overleaf-3 ... satırı ekleyin (ve HAProxy’nin yeniden başlaması için config-hash değerini artırın).