Backup & Restore — Kubernetes On-Premise

Server Backup chính: MinIO server cài trên 1 Ubuntu server riêng. Tất cả dự liệu toàn bộ hệ thống sẽ được backup về đây có IP 10.128.48.222 có domain tương ứng là http://backup-center.giangit.com.Trong trường hợp không có dns server nội bội thì có thể sử dụng trực tiếp IP thay vì domain

Server Backup phụ : Bổ sung thêm 1 MinIO server cài trên 1 Ubuntu server làm replication cho server backup chính . Dữ liệu backup chính sẽ được replication 1 chiều sang backup phụ có IP 10.128.48.223

Lưu ý: MinIO sẽ cài trực tiếp, không cài đặt bằng docker để tăng hiệu năng. Velero cài vào trong cụm k8s dưới dạng pod

Kiến trúc & phạm vi backup

Điểm quan trọng nhất cần nắm trước khi đọc runbook này: không phải mọi thành phần đều chạy trong cluster Kubernetes. Một số dịch vụ được cài trực tiếp trên các server Ubuntu riêng biệt (không phải pod K8s), nên Velero không backup được chúng — phải backup bằng cron + đẩy thẳng lên MinIO qua mc (MinIO Client) trên từng server đó.

Chạy trong cluster Kubernetes (backup qua Velero + Longhorn)

• Control-plane (3 node) + etcd
• Worker (3 node)
• ArgoCD (namespace argocd)
• cert-manager (namespace cert-manager)
• Grafana / Prometheus / Loki (namespace monitoring) — cài trực tiếp vào cụm
• Toàn bộ ứng dụng do ArgoCD deploy, dữ liệu trên Longhorn/NFS

Chạy ngoài cluster — mỗi thành phần 1 server Ubuntu riêng (backup bằng cron + mc cp thẳng lên MinIO, không qua Velero)

• LB API (HAProxy cho control-plane) — 1 server
• LB External (HAProxy cho worker + ingress) — 1 server
• Harbor — 1 server
• GitLab Runner (Kubernetes executor) — 1 server (runner agent chạy ở đây, job build thực thi bằng pod bên trong cluster)
• MinIO backup server (chính) — 1 server riêng (10.128.48.222)
• MinIO backup server (phụ) — 1 server riêng (10.128.48.223), nhận replication 1 chiều từ MinIO chính qua Bucket Replication (mục 1.5)

Máy quản trị (Admin CLI) — 10.128.48.207

admin có 1 máy Ubuntu riêng dùng để quản trị cụm bằng CLI, kết nối tới control-plane qua LB API (không SSH trực tiếp vào từng control-plane để chạy kubectl). Vì máy này chỉ nói chuyện với cluster qua kubeconfig → LB API, không phải mọi lệnh trong runbook đều chạy tập trung được từ đây — chỉ những lệnh thuần kubectl/velero/mc (không cần chứng chỉ hay file cục bộ chỉ có trên 1 server cụ thể) mới centralize được. Từ mục 2 trở đi, mỗi phần đều có ghi rõ dòng "Chạy ở đâu" để admin biết lệnh nào gõ được ngay trên 10.128.48.207, và lệnh nào bắt buộc phải chạy (hoặc SSH vào) đúng server đích.

Tóm tắt nhanh:

ArgoCD hiện chỉ cài UI, không cài ArgoCD CLI — các bước backup/restore ArgoCD dưới đây dùng kubectl thuần thay vì argocd admin export/import.

StorageClass trong cluster chỉ gồm Longhorn và NFS.

0. Nguyên tắc trước khi bắt đầu

1. Chiến lược backup tập trung on-premise: toàn bộ backup gom về 1 điểm — MinIO server 10.128.48.222 — và không đẩy bản sao ra cloud/off-site. Đây là lựa chọn có đánh đổi thật: nguyên tắc 3-2-1 kinh điển (3 bản sao, 2 loại lưu trữ, 1 bản off-site) khuyến nghị luôn có ít nhất 1 bản ở địa điểm khác để chống rủi ro mất cả cluster lẫn backup cùng lúc (cháy phòng máy, ngập nước, mất điện diện rộng...).Runbook này tập trung vào việc làm cho bản backup on-premise duy nhất đó đáng tin cậy nhất có thể — đã có RAID 6 ở tầng đĩa (mục 1.1), và có thêm các bước nâng cấp dự phòng ở tầng server/site tại mục 1.5 nếu muốn giảm rủi ro hơn nữa mà vẫn không cần dùng cloud.
2. Backup ứng dụng-nhất-quán (application-consistent) khác với snapshot volume thô. Snapshot lúc GitLab/Harbor đang ghi dữ liệu có thể tạo ra bản backup restore lên bị lỗi database. GitLab và Harbor có quy trình backup riêng ở mục 5, 6.
3. Test restore định kỳ. Một backup chưa từng được restore thử là một backup chưa được xác minh.
4. Tách quyền truy cập MinIO theo từng loại backup — dùng access key/secret key riêng cho từng nhóm (Velero, etcd, GitLab, Harbor, infra-config) thay vì dùng chung 1 root credential cho mọi thứ.

1. Chuẩn bị MinIO server làm kho backup

1.1. Cài đặt MinIO trực tiếp trên Ubuntu server (10.128.48.222)

# Tạo user và thư mục dữ liệu riêng cho MinIO
useradd -r minio-user -s /sbin/nologin
mkdir -p /mnt/minio-data
chown minio-user:minio-user /mnt/minio-data

# Tải binary MinIO server chính thức
wget https://dl.min.io/server/minio/release/linux-amd64/minio -O /usr/local/bin/minio
chmod +x /usr/local/bin/minio
chown minio-user:minio-user /usr/local/bin/minio

# File biến môi trường
cat <<ENV_EOF > /etc/default/minio
MINIO_VOLUMES="/mnt/minio-data"
MINIO_OPTS="--address :9000 --console-address :9001"
MINIO_ROOT_USER=backup-admin
MINIO_ROOT_PASSWORD=<mật-khẩu-mạnh>
ENV_EOF
chmod 600 /etc/default/minio

# Systemd service
cat <<SERVICE_EOF > /etc/systemd/system/minio.service
[Unit]
Description=MinIO Object Storage
After=network-online.target
Wants=network-online.target

[Service]
User=minio-user
Group=minio-user
EnvironmentFile=/etc/default/minio
ExecStart=/usr/local/bin/minio server \$MINIO_VOLUMES \$MINIO_OPTS
Restart=always
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
SERVICE_EOF

systemctl daemon-reload
systemctl enable --now minio
systemctl status minio

Console quản trị truy cập qua: http://backup-center.giangit.com:9001

1.2. Cài mc (MinIO Client) trên tất cả server cần đẩy backup lên

Chạy trên: control-plane (etcd), server GitLab, server Harbor, server LB API, server LB External, server GitLab Runner, bao gồm bất kỳ máy nào dùng để chạy lệnh restore và máy quản trị

wget https://dl.min.io/client/mc/release/linux-amd64/mc -O /usr/local/bin/mc
chmod +x /usr/local/bin/mc

# Đăng ký alias trỏ tới MinIO server backup
mc alias set backupminio http://10.128.48.222:9000 backup-admin '<mật-khẩu-mạnh>'
mc admin info backupminio   # kiểm tra kết nối thành công

1.3. Tạo các bucket riêng theo từng loại backup

mc mb backupminio/etcd-backup
mc mb backupminio/longhorn-backup
mc mb backupminio/velero
mc mb backupminio/gitlab-backup
mc mb backupminio/harbor-backup
mc mb backupminio/infra-config-backup
mc ls backupminio

1.4. (Khuyến nghị) Tạo access key riêng theo từng mục đích thay vì dùng chung root

mc admin user add backupminio velero-svc '<mật-khẩu-riêng>'
mc admin policy attach backupminio readwrite --user velero-svc
# Lặp lại tương tự cho etcd-svc, gitlab-svc, harbor-svc, infra-svc nếu muốn tách quyền chi tiết hơn

1.5. Tăng độ dự phòng cho MinIO — triển khai Replication MinIO server)

Bước 1 — Cài MinIO trên server phụ (10.128.48.223), làm giống hoàn toàn mục 1.1 (binary + systemd), chỉ khác IP/hostname — ổ đĩa cũng đã có RAID 6 sẵn nên không cần cấu hình thêm gì ở tầng đĩa. Có thể dùng MINIO_ROOT_USER/MINIO_ROOT_PASSWORD khác với MinIO chính nếu muốn, chỉ cần nhất quán với alias mc sẽ đăng ký ở Bước 2.

Bước 2 — Đăng ký alias và bật replication (chạy trên MinIO chính, hoặc từ máy quản trị 10.128.48.207 nếu đã cài mc + có alias backupminio trỏ tới MinIO chính):

# Đăng ký alias tới MinIO phụ
mc alias set backupminio2 http://10.128.48.223:9000 backup-admin '<mật-khẩu-minio-phụ>'
mc admin info backupminio2   # xác nhận kết nối được tới MinIO phụ trước khi tiếp tục

# Bật versioning (bắt buộc phải có trước khi bật replication) cho từng bucket cần nhân bản
mc version enable backupminio/etcd-backup
mc version enable backupminio2/etcd-backup

# Tạo replication rule 1 chiều: mọi thay đổi trên bucket chính tự động đồng bộ sang bucket phụ
mc replicate add backupminio/etcd-backup \
  --remote-bucket http://backup-admin:'<mật-khẩu-minio-phụ>'@10.128.48.223:9000/etcd-backup

Lặp lại Bước 2 (bật versioning + tạo replication rule) cho từng bucket còn lại: longhorn-backup, velero, gitlab-backup, harbor-backup, infra-config-backup.

Bước 3 — Kiểm chứng replication đang hoạt động:

# Xem trạng thái/thống kê replication của 1 bucket
mc replicate status backupminio/etcd-backup

# Kiểm chứng thực tế: tạo 1 file test trên bucket chính, đợi vài giây, kiểm tra đã có ở MinIO phụ chưa
echo "test-replication" > /tmp/test-replication.txt
mc cp /tmp/test-replication.txt backupminio/etcd-backup/
sleep 5
mc ls backupminio2/etcd-backup/   # phải thấy file test-replication.txt xuất hiện ở đây
mc rm backupminio/etcd-backup/test-replication.txt backupminio2/etcd-backup/test-replication.txt   # dọn file test

Với Replication server đã triển khai: dù server MinIO chính bị phá huỷ hoàn toàn, dữ liệu vẫn còn nguyên trên MinIO phụ — cập nhật lại quy trình restore (mục 2-9) để trỏ mc alias/kubeconfig sang MinIO phụ (backupminio2) trong trường hợp MinIO chính không còn khả dụng.

2. Backup & Restore etcd (quan trọng nhất)

2.0. Kiểm tra & cài đặt etcdctl (etcd-client) trước khi backup

Gói etcd-client chưa chắc được cài sẵn theo mặc định trên mọi control-plane node (tuỳ cách dựng cluster bằng kubeadm) — kiểm tra trước khi chạy bước 2.1, tránh script cron fail âm thầm vì thiếu binary.

# Chạy trên TỪNG control-plane node
which etcdctl
# Nếu không thấy thông tin output thì tiến hành cài đặt thủ công
apt update && apt install -y etcd-client
# Xác nhận version, và xác nhận etcdctl gọi được vào etcd cục bộ
etcdctl version
ETCDCTL_API=3 etcdctl endpoint health \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

2.1. Script backup (chạy trên từng control-plane node + cron)

#!/bin/bash
# /usr/local/bin/backup-etcd.sh
set -e
DATE=$(date +%F-%H%M)
SNAPSHOT_DIR=/opt/etcd-backup
mkdir -p $SNAPSHOT_DIR

ETCDCTL_API=3 etcdctl snapshot save $SNAPSHOT_DIR/etcd-snapshot-$DATE.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# Đẩy thẳng lên MinIO qua mc (không cần mount gì cả)
mc cp $SNAPSHOT_DIR/etcd-snapshot-$DATE.db backupminio/etcd-backup/$(hostname)/

# Giữ 7 bản gần nhất tại local, retention dài hạn xử lý bằng lifecycle rule trên bucket (mục 2.3)
ls -1t $SNAPSHOT_DIR/etcd-snapshot-*.db | tail -n +8 | xargs -r rm --

Cron mỗi 6 giờ:

crontab -e
0 */6 * * * /usr/local/bin/backup-etcd.sh >> /var/log/backup-etcd.log 2>&1

2.2. Restore etcd

# Tải snapshot cần restore về từ MinIO
mc cp backupminio/etcd-backup/<node>/etcd-snapshot-<ngày>.db /opt/etcd-backup/restore.db

mv /etc/kubernetes/manifests/etcd.yaml /tmp/
mv /etc/kubernetes/manifests/kube-apiserver.yaml /tmp/

ETCDCTL_API=3 etcdctl snapshot restore /opt/etcd-backup/restore.db \
  --name <tên-node> \
  --initial-cluster <node1>=https://<ip1>:2380,<node2>=https://<ip2>:2380,<node3>=https://<ip3>:2380 \
  --initial-cluster-token etcd-cluster-restore \
  --initial-advertise-peer-urls https://<ip-node-hiện-tại>:2380 \
  --data-dir /var/lib/etcd-restore

mv /tmp/etcd.yaml /etc/kubernetes/manifests/
mv /tmp/kube-apiserver.yaml /etc/kubernetes/manifests/

kubectl get nodes
kubectl get pods -A

Lưu ý: phải restore đồng thời trên cả 3 control-plane node với cùng 1 snapshot, đổi tên data-dir để tránh nhầm dữ liệu cũ.

2.3. Lifecycle rule tự dọn snapshot cũ trên MinIO (thay cho việc tự xoá thủ công)

mc ilm rule add backupminio/etcd-backup --expire-days 30

3. Velero — backup resource Kubernetes + dữ liệu Volume

Velero backup (a) manifest/resource (ArgoCD Application, cert-manager Certificate, ConfigMap, Secret...) và (b) dữ liệu PV qua node-agent (Kopia/Restic) — hoạt động đồng nhất cho cả Longhorn và NFS.

3.0. Cài đặt Velero CLI trên máy quản trị

# Chạy trên máy quản trị 10.128.48.207 (link download: https://github.com/velero-io/velero/releases/tag/v1.18.2)
wget https://github.com/velero-io/velero/releases/download/v1.18.2/velero-v1.18.2-linux-amd64.tar.gz
tar -xzf velero-v1.18.2-linux-amd64.tar.gz

sudo cp velero-v1.18.2-linux-amd64/velero /usr/local/bin/
sudo chmod +x /usr/local/bin/velero

# Xác nhận cài đặt thành công (client-only vì chưa install Velero vào cluster ở bước 3.1)
velero version --client-only

3.1. Cài đặt Velero vào cluster

Tạo file credential cho Velero trước khi chạy lệnh install, vì velero install cần đọc file này ngay khi chạy (credentials-velero):

# File: credentials-velero
[default]
aws_access_key_id = velero-svc
aws_secret_access_key = <mật-khẩu-riêng-của-velero-svc>

Sau khi đã có file credentials-velero cùng thư mục, chạy:

velero install \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.9.0 \
  --bucket velero \
  --backup-location-config region=minio,s3ForcePathStyle="true",s3Url=http://10.128.48.222:9000 \
  --secret-file ./credentials-velero \
  --use-node-agent \
  --default-volumes-to-fs-backup

3.2. Lịch backup định kỳ

# Backup toàn cluster mỗi ngày, giữ 14 ngày
velero schedule create daily-full \
  --schedule="0 1 * * *" \
  --ttl 336h0m0s

# Backup riêng các namespace quan trọng trong cluster (GitLab/Harbor KHÔNG có ở đây vì chạy ngoài cluster)
velero schedule create hourly-critical-ns \
  --schedule="0 * * * *" \
  --include-namespaces argocd,cert-manager,monitoring \
  --ttl 72h0m0s

Kiểm chứng ngay bằng 1 bản backup thử (không cần chờ tới giờ chạy theo schedule):

# Tạo backup thủ công ngay lập tức, --wait để đứng chờ tới khi xong luôn
velero backup create test-backup --include-namespaces argocd --wait

# Kiểm tra kết quả — Phase phải là "Completed"
velero backup describe test-backup --details

# Nếu Phase là "PartiallyFailed" hoặc "Failed", xem log chi tiết để biết lỗi ở đâu
velero backup logs test-backup

# Sau khi xác nhận ổn, có thể xoá bản test này (không xoá dữ liệu gốc trong cluster, chỉ xoá bản backup)
velero backup delete test-backup --confirm

3.3. Restore

velero backup get
velero restore create --from-backup daily-full-20250101010000
velero restore create --from-backup daily-full-20250101010000 --include-namespaces monitoring
velero restore describe <tên-restore>
velero restore logs <tên-restore>

4. Longhorn — backup native qua S3 (MinIO)

kubectl create secret generic minio-secret \
  --from-literal=AWS_ACCESS_KEY_ID=backup-admin \
  --from-literal=AWS_SECRET_ACCESS_KEY='<mật-khẩu-mạnh>' \
  --from-literal=AWS_ENDPOINTS=http://10.128.48.222:9000 \
  -n longhorn-system

s3://longhorn-backup@us-east-1/

kubectl apply -f - <<EOF
apiVersion: longhorn.io/v1beta2
kind: BackupTarget
metadata:
  name: default
  namespace: longhorn-system
spec:
  backupTargetURL: s3://longhorn-backup@us-east-1/
  credentialSecret: minio-secret
  pollInterval: 5m0s
EOF

# Lưu nội dung dưới đây vào file recurring-job-daily-backup.yaml, rồi:
kubectl apply -f recurring-job-daily-backup.yaml

apiVersion: longhorn.io/v1beta2
kind: RecurringJob
metadata:
  name: daily-backup
  namespace: longhorn-system
spec:
  cron: "30 1 * * *"
  task: "backup"
  groups:
  - default
  retain: 14
  concurrency: 2

kubectl get recurringjobs.longhorn.io -n longhorn-system

kubectl apply -f - <<EOF
apiVersion: longhorn.io/v1beta2
kind: Volume
metadata:
  name: restored-vol
  namespace: longhorn-system
spec:
  fromBackup: "s3://longhorn-backup@us-east-1/?backup=<backup-id>"
  size: "20Gi"
  numberOfReplicas: 3
EOF

# Chạy trực tiếp trên server Ubuntu cài GitLab
gitlab-backup create

# Backup kèm gitlab-secrets.json và gitlab.rb — KHÔNG nằm trong gitlab-backup create,
# nhưng bắt buộc phải có để restore đúng (chứa khoá mã hoá CI variables, 2FA...)
mkdir -p /root/gitlab-config-backup
cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab.rb /root/gitlab-config-backup/

# Đẩy thẳng lên MinIO (đã cài mc + alias backupminio ở mục 1.2)
mc cp /var/opt/gitlab/backups/*.tar backupminio/gitlab-backup/
mc cp --recursive /root/gitlab-config-backup/ backupminio/gitlab-backup/config/

crontab -e
0 2 * * * /usr/bin/gitlab-backup create CRON=1 && mc cp /var/opt/gitlab/backups/*.tar backupminio/gitlab-backup/ >> /var/log/gitlab-backup.log 2>&1

# Tải file backup cần restore về từ MinIO
mc cp backupminio/gitlab-backup/<file>_gitlab_backup.tar /var/opt/gitlab/backups/
chown git:git /var/opt/gitlab/backups/<file>_gitlab_backup.tar

gitlab-ctl stop puma
gitlab-ctl stop sidekiq
gitlab-backup restore BACKUP=<timestamp>

# Nếu restore lên server mới hoàn toàn, phục hồi thêm 2 file cấu hình đã backup:
mc cp backupminio/gitlab-backup/config/gitlab-secrets.json /etc/gitlab/
mc cp backupminio/gitlab-backup/config/gitlab.rb /etc/gitlab/

gitlab-ctl reconfigure
gitlab-ctl restart
gitlab-rake gitlab:check SANITIZE=true

cd /opt/harbor    # thay bằng đường dẫn cài đặt Harbor thực tế 

# Dừng tạm để backup nhất quán data volume
docker compose stop

DATE=$(date +%F)
tar czf /tmp/harbor-data-$DATE.tar.gz /data   # /data = data_volume khai báo trong harbor.yml

docker compose start

# Backup DB riêng — có thể chạy khi Harbor vẫn đang hoạt động (ít downtime hơn tar toàn bộ /data)
docker exec harbor-db pg_dumpall -U postgres > /tmp/harbor-db-$DATE.sql
# (kiểm tra đúng tên container bằng: docker ps | grep harbor)

mc cp /tmp/harbor-data-$DATE.tar.gz backupminio/harbor-backup/
mc cp /tmp/harbor-db-$DATE.sql backupminio/harbor-backup/

crontab -e
0 3 * * * /usr/local/bin/backup-harbor.sh >> /var/log/harbor-backup.log 2>&1

cd /opt/harbor
docker compose stop

mc cp backupminio/harbor-backup/harbor-data-<ngày>.tar.gz /tmp/
tar xzf /tmp/harbor-data-<ngày>.tar.gz -C /

docker compose up -d harbor-db
mc cp backupminio/harbor-backup/harbor-db-<ngày>.sql /tmp/
cat /tmp/harbor-db-<ngày>.sql | docker exec -i harbor-db psql -U postgres

docker compose start

NS=argocd
DATE=$(date +%F)
OUTDIR=/tmp/argocd-backup-$DATE
mkdir -p $OUTDIR

for res in applications applicationsets appprojects; do
  kubectl get $res -n $NS -o yaml > $OUTDIR/$res.yaml
done

kubectl get configmap argocd-cm argocd-rbac-cm argocd-cmd-params-cm -n $NS -o yaml > $OUTDIR/configmaps.yaml
# Secret chứa repo credentials, SSO config — dữ liệu nhạy cảm, giữ quyền truy cập chặt trên MinIO
kubectl get secret -n $NS -o yaml > $OUTDIR/secrets.yaml

tar czf argocd-backup-$DATE.tar.gz -C /tmp argocd-backup-$DATE
mc cp argocd-backup-$DATE.tar.gz backupminio/infra-config-backup/argocd/

mc cp backupminio/infra-config-backup/argocd/argocd-backup-<ngày>.tar.gz .
tar xzf argocd-backup-<ngày>.tar.gz
kubectl apply -f argocd-backup-<ngày>/configmaps.yaml
kubectl apply -f argocd-backup-<ngày>/secrets.yaml
kubectl apply -f argocd-backup-<ngày>/appprojects.yaml
kubectl apply -f argocd-backup-<ngày>/applications.yaml
kubectl apply -f argocd-backup-<ngày>/applicationsets.yaml

#!/bin/bash
# /usr/local/bin/backup-infra.sh — chạy trên LB-API, LB-External, và GitLab Runner (mỗi server 1 bản)
DATE=$(date +%F)
HOST=$(hostname)
mkdir -p /tmp/infra-backup

case "$HOST" in
  *lb-api*)
    tar czf /tmp/infra-backup/haproxy-api-$HOST-$DATE.tar.gz /etc/haproxy
    ;;
  *lb-external*)
    tar czf /tmp/infra-backup/haproxy-external-$HOST-$DATE.tar.gz /etc/haproxy
    ;;
  *runner*)
    tar czf /tmp/infra-backup/gitlab-runner-$HOST-$DATE.tar.gz /etc/gitlab-runner
    ;;
esac

mc cp --recursive /tmp/infra-backup/ backupminio/infra-config-backup/$HOST/

0 4 * * * /usr/local/bin/backup-infra.sh >> /var/log/infra-backup.log 2>&1