Runbook // Quy trình vận hànhceph

Ceph — Sự cố, maintenance và recovery

DOC PATH runbooks/ceph/failure-recovery-ha

Doc Type: Runbook
Technology: ceph
Status: Active
Tags: CephRecoveryHAOSD

Khoanh vùng OSD down, phục hồi daemon, quorum, host và thay OSD có kiểm soát. Đọc theo thứ tự các chương hoặc chọn mục cần tra cứu trong mục lục.

Phạm vi, baseline và tác động

Baseline and Fault Model

Lab có ba host, ba MON, hai MGR, ba OSD, replicated pools size 3/min_size 2. Khi một host mất, nhiều daemon có thể mất cùng lúc; còn I/O không đồng nghĩa còn đủ durability/redundancy.

Trước mỗi thay đổi, ghi thời điểm, daemon/host/device, MON quorum, MGR role, PG state, service placement và checksum của workload test. Thay mọi placeholder bằng inventory đang quan sát; không tái dùng OSD ID hoặc /dev/sdX từ một lần thao tác trước.

Sự cố và HA

OSD failure

Khi OSD down nhưng vẫn IN, CRUSH vẫn xem OSD thuộc desired placement. Sau timeout hoặc thao tác quản trị, OSD có thể OUT để Ceph remap replica sang OSD khác.

Host failure

Host failure có thể đồng thời làm mất MON/MGR/OSD/RGW/exporters. HA phải được đánh giá theo từng service, không chỉ nhìn một health flag.

Safe maintenance

Maintenance mode phục vụ việc dừng host có kế hoạch. cephadm kiểm tra điều kiện an toàn trước khi dừng daemon. Các OSD flag như noout/noup/nodown/noin có thể kiểm soát cách cluster xử lý thay đổi trạng thái trong thời gian maintenance.

OSD replacement

Xác định OSD/device bị lỗi bằng stable path.
Đảm bảo dữ liệu vẫn còn đủ replica và có replacement capacity.
Mark OUT khi xác định OSD không quay lại.
Provision replacement OSD.
Theo dõi recovery/backfill đến active+clean.
Chạy ceph osd safe-to-destroy <old-id>.
Chỉ khi PASS mới remove old OSD metadata/daemon.

Vấn đề

Một Ceph OSD được báo không hoạt động và trạng thái health của cluster bị degraded. Cần xác định lỗi nằm ở daemon, server, thiết bị hay mạng của cluster trước khi chọn cách khắc phục.

Triệu chứng

Các dấu hiệu cần đối chiếu:

ceph -s báo trạng thái health bị degraded;
ceph osd tree hiển thị một OSD ở trạng thái down;
placement group có thể đang degraded hoặc recovering;
server bị ảnh hưởng vẫn truy cập được;
thiết bị dữ liệu vẫn hiển thị trên server bị ảnh hưởng.

Ghi lại output health và thời điểm chính xác trước khi thay đổi.

Môi trường

Hạng mục	Phạm vi ví dụ
Triển khai	`cephadm`
Cluster	Lab mẫu ba node
Lỗi	Một OSD daemon dừng hoặc không khả dụng
Host	`<affected-host>`
OSD	`<osd-id>`
Thiết bị	`<device>`

Thay giá trị đại diện bằng giá trị quan sát được. Không mặc định OSD ID từ bài thực hành trước.

Điều tra và chọn nhánh xử lý

Establish the Fault Boundary

ceph -s
ceph health detail
ceph osd tree
ceph pg stat
ceph orch ps
ceph quorum_status -f json-pretty
ceph mgr stat
ceph mgr services

Phân biệt down/up (reachability/process) với out/in (membership). OSD down không mặc định cần mark out: trước hết xác định lỗi nằm ở daemon, host, network hay device.

Điều tra

1. Xác nhận triệu chứng cấp cluster

Bắt đầu bằng các lệnh chỉ đọc:

ceph -s
ceph health detail
ceph osd tree

Xác nhận cảnh báo đúng OSD cần điều tra và ghi nhận các OSD, server hoặc placement group khác có bị ảnh hưởng hay không.

2. Kiểm tra daemon

Kiểm tra trạng thái daemon bị ảnh hưởng qua orchestrator:

ceph orch ps --daemon-type osd --hostname <affected-host>

Nếu daemon dừng trong khi server ở trạng thái healthy, fault boundary có thể nằm ở tiến trình daemon hoặc cấu hình cục bộ. Nếu server không truy cập được, tiếp tục điều tra server/mạng thay vì khởi động lại daemon từ xa.

3. Kiểm tra server và thiết bị

Từ môi trường quản trị đã được phê duyệt, kiểm tra server và thiết bị:

ssh <affected-host> hostname
ssh <affected-host> lsblk

Kiểm tra dịch vụ cục bộ và system log qua công cụ thu thập log đã được phê duyệt. Tìm lỗi I/O thiết bị, lỗi filesystem, cạn tài nguyên và các thay đổi gần đây.

4. Chọn nhánh điều tra

Quan sát	Fault Boundary có thể xảy ra	Hành động tiếp theo
Server truy cập được, thiết bị healthy, daemon dừng	Dịch vụ/tiến trình OSD	Xác minh khởi động lại daemon là an toàn.
Server không truy cập được	Server, nguồn điện hoặc mạng	Khôi phục truy cập server trước khi đổi OSD.
Thiếu thiết bị hoặc có lỗi I/O	Device hoặc storage path	Dừng và dùng quy trình xử lý thiết bị lỗi.
Nhiều OSD bị ảnh hưởng	Dependency dùng chung hoặc sự kiện cluster	Điều tra dependency chung của server, mạng và storage.

Không kết luận root cause chỉ từ ceph -s; lệnh này cho thấy triệu chứng, không nhất thiết cho biết fault boundary.

Root Cause

Chỉ xác nhận nguyên nhân khi log và kiểm tra host/device/network đều phù hợp với giả thuyết. Daemon dừng có thể là hệ quả của lỗi thiết bị, cạn tài nguyên hoặc mất mạng; trạng thái down tự nó không giải thích nguyên nhân.

Kiểm tra sự cố

Triệu chứng	Kiểm tra đầu tiên	Hướng suy luận
HEALTH_WARN	`ceph health detail`	Xác định warning thuộc MON/OSD/PG/capacity/cephadm.
OSD down	`ceph osd tree; orch ps; host reachability`	Daemon stop, host mất, disk lỗi, network heartbeat.
PG degraded	`ceph pg stat; osd tree; pool size/min_size`	Thiếu replica hoặc chưa có recovery target.
PG stuck peering	`ceph health detail; pg query`	OSD history/authoritative log/quorum issue.
MON out of quorum	quorum_status; time sync; network	Network, clock skew, MON process/storage.
Dashboard unavailable	`ceph mgr stat; mgr services`	Active MGR thay đổi hoặc module/endpoint lỗi.
Slow ops	`ceph health detail; osd perf; network/disk metrics`	Disk latency, recovery contention, network saturation.
cephadm host offline	orch host ls; check-host; SSH	Management network/SSH khác với Ceph public plane.
Device inventory stale	orch device ls –refresh; lsblk/by-path	Host reboot/device rename/cache inventory.

Choose the Recovery Branch

Observation	Action
OSD daemon down, host/device hoạt động bình thường	Dùng luồng điều tra OSD Down; chỉ restart daemon sau khi xác nhận không có lỗi device.
One MON down in a three-MON cluster	Xác nhận quorum còn đa số, khôi phục MON và kiểm tra lại 3/3; MON map khác với quorum thực tế.
Active MGR cần chuyển role	Dùng `ceph mgr fail <active-mgr>`; không stop active MGR bằng `--force`.
Planned host maintenance	Dùng maintenance workflow; dừng khi Ceph báo không còn đủ service capacity, ví dụ RGW chỉ có một instance.
Device failed or missing	Chuẩn bị replacement capacity, để recovery hoàn tất và chờ `safe-to-destroy` trước khi remove OSD cũ.

Troubleshooting Quick Reference

Triệu chứng	Kiểm tra / xử lý
`rados put` không thấy file host	Bind file bằng `cephadm shell --mount`; kiểm tra container path.
RBD `Module rbd not found`	Kiểm tra kernel/module trên client; không tự tắt image features hoặc sửa pool.
Hai `/dev/rbdX` trỏ cùng image	Đối chiếu `rbd device list`, watchers và mount; gỡ mapping thừa.
`lsblk` thiếu FSTYPE	Dùng `blkid -p`, `file -sL`, `findmnt`; không format lại theo phỏng đoán.
Snapshot Delete disabled	Kiểm tra protection và child dependency; flatten nếu cần trước Unprotect/Delete.
CephFS hai placement hosts nhưng một MDS	Kiểm tra service Count, `max_mds` và standby role.
CephFS mount unauthorized/no MDS	Kiểm tra client ID không lặp `client.`, caps/path, secret và MON endpoints.
Subvolume Edit 404/500, thiếu `client_respect_subvolume_snapshot_visibility`	Kiểm tra khả năng hỗ trợ của Dashboard/config lookup; đối chiếu CLI và dữ liệu, không Save form lỗi.
Evicted mount vẫn xuất hiện	Mount entry khác MDS session; clean unmount/remount và xác nhận nonce mới.
RGW stats bằng 0 nhưng GET được	Đồng bộ user stats và kiểm tra bucket stats.
S3 GET mất object sau DELETE	Với Versioning, xem Delete Marker/old versions trước khi kết luận mất dữ liệu.
Dashboard healthy nhưng infrastructure alert	Kiểm tra target, host usage, inode và trend riêng với Ceph health.

Khôi phục OSD daemon

Khắc phục

Với trường hợp chỉ lỗi daemon, khởi động lại daemon bị ảnh hưởng bằng quy trình điều phối đã được phê duyệt:

ceph orch daemon restart osd.<osd-id>

Theo dõi thao tác và dừng nếu daemon không hoạt động lại hoặc xuất hiện lỗi thiết bị/server mới. Không dùng khởi động lại daemon cho trường hợp mất thiết bị hoặc lỗi server.

OSD Daemon Recovery

Mark Down thay trạng thái OSD, không tương đương dừng daemon process. Không dùng Stop như bước chẩn đoán mặc định trên cluster đang phục vụ.

Khi host/device hoạt động bình thường và nguyên nhân chỉ là daemon dừng, khởi động lại đúng daemon:

ceph orch ps --daemon-type osd --hostname <affected-host> --refresh
ceph orch daemon start osd.<osd-id>
ceph osd tree
ceph health detail

Kết quả mong đợi: down/in → up/in, PG phục hồi và checksum readback khớp. Nếu OSD up/out, restart không tự chứng minh placement đã đúng; cần xác định vì sao OSD bị mark out trước khi quyết định đưa lại vào.

Với pool size 3/min_size 2, I/O có thể tiếp tục khi một replica mất, nhưng còn phụ thuộc quorum và PG state. Không suy rộng thành mọi pool đều chịu được cùng số lỗi.

Khôi phục control plane và host

MON Quorum and MGR Failover

MON Recovery

MON map chứa daemon không có nghĩa daemon đó đang trong quorum. Với ba MON, mất một MON vẫn còn majority 2/3; kiểm tra quorum thực tế và khôi phục node/daemon bị mất:

ceph mon stat
ceph quorum_status -f json-pretty
ceph orch ps --daemon-type mon --refresh
# Khi host/network đã healthy và daemon cần được start lại
ceph orch daemon start mon.<mon-id>
ceph quorum_status -f json-pretty

Kết quả mong đợi: quorum trở lại 3/3, health detail không còn lỗi liên quan và workload đọc/ghi thành công. Không tiếp tục kế hoạch dừng MON khác khi cluster đang thiếu thành viên quorum.

MGR Role Failover

Trước planned failover, xác nhận standby sẵn sàng. Dùng role failover thay vì force-stop Active MGR:

ceph mgr stat
ceph mgr services
ceph mgr fail <active-mgr-id>
ceph mgr stat
ceph mgr services

Kết quả mong đợi: standby chuyển sang active; cả hai process có thể vẫn running. Endpoint của module Dashboard/Prometheus có thể chuyển sang host mới. MGR role không đại diện cho data path; vẫn cần kiểm tra client/application theo workload của môi trường.

Failback không bắt buộc chỉ để trả lại hostname Active cũ. Hoàn tất khi Active/Standby redundancy và service endpoints hoạt động đúng.

Full Host Failure

Một host tắt đột ngột có thể làm mất MON, OSD, RGW và exporter trên cùng node. RADOS có thể tiếp tục phục vụ I/O trong khi endpoint RGW bị mất hoàn toàn nếu chỉ có một gateway. Vì vậy, cần đánh giá riêng HA của backend và HA của endpoint ứng dụng.

Xác định power/network/management failure trước khi thay OSD membership.
Kiểm tra quorum, PG, application endpoint còn lại; không chỉ đọc host inventory.
Khôi phục host, xác nhận SSH/time sync và các daemon trở lại.
Chờ PG recovery, kiểm tra endpoint và checksum data đã ghi khi degraded.

Nếu host đang maintenance, power-on không tự kết thúc maintenance; dùng workflow Exit Maintenance bên dưới.

Theo dõi recovery

Monitor Recovery

ceph -s
ceph health detail
ceph pg stat
ceph osd safe-to-destroy <old-osd-id>
ceph progress

degraded không đồng nghĩa recovery đang chạy: xem ceph progress, PG state và các flag norecover/nobackfill. Chờ active+clean; PG autoscaler có thể tạo cảnh báo tạm thời trong quá trình hội tụ.

Metric / state	Dùng để xác nhận
`ceph_health_detail{name="PG_DEGRADED"}`	Health condition, không phải throughput recovery.
`ceph_pg_degraded` / `ceph_pg_recovering` / `ceph_pg_clean`	PG đang degraded, recovering hoặc clean theo pool.
`ceph_pool_recovering_bytes_per_sec`	Recovery throughput tại time window được quan sát.
`ceph_pool_recovering_objects_per_sec`	Object recovery rate; giá trị tại thời điểm đo có thể bằng 0 do thời điểm scrape.
`nobackfill` / `norecover`	Flags có thể chặn tiến trình; tìm nguyên nhân/owner trước khi thay.

Nếu gặp TOO_MANY_PGS khi autoscaler merge/split song song recovery, kiểm tra PG count, autoscaler và tiến trình recovery. Không tăng threshold hoặc áp PG cap chỉ để giấu warning khi chưa xác định nguyên nhân.

Maintenance và thay OSD

Planned Host Maintenance

Dùng Dashboard Cluster > Hosts > <host> > Enter Maintenance hoặc CLI tương ứng. Trước khi thao tác, kiểm tra các service chỉ có một instance, dung lượng trống và năng lực phục vụ còn lại.

Nếu maintenance bị chặn do chỉ có một RGW daemon, đánh giá mở rộng placement tại Administration > Services sang hai host, Count=2; xác nhận cả hai endpoint trước khi maintenance. Hai gateway tự nó chưa tạo một HA client endpoint: client/LB phải chuyển được traffic.

ceph orch ls --service_type rgw
ceph orch ps --daemon-type rgw --refresh
ceph orch host maintenance enter <host>
ceph orch host ls
ceph -s

Trong maintenance, Ceph daemons trên host dừng; health có thể báo MON/OSD down, degraded PG và maintenance-related flags. Ghi nhận các flag do workflow đặt, không tự gỡ chúng trong lúc maintenance còn hiệu lực.

Sau khi hoàn tất công việc trên host và host đã online:

ceph orch host maintenance exit <host>
ceph orch host ls
ceph orch ps --hostname <host> --refresh
ceph quorum_status -f json-pretty
ceph osd tree
ceph -s

Kết quả mong đợi: các daemon khởi động lại, maintenance flag được gỡ theo workflow, MON đạt quorum 3/3, OSD up/in, application redundancy được khôi phục và PG đạt active+clean. Không dùng --force để bỏ qua bước kiểm tra năng lực phục vụ.

OSD Replacement Gate

Ghi OSD ID, host, device, health detail và trạng thái PG trước thay đổi.
Xác nhận device cũ không thể trở lại; nhận diện replacement bằng serial/stable path và refresh inventory. /dev/sdX có thể đổi sau reboot.
Provision replacement OSD, chờ replica chuyển sang acting set mới và cluster recovery.
Chỉ khi ceph osd safe-to-destroy <old-osd-id> PASS mới remove OSD cũ.
Xác minh up/in, CRUSH tree, checksum workload test và HEALTH_OK/baseline mong đợi.

Identify the Device

ceph osd metadata <old-osd-id> -f json-pretty
ceph orch device ls --hostname <host> --refresh --wide
# Trên affected host
lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS,SERIAL
ls -l /dev/disk/by-path/
wipefs -n <replacement-device>

Tên /dev/sdX có thể đổi sau tháo lắp hoặc reboot. Serial/stable path cùng inventory hiện tại là căn cứ xác định device, không phải tên Linux được ghi từ trước. Device đang được OSD sử dụng hiển thị Available=No là trạng thái mong đợi.

Provision, Recover and Retire

Khi disk cũ đã xác nhận failed/permanently missing, mark out đúng OSD để loại nó khỏi placement. Device mới phải raw/available và thuộc đúng host failure domain:

ceph osd out <old-osd-id>
ceph orch daemon add osd <host>:<replacement-device>
ceph osd tree
ceph -s
ceph osd map <test-pool> <test-object>
ceph osd safe-to-destroy <old-osd-id>

Với ba OSD/size 3 và không có spare, safe-to-destroy có thể trả EBUSY khi còn PG ánh xạ tới OSD cũ. Cần replacement capacity và recovery trước khi loại bỏ, không force vượt qua kiểm tra. OSD thay thế có thể nhận ID mới.

Chỉ khi acting set đã có replica trên replacement, checksum đạt và safe-to-destroy trả PASS:

ceph orch osd rm <old-osd-id>
ceph orch osd rm status
ceph osd tree
ceph health detail

Chờ quá trình xóa hoàn tất; việc lệnh được chấp nhận chưa có nghĩa thao tác đã xong. Xác nhận OSD còn lại up/in, OSD cũ không còn trong inventory và checksum dữ liệu khớp. Không dùng service spec cũ để provision/remove hàng loạt nếu spec không phản ánh đúng placement thực tế.

Xác minh và phòng ngừa

Kiểm tra sau phục hồi

Layer	Kiểm tra sau recovery
RADOS	PUT/GET object test, so sánh SHA-256 và acting set.
RBD	Image/mapping còn đúng; readback/checksum sau remount hoặc import/export test có phạm vi rõ.
CephFS	Active/Standby MDS, client session, mount và file checksum.
RGW	Endpoint cùng authenticated S3 operation; kiểm tra gateway còn lại khi một host mất.
Cluster	Quorum, MGR role, OSD up/in, PG convergence, capacity và alerting.

HTTP root response của RGW chỉ kiểm tra endpoint; cần request S3 đã xác thực và đọc/ghi object để kiểm tra authorization/data path.

Xác minh

Chạy lại các kiểm tra sau khi daemon khởi động và cluster cập nhật trạng thái:

ceph osd tree
ceph -s
ceph health detail
ceph orch ps --daemon-type osd --hostname <affected-host>

Đối chiếu kết quả:

OSD mục tiêu ở trạng thái up và in nếu đó là trạng thái dự kiến.
Health detail không còn cảnh báo liên quan đến sự cố vừa xử lý.
Các placement group degraded/recovery trở về trạng thái mong đợi.
Không xuất hiện lỗi mới trên server hoặc thiết bị.
Ứng dụng đọc/ghi được dữ liệu và checksum đối chiếu khớp.

Phòng ngừa

Theo dõi riêng trạng thái OSD daemon và health của server/thiết bị.
Ghi OSD ID, server và thiết bị vào ghi chú sự cố.
Duy trì một kịch bản mô phỏng lỗi đã biết là an toàn trong lab.
Liên kết cảnh báo với luồng điều tra và quy trình khôi phục đã phê duyệt.
Xem xét lỗi có cần kiểm tra thiết bị, server hoặc mạng trước khi khởi động lại hay không.