> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Nâng cấp trên Kubernetes

> Nâng cấp một bản triển khai Kubernetes của Ayakaleaf Pro, với một hoặc nhiều replica.

Một lần nâng cấp sẽ thay thế tag của image. Phiên bản mới sẽ migrate cơ sở dữ liệu khi khởi động, và các migration này phải chạy **một lần, từ một pod, trong khi không có pod phiên bản cũ nào đang chạy**. Trên Kubernetes, điều này loại trừ việc dùng rolling update thông thường cho một StatefulSet đã được mở rộng.

> [!CAUTION]
>
> Hãy tạo một [bản sao lưu nhất quán](https://ayakaleaf-pro.mintlify.site/vi/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) trước mỗi lần nâng cấp, khi Ayakaleaf Pro đã dừng. Hãy đọc [ghi chú phát hành](https://ayakaleaf-pro.mintlify.site/vi/on-premises/release-notes) để biết các bước của phiên bản mà bạn nâng cấp lên.

Trước khi bắt đầu, trên mọi node chạy Ayakaleaf Pro, hãy pull bất kỳ image TeX Live nào mà phiên bản mới hoặc cấu hình mới của bạn liệt kê, bằng `sudo docker pull`.

> [tab] Một replica
>
> **1. Dừng Ayakaleaf Pro**
>
> ```bash theme={null}
> kubectl -n overleaf scale deployment/overleaf --replicas=0
> kubectl -n overleaf wait --for=delete pod -l app=overleaf --timeout=5m
> ```
>
> **2. Sao lưu**
>
> MongoDB, từ bất kỳ thành viên nào:
>
> ```bash wrap theme={null}
> kubectl -n overleaf exec mongo-0 -- mongodump --quiet --archive --gzip \
>   --uri 'mongodb://mongo-0.mongo:27017,mongo-1.mongo:27017,mongo-2.mongo:27017/sharelatex?replicaSet=overleaf' \
>   > sharelatex-$(date +%F).archive.gz
> ```
>
> Volume dữ liệu, thông qua một pod tồn tại ngắn có mount volume đó (pod này sẽ chạy trên node của volume):
>
> ```bash wrap theme={null}
> kubectl -n overleaf run backup --image=busybox --restart=Never --overrides='
> {"spec":{"containers":[{"name":"backup","image":"busybox","command":["sleep","3600"],
>  "volumeMounts":[{"name":"d","mountPath":"/data"}]}],
>  "volumes":[{"name":"d","persistentVolumeClaim":{"claimName":"overleaf-data"}}]}}'
> kubectl -n overleaf wait --for=condition=Ready pod/backup
> kubectl -n overleaf exec backup -- tar czf - -C /data . > overleaf-data-$(date +%F).tar.gz
> kubectl -n overleaf delete pod backup
> ```
>
> Làm tương tự với volume của git-bridge (`data-git-bridge-0`), và giữ một bản sao của Secret `overleaf-secrets`. Nếu bộ lưu trữ của bạn hỗ trợ [VolumeSnapshots](https://kubernetes.io/docs/concepts/storage/volume-snapshots/), một snapshot của các volume cũng có tác dụng tương tự.
>
> **3. Thay đổi phiên bản và khởi động**
>
> Đặt tag mới trong `40-overleaf.yaml` (và trong `45-git-bridge.yaml`, vốn phải dùng cùng tag), sau đó:
>
> ```bash theme={null}
> kubectl apply -f 40-overleaf.yaml -f 45-git-bridge.yaml
> kubectl -n overleaf scale deployment/overleaf --replicas=1
> kubectl -n overleaf rollout status deployment/overleaf --timeout=20m
> kubectl -n overleaf logs deployment/overleaf | grep 'Finished migrations'
> ```
>
> Deployment dùng `strategy: Recreate`, nên ngay cả khi tag thay đổi cũng không bao giờ có hai phiên bản chạy cùng lúc.

> [tab] Nhiều replica
>
> Dành cho thiết lập trong [Mở rộng theo chiều ngang](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/kubernetes/horizontal-scaling.md).
>
> **1. Dừng tất cả các replica**
>
> ```bash theme={null}
> kubectl -n overleaf scale statefulset/overleaf --replicas=0
> kubectl -n overleaf wait --for=delete pod -l app=overleaf-ha --timeout=10m
> ```
>
> **2. Sao lưu**
>
> MongoDB như trong tab một replica, các bucket S3 bằng công cụ của nhà cung cấp, volume của git-bridge (`data-git-bridge-0`) và các Secret. `/srv/overleaf-ha` của các replica chỉ chứa kết quả biên dịch và không cần sao lưu.
>
> **3. Khởi động một replica với phiên bản mới**
>
> Đặt tag mới trong `70-overleaf.yaml` và `75-git-bridge.yaml`, và `replicas: 1`:
>
> ```bash theme={null}
> kubectl apply -f 70-overleaf.yaml -f 75-git-bridge.yaml
> kubectl -n overleaf rollout status statefulset/overleaf --timeout=20m
> kubectl -n overleaf logs overleaf-0 | grep 'Finished migrations'
> ```
>
> Kiểm tra rằng bạn có thể đăng nhập, mở một dự án và biên dịch.
>
> **4. Khởi động các replica còn lại**
>
> Đặt lại `replicas: 3` và áp dụng. `OrderedReady` sẽ khởi động chúng lần lượt từng cái một.
>
> ```bash theme={null}
> kubectl apply -f 70-overleaf.yaml
> kubectl -n overleaf rollout status statefulset/overleaf --timeout=20m
> ```
>
> > [!WARNING]
> >
> > Không thay đổi image của một StatefulSet đã mở rộng đang chạy bằng `kubectl set image` hoặc `kubectl apply`: rolling update sẽ khởi động phiên bản mới, cùng các migration của nó, trong khi các replica cũ vẫn đang phục vụ người dùng. Các thay đổi cấu hình không kèm phiên bản mới thì có thể thực hiện bằng rolling restart: `kubectl -n overleaf rollout restart statefulset/overleaf`.

### MongoDB và Redis

Hãy nâng cấp chúng riêng biệt với Ayakaleaf Pro. Với MongoDB, hãy làm theo [Cập nhật MongoDB](https://ayakaleaf-pro.mintlify.site/vi/on-premises/maintenance/updating-mongodb.md) (mỗi lần một phiên bản chính, đặt `featureCompatibilityVersion` sau mỗi bước); một replica set sẽ nhận image mới lần lượt từng thành viên khi bạn thay đổi image trong `10-mongo.yaml`, vì StatefulSet lần lượt thay thế `mongo-2`, `mongo-1` và `mongo-0`.

### Khôi phục phiên bản cũ

Dừng Ayakaleaf Pro như trên, khôi phục MongoDB từ tệp lưu trữ (`mongorestore --drop --archive --gzip`) và các volume hoặc bucket từ bản sao lưu, đặt lại tag cũ và khởi động lại. Nếu không làm vậy, các migration của phiên bản mới không thể hoàn tác.

### Q\&A

> [accordion] Một replica vẫn ở trạng thái chưa sẵn sàng, và các replica khác không bao giờ khởi động
>
> **Trả lời:** Với `podManagementPolicy: OrderedReady`, `overleaf-1` chỉ khởi động khi `overleaf-0` đã sẵn sàng, và rolling update không thay thế một pod chưa bao giờ sẵn sàng. Sau khi bạn đã khắc phục nguyên nhân, ví dụ một cài đặt sai trong ConfigMap, hãy xóa pod bị kẹt để StatefulSet tạo lại nó từ template hiện tại:
>
> ```bash theme={null}
> kubectl -n overleaf delete pod overleaf-0
> kubectl -n overleaf rollout status statefulset/overleaf --timeout=20m
> ```
>
> Chúng tôi đã gặp trường hợp này trên cluster thử nghiệm sau khi một cài đặt khiến `overleaf-0` không thể sẵn sàng; việc xóa pod đã giúp cả ba replica khởi động.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.