Logo

Personal Ops Runbook

Personal runbook covering infrastructure operations for Cloud, Kubernetes, OpenStack, and Ceph environments. Includes deployment and teardown procedures, node management, cluster monitoring setup, and incident response workflows compiled from day-to-day operational work. Intended strictly for personal reference — configurations and scripts are environment-specific and not guaranteed to work as-is elsewhere.

Runbook: OSD shard & thread config cho mClock (HDD)

Tham số: osd_op_num_shards_hdd, osd_op_num_threads_per_shard_hdd Phạm vi: OSD nền HDD chạy mClock scheduler (mặc định từ Quincy trở đi). Mục đích: Hiểu cơ chế, biết khi nào nên đổi, cách đổi an toàn, và cách verify.

1. Hai tham số này là gì

  • shard = một "làn xử lý" độc lập trong OSD. Mỗi shard có hàng đợi riêng và một bộ lập lịch mClock riêng. Op (client I/O, recovery, backfill, scrub...) được băm theo PG để rơi vào một shard cố định (giữ thứ tự op trên cùng PG).
  • thread per shard = số worker thread cùng rút op ra khỏi hàng đợi của shard đó để xử lý song song.

Điểm cốt lõi cần nhớ: mClock — bộ ra quyết định QoS — sống bên trong từng shard, không phải ở cấp OSD. Vì vậy số shard chính là số "bộ não lập lịch" độc lập trong một OSD.

2. Giá trị mặc định (tham chiếu nhanh)

Tham số Default cũ Default mới
osd_op_num_shards_hdd 5 1
osd_op_num_threads_per_shard_hdd 1 5

Tổng số worker thread không đổi (5 ở cả hai cấu hình) — chỉ khác cách tổ chức hàng đợi.

Tham khảo thêm (không thuộc phạm vi runbook này nhưng để đối chiếu): - SSD: osd_op_num_shards_ssd = 8, osd_op_num_threads_per_shard_ssd = 2 (giữ nguyên, KHÔNG đổi xuống 1). - osd_op_num_shards (chung) mặc định 0 → khi = 0 thì dùng giá trị theo loại thiết bị; nếu đặt khác 0 sẽ đè lên cả hdd/ssd.

3. Vì sao đổi 5 -> 1 shard

Mỗi mClock chỉ điều phối trong phạm vi hàng đợi của nó, và capacity IOPS của OSD bị chia đều theo số shard (vd 300 IOPS / 5 shard = 60 IOPS/shard). Reservation/weight/limit cũng được cấp per-shard.

Hệ quả khi có nhiều shard: - Mỗi mClock chỉ thấy ~1/5 lượng op và quản 1/5 capacity → không có trọng tài tổng thể. - Op băm theo PG nên phân bố lệch: shard này ngập client, shard kia ngập recovery, không san việc cho nhau. - Reservation bị "treo": nếu client op chỉ rơi vào 2/5 shard thì phần reservation client ở 3 shard còn lại nằm không → client thực nhận ít hơn mức cấu hình. - Phương sai (variance) cao là tính chất cấu trúc của "nhiều hàng đợi 1 server" so với "1 hàng đợi nhiều server" — tune profile không gỡ được, chỉ giảm triệu chứng bằng cách hi sinh throughput.

Với 1 shard: toàn bộ op vào một mClock, thấy đầy đủ capacity → một quyết định QoS mạch lạc, 5 thread chỉ thực thi. Đây là lý do gộp về 1 shard lấy lại đúng QoS đã cấu hình.

Lưu ý bối cảnh: đây là biện pháp tạm thời theo docs, đặc thù cho HDD (bài test scale của Ceph chạy trên HDD). NVMe/SSD giữ nhiều shard vì cần song song để khai thác hết thiết bị nhanh — số shard là đánh đổi giữa độ chính xác QoS (ít shard) và tận dụng thiết bị (nhiều shard).

4. Khi nào nên áp dụng / không

Nên áp dụng nếu: - Cluster HDD chạy mClock và đang gặp client I/O bị slow / slow request khi có backfill/recovery. - Đang còn ở default cũ (5/1).

Không kỳ vọng nó: - Làm backfill chạy nhanh hơn — backfill là best-effort, bị ưu tiên thấp theo thiết kế. Đổi shard cải thiện độ ổn định QoS của client, không phải tốc độ backfill. - Giảm read-amplification của EC — backfill/recovery EC vẫn nặng (đọc đủ k shard + decode) bất kể số shard.

5. Kiểm tra giá trị đang chạy

# Giá trị sẽ áp dụng sau lần restart kế tiếp:
ceph config show osd.0 osd_op_num_shards_hdd
ceph config show osd.0 osd_op_num_threads_per_shard_hdd

# Giá trị OSD đang chạy THẬT ngay lúc này (sau khi đã resolve logic chung/đè):
ceph daemon osd.0 config show | grep -E 'osd_op_num_shards|osd_op_num_threads_per_shard'

Nếu đã là 1 / 5 thì không cần làm gì.

6. Quy trình đổi (an toàn, cuốn chiếu)

Quan trọng: số shard chỉ được đọc lúc OSD khởi động. Đổi config xong bắt buộc restart OSD mới có hiệu lực. Việc đổi an toàn — KHÔNG đụng layout dữ liệu on-disk, chỉ là cấu trúc hàng đợi/thread trong RAM.

# 1. Đặt config (chưa có hiệu lực cho tới khi restart)
ceph config set osd osd_op_num_shards_hdd 1
ceph config set osd osd_op_num_threads_per_shard_hdd 5

# 2. Chống cluster tự rebalance trong lúc restart cuốn chiếu
ceph osd set noout

# 3. Restart từng OSD / từng host, CHỜ HEALTH_OK giữa các bước
#    (ví dụ trên 1 host, lặp cho từng host)
systemctl restart ceph-osd@<id>     # hoặc: ceph orch restart osd.<id> nếu dùng cephadm
#    -> theo dõi: watch ceph -s   (đợi active+clean ổn định)

# 4. Gỡ cờ sau khi xong toàn bộ
ceph osd unset noout

Kiểm tra lại sau restart:

ceph daemon osd.<id> config show | grep -E 'osd_op_num_shards|osd_op_num_threads_per_shard'

7. Rollback

ceph config set osd osd_op_num_shards_hdd 5
ceph config set osd osd_op_num_threads_per_shard_hdd 1
# rồi restart cuốn chiếu lại như mục 6

Hoặc xoá hẳn để về default của bản đang chạy:

ceph config rm osd osd_op_num_shards_hdd
ceph config rm osd osd_op_num_threads_per_shard_hdd

8. Kiểm tra liên quan (hay là nguyên nhân thật của slow request)

Trước khi đổ lỗi cho số shard, verify capacity IOPS — đây là thủ phạm phổ biến nhất của slow request liên quan mClock trên HDD.

ceph config show osd.0 osd_mclock_max_capacity_iops_hdd
  • Mặc định 315. Nếu giá trị vô lý (vài nghìn cho HDD) hoặc quá thấp → mClock lập lịch sai.
  • Ngưỡng bỏ qua bench: > 500 hoặc < 50 IOPS → rơi về default 315 kèm WRN trong log. Nếu thấy đúng 315 tròn thì khả năng bench đã bị loại.

Đo lại (4 KiB random write, drop cache trước):

ceph tell osd.0 cache drop
ceph tell osd.0 bench 12288000 4096 4194304 100   # đọc trường "iops"

Block size đo capacity LUÔN là 4 KiB cho mọi thiết bị (HDD/SSD/NVMe) và mọi pool (replica/EC) — đây là đơn vị chuẩn để định nghĩa capacity, không phải để khớp workload. Đừng đo bằng block lớn.

Set thủ công nếu cần:

ceph config set osd.0 osd_mclock_max_capacity_iops_hdd <số_đo_được>
# hoặc global: ceph config set global osd_mclock_max_capacity_iops_hdd <số>
# nếu set global, xoá per-osd cũ trước (per-osd thắng global):
ceph config dump | grep osd_mclock_max_capacity_iops_hdd

9. Liên quan tới tuning backfill/recovery (đừng nhầm với số shard)

  • Số shard / thread quyết định cấu trúc hàng đợi & độ chính xác QoS.
  • mClock profile (*_res / *_lim / *_wgt) quyết định tỉ lệ băng thông giữa client / recovery / best-effort.
  • osd_max_backfills / osd_recovery_max_active_* quyết định số PG backfill song song mỗi OSD — đây là lớp ngoài mClock và bị khoá trừ khi bật: bash ceph config set osd osd_mclock_override_recovery_settings true
  • osd_max_backfills là giới hạn per-OSD (tính cả PG vào lẫn ra). Khi thêm ổ mới, ít OSD đích → tổng song song thấp; khi drain ổ, nhiều OSD đích → nhanh hơn.
  • injectargs là ephemeral — mất khi OSD restart. Nhớ hạ về mặc định sau khi xong đợt redeploy.

10. Checklist nhanh khi gặp "OSD slow lúc backfill"

  1. ceph -s — degraded hay chỉ misplaced? (degraded = recovery; misplaced = backfill/best-effort).
  2. client: trong ceph -s có cao không? Nếu client đang bận, best-effort bị reservation nhường đường là đúng thiết kế, không phải lỗi.
  3. Verify osd_mclock_max_capacity_iops_hdd (mục 8) — capacity sai gây phần lớn slow request.
  4. Kiểm tra shard đang là 5 hay 1 (mục 5). Nếu là 5 và client bị ảnh hưởng khi backfill → cân nhắc đổi (mục 6).
  5. Chỉ chỉnh osd_max_backfills khi đã bật gate override (mục 9), và nhớ nó là per-OSD.

Nguồn

Ceph docs — mClock Config Reference: https://docs.ceph.com/en/reef/rados/configuration/mclock-config-ref/#osd-shard-configuration-for-hdd-based-clusters-with-mclock

© Copyright Infra Notes contributors. Last updated on September 07, 2026.