Follow Up - Preventing Upgrade Failures from etcd v3.5 to v3.6

etcd · 2025 · 4. Điều chỉnh · Độ khó: Trung bình — bài gốc

Hai thông báo ngắn của dự án etcd. Bài này nối tiếp bài "How to Prevent a Common Failure when Upgrading etcd v3.5 to v3.6" (cùng 2025); wiki tóm tắt cả hai.

Bối cảnh

• etcd lưu thông tin thành viên cụm (membership) ở hai kho: v2store (cũ) và v3store. Ở v3.5, v2store là nguồn sự thật; ở v3.6, v3store là nguồn sự thật.
• Mặc định etcd chỉ cho phép tối đa một learner (thành viên chưa bỏ phiếu); bootstrap thất bại nếu có từ hai learner trở lên.

Sự cố, lần 1

• Từ v3.5.1 (một thay đổi năm 2021) tới v3.5.19, khi promote learner thành voter, thay đổi chỉ được ghi bền vào v2store, không vào v3store. Ở v3.5 không ai thấy vì v2store là nguồn sự thật.
• Khi nâng lên v3.6, v3store thành nguồn sự thật: một số voter quay lại thành learner. Từ hai cái trở lên thì nâng cấp hỏng (membership: too many learner member in cluster); một cái thì vẫn lên nhưng mất một phiếu, ảnh hưởng quorum (v3.6.0-rc.3 thêm tự promote learner lúc bootstrap).
• Sửa ở v3.5.20; quy định phải lên v3.5.20+ trước khi lên v3.6. Test e2e nâng cấp của etcd không bắt được; lỗi lộ ra ở workflow test của Kubernetes. Đã thêm test e2e tương tự.

Sự cố, lần 2 (bài follow-up)

• Bản sửa chưa phủ hết: khi nâng cấp kiểu thay dần từng máy (ví dụ Cluster API khi nâng control plane Kubernetes), một learner mới có thể nhận snapshot từ một thành viên cũ (≤ v3.5.19) mang membership sai. Trên v3.5 vẫn không sao; lên v3.6 thì lại hỏng.
• Sửa ở v3.5.24; khuyến nghị lên v3.5.24+ trước v3.6. Cụm cài mới trên v3.5.20–v3.5.23 (không nâng từ bản cũ) thì đi thẳng được.
• Cách lách nếu chưa lên được v3.5.24: khởi động lại mọi thành viên trước khi lên v3.6 (đăng ký lại và sửa membership), hoặc nâng thêm một bản vá trong dải v3.5.20–v3.5.23.

Vì sao

• Trong giai đoạn hai kho cùng tồn tại, kho phụ có thể sai âm thầm nhiều năm; lỗi chỉ hiện khi nguồn sự thật được đổi sang nó (Migration không downtime).
• Dữ liệu sai lan qua snapshot: sửa code không sửa được trạng thái đã ghi, và máy mới có thể nhận lại trạng thái sai từ máy cũ (Failover, replica và dự phòng dữ liệu).

Bài học cho SWE

• Trước khi đổi nguồn sự thật giữa hai kho, đối chiếu dữ liệu của hai kho trên cụm thật, không chỉ sửa đường ghi.
• Bản vá cho dữ liệu cần cả bước sửa trạng thái đã có (đăng ký lại, khởi động lại), không chỉ sửa code.
• Lộ trình nâng cấp bắt buộc qua một bản trung gian là cách dự án phân tán đảm bảo mọi cụm đã được "làm sạch" trước bước lớn.
• Test nâng cấp phải mô phỏng đúng cách người dùng nâng (thay dần từng máy, snapshot từ máy cũ).

Liên quan

• etcd 2017 · Kubernetes 2026 · Google 2006
• Migration không downtime · Failover, replica và dự phòng dữ liệu