Cheat Sheet — Kafka CLI 3.8 (KRaft)

Các công cụ dòng lệnh Kafka 3.8 dùng hằng ngày: quản lý topic, produce/consume kiểm chứng, consumer group và reset offset an toàn, cấu hình topic, ACL và kiểm tra KRaft quorum.

Module 06

Quản lý topic

Quản lý topic
MụcÝ nghĩa & cách dùng
kafka-topics.sh --bootstrap-server <broker>:9092 --listLiệt kê mọi topic trong cluster. Mọi lệnh Kafka hiện hành đều nối qua --bootstrap-server thay vì địa chỉ ZooKeeper.
kafka-topics.sh --bootstrap-server <broker>:9092 --describe --topic loyalty.outboxChi tiết topic: số partition, replication factor, leader và ISR của từng partition — xem đầu tiên khi nghi ngờ partition mất đồng bộ (ISR nhỏ hơn RF).
kafka-topics.sh --bootstrap-server <broker>:9092 --create --topic loyalty.outbox --partitions 6 --replication-factor 3Tạo topic với số partition và hệ số nhân bản chỉ định. Số partition quyết định mức song song tối đa của consumer group và gần như không giảm được về sau.
kafka-topics.sh --bootstrap-server <broker>:9092 --alter --topic loyalty.outbox --partitions 12Tăng số partition cho topic. Chỉ tăng được, không giảm; tăng partition làm thay đổi ánh xạ key → partition nên thứ tự theo key cũ không còn bảo toàn tuyệt đối.
kafka-topics.sh --bootstrap-server <broker>:9092 --delete --topic loyalty.test-cuXóa hẳn một topic và dữ liệu của nó. Thao tác không khôi phục được — chỉ dùng cho topic tạm/topic tạo nhầm, tuyệt đối kiểm tra kỹ tên topic và môi trường trước khi chạy.

Produce & consume kiểm chứng

Produce & consume kiểm chứng
MụcÝ nghĩa & cách dùng
kafka-console-producer.sh --bootstrap-server <broker>:9092 --topic loyalty.outboxGửi message thủ công từ bàn phím vào topic — dùng để kiểm chứng pipeline (ví dụ sự kiện outbox) mà không cần chạy ứng dụng.
kafka-console-producer.sh --bootstrap-server <broker>:9092 --topic loyalty.outbox --property parse.key=true --property key.separator=:Gửi message kèm key theo định dạng key:value. Key quyết định partition và thứ tự trong partition — không có key thì không kiểm chứng được hành vi theo khóa nghiệp vụ.
kafka-console-consumer.sh --bootstrap-server <broker>:9092 --topic loyalty.outbox --from-beginningĐọc message từ đầu topic bằng một group tạm — xem dữ liệu thực tế đang có, kể cả message cũ mà consumer ứng dụng đã xử lý.
kafka-console-consumer.sh --bootstrap-server <broker>:9092 --topic loyalty.outbox --group debug-groupĐọc bằng một consumer group đặt tên: offset sẽ được lưu cho group này, dùng khi muốn mô phỏng đúng hành vi consumer của ứng dụng.
kafka-console-consumer.sh --bootstrap-server <broker>:9092 --topic loyalty.outbox --property print.key=true --property print.timestamp=true --from-beginningĐọc kèm key và timestamp của từng message — khi gỡ lỗi cần đối chiếu thứ tự sự kiện của cùng một khóa nghiệp vụ (ví dụ cùng một member) trong partition.
kafka-get-offsets.sh --bootstrap-server <broker>:9092 --topic loyalty.outboxXem offset đầu (earliest) và cuối (latest) của từng partition mà không cần consume — so nhanh latest trừ committed offset của group để ước lượng LAG tổng.

Consumer group & reset offset

Consumer group & reset offset
MụcÝ nghĩa & cách dùng
kafka-consumer-groups.sh --bootstrap-server <broker>:9092 --describe --group loyalty-crm-consumerXem offset đã commit, log-end-offset và LAG của từng partition kèm instance đang sở hữu — lệnh chẩn đoán đầu tiên khi consumer bị trễ hoặc nghi ngờ poison pill.
kafka-consumer-groups.sh --bootstrap-server <broker>:9092 --group loyalty-crm-consumer --reset-offsets --to-earliest --topic loyalty.outbox --dry-runMô phỏng reset offset về đầu topic: chỉ in kết quả dự kiến, chưa thay đổi gì. Luôn chạy --dry-run trước để rà soát phạm vi.
kafka-consumer-groups.sh --bootstrap-server <broker>:9092 --group loyalty-crm-consumer --reset-offsets --to-earliest --topic loyalty.outbox --executeThực thi reset offset đã rà soát. Group phải đang inactive (không còn consumer chạy) thì mới reset được; sau reset, consumer sẽ đọc lại message — ứng dụng phải idempotent để không xử lý trùng gây lỗi nghiệp vụ.
kafka-consumer-groups.sh --bootstrap-server <broker>:9092 --group g --reset-offsets --shift-by -100 --topic loyalty.outbox --executeDịch offset tương đối: --shift-by âm lùi lại (đọc lại 100 message gần nhất), dương bỏ qua. Hữu ích khi chỉ cần xử lý lại một đoạn ngắn quanh sự cố.
kafka-consumer-groups.sh --bootstrap-server <broker>:9092 --group g --reset-offsets --to-datetime 2026-10-22T00:00:00.000 --topic loyalty.outbox --executeReset offset về vị trí tương ứng một mốc thời gian — cách gọn nhất để phát lại toàn bộ sự kiện từ đầu ngày sự cố.

Cấu hình topic, ACL & hạ tầng KRaft

Cấu hình topic, ACL & hạ tầng KRaft
MụcÝ nghĩa & cách dùng
kafka-configs.sh --bootstrap-server <broker>:9092 --entity-type topics --entity-name loyalty.outbox --describeXem cấu hình động của một topic: retention.ms, cleanup.policy, min.insync.replicas... đối chiếu với mặc định của broker.
kafka-configs.sh --bootstrap-server <broker>:9092 --entity-type topics --entity-name loyalty.outbox --alter --add-config retention.ms=604800000,cleanup.policy=deleteĐổi cấu hình topic ngay lúc hệ thống đang chạy, không cần khởi động lại broker: ví dụ giữ message 7 ngày với chính sách xóa theo thời gian. Topic sự kiện cần trạng thái hiện tại thì dùng cleanup.policy=compact (thường kết hợp delete).
kafka-acls.sh --bootstrap-server <broker>:9092 --add --allow-principal User:loyalty-app --operation Write --topic loyalty.outboxCấp quyền ACL cho một principal trên topic khi cluster bật authorizer — tách quyền tối thiểu theo từng ứng dụng thay vì dùng chung tài khoản toàn quyền.
kafka-metadata-quorum.sh --bootstrap-server <broker>:9092 describe --statusXem trạng thái KRaft quorum của controller: leader, voter và mức độ nhân bản metadata — kiểm tra sức khỏe tầng điều khiển trong cài đặt KRaft.
kafka-log-dirs.sh --bootstrap-server <broker>:9092 --describe --topic-list loyalty.outboxXem dung lượng log theo partition/broker để phát hiện partition phình bất thường hoặc broker lệch đĩa. Lưu ý về ZooKeeper: Kafka 3.8 KRaft là hướng mặc định cho cài mới (chế độ ZooKeeper đã deprecated), nên vận hành mới nên đi theo KRaft và các lệnh --bootstrap-server như trên.