Tải Plugin Debezium PostgreSQL Connector
Xác định phiên bản tương thích
Để đảm bảo tính ổn định, bạn cần tải phiên bản Debezium connector tương thích với Kafka Connect đang chạy. Trong phần 2, chúng ta đã cài đặt Kafka 3.x, nên hãy tải phiên bản Debezium 2.x (ví dụ: 2.5.0) để tránh xung đột API.
Thư mục làm việc hiện tại là /opt/kafka. Chúng ta sẽ tải file JAR trực tiếp từ Maven Central vào thư mục tạm để chuẩn bị.
Thực thi lệnh sau để tải connector:
cd /tmp
wget https://repo1.maven.org/maven2/io/debezium/debezium-connector-postgresql/2.5.0/debezium-connector-postgresql-2.5.0.jar
Kết quả mong đợi: File debezium-connector-postgresql-2.5.0.jar được tải về thành công với kích thước khoảng 10MB - 15MB.
Tải các thư viện phụ thuộc (Dependencies)
Connector PostgreSQL không chỉ là một file JAR duy nhất. Nó cần các thư viện phụ thuộc như postgresql-protocol để giao tiếp với database và pgoutput để đọc WAL (Write-Ahead Log).
Debezium đóng gói các thư viện này trong một file JAR "shaded" (đã gộp), nhưng để an toàn và tuân thủ kiến trúc chuẩn của Kafka Connect, chúng ta cần đảm bảo các JAR phụ thuộc được đưa vào đúng thư mục libs của Kafka hoặc nằm trong cấu trúc plugin.
Trong phiên bản 2.5.0, file JAR chính đã bao gồm hầu hết dependencies, nhưng chúng ta vẫn cần tải thêm postgresql-42.6.0.jar nếu Kafka Connect chưa có sẵn trong thư mục libs, hoặc để đảm bảo phiên bản driver mới nhất.
Tải driver PostgreSQL:
cd /tmp
wget https://repo1.maven.org/maven2/org/postgresql/postgresql/42.6.0/postgresql-42.6.0.jar
Kết quả mong đợi: File postgresql-42.6.0.jar xuất hiện trong thư mục /tmp.
Cấu hình file config.properties cho Kafka Connect
Hiểu về cơ chế Plugin Path
Kafka Connect cần biết nơi chứa các connector bên thứ 3. Mặc định, nó chỉ quét thư mục plugins trong thư mục cài đặt Kafka Connect. Chúng ta cần chỉ định rõ ràng đường dẫn này trong file cấu hình để hệ thống nhận diện được plugin Debezium vừa tải về.
File cấu hình nằm tại /opt/kafka/config/connect-distributed.properties (hoặc connect-standalone.properties nếu bạn chạy standalone, nhưng series này hướng đến distributed).
Chúng ta sẽ chỉnh sửa file này để thêm tham số plugin.path.
Trước tiên, hãy xem nội dung hiện tại của file:
cat /opt/kafka/config/connect-distributed.properties
Kết quả mong đợi: Bạn thấy danh sách các tham số cấu hình như bootstrap.servers, key.converter, v.v.
Sửa file cấu hình để nhận diện Plugin
Chúng ta cần thêm dòng plugin.path=/opt/kafka/plugins vào file cấu hình. Nếu dòng này đã tồn tại nhưng bị comment, hãy bỏ comment. Nếu chưa có, hãy thêm vào cuối file hoặc ngay sau phần bootstrap.servers.
Sử dụng nano hoặc vim để chỉnh sửa. Dưới đây là nội dung đầy đủ của file connect-distributed.properties đã được cập nhật (chú ý dòng plugin.path):
cat > /opt/kafka/config/connect-distributed.properties
Kết quả mong đợi: File connect-distributed.properties được ghi lại thành công, dòng plugin.path=/opt/kafka/plugins đã được thêm vào.
Cài đặt plugin vào thư mục plugins của Kafka Connect
Tạo cấu trúc thư mục Plugins
Kafka Connect phân biệt connector bằng thư mục con. Mỗi connector nên có một thư mục riêng để tránh xung đột tên file JAR. Cấu trúc chuẩn là: <plugin.path>/<connector-name>/.
Chúng ta sẽ tạo thư mục /opt/kafka/plugins/debezium-postgresql để chứa các file JAR đã tải về.
Thực thi lệnh tạo thư mục:
mkdir -p /opt/kafka/plugins/debezium-postgresql
Kết quả mong đợi: Thư mục debezium-postgresql được tạo thành công trong đường dẫn /opt/kafka/plugins.
Di chuyển các file JAR vào thư mục Plugin
Bây giờ, di chuyển file JAR chính của Debezium PostgreSQL và file driver PostgreSQL từ /tmp vào thư mục plugin vừa tạo.
Lệnh di chuyển:
cp /tmp/debezium-connector-postgresql-2.5.0.jar /opt/kafka/plugins/debezium-postgresql/
cp /tmp/postgresql-42.6.0.jar /opt/kafka/plugins/debezium-postgresql/
Kết quả mong đợi: Cả hai file JAR đều đã có mặt trong thư mục /opt/kafka/plugins/debezium-postgresql.
Đảm bảo quyền truy cập (Permissions)
Trên Ubuntu 24.04, người dùng kafka (nếu bạn đã tạo user riêng để chạy dịch vụ) cần quyền đọc các file này. Nếu bạn chạy bằng root thì bỏ qua bước này, nhưng để chuẩn hóa (best practice), hãy set quyền cho thư mục plugins.
Thay đổi quyền sở hữu và quyền đọc cho thư mục plugin:
chown -R kafka:kafka /opt/kafka/plugins/debezium-postgresql
chmod -R 755 /opt/kafka/plugins/debezium-postgresql
Kết quả mong đợi: Không có lỗi (no error), quyền truy cập đã được cấp cho user kafka.
Kiểm tra và xác nhận plugin đã được nhận diện
Liệt kê các file trong thư mục plugins
Trước khi khởi động Kafka Connect, hãy xác minh vật lý rằng các file đã nằm đúng vị trí mà plugin.path đã chỉ định.
Lệnh kiểm tra:
ls -R /opt/kafka/plugins/
Kết quả mong đợi: Bạn thấy cây thư mục như sau:
debezium-postgresql/
debezium-connector-postgresql-2.5.0.jar
postgresql-42.6.0.jar
Khởi động Kafka Connect (chế độ Standalone để test nhanh)
Để xác nhận plugin được nhận diện ngay lập tức mà không cần chờ cluster Zookeeper/Kafka Distributed, chúng ta sẽ chạy Kafka Connect ở chế độ standalone với file config connect-standalone.properties đã được cấu hình tương tự (có plugin.path).
Tuy nhiên, để kiểm tra nhanh nhất mà không cần khởi động full service, chúng ta có thể dùng script kafka-connect-plugins.sh (có sẵn trong Kafka 3.x trở lên) để liệt kê các connector đã cài đặt.
Thực thi lệnh liệt kê plugin:
cd /opt/kafka
./bin/kafka-connect-plugins.sh --class-name org.apache.kafka.connect.cli.ConnectStandalone
Hoặc cách chính xác hơn để tìm connector cụ thể:
./bin/kafka-connect-plugins.sh --class-name org.apache.kafka.connect.cli.ConnectDistributed
Kết quả mong đợi: Trong danh sách output, bạn sẽ thấy một mục có tên io.debezium.connector.postgresql.PostgresConnector hoặc hiển thị rõ ràng là debezium-postgresql trong phần "Available connectors".
Nếu bạn muốn chạy thử để xem log khởi động (tạm thời dừng nếu thấy lỗi), hãy chạy:
./bin/kafka-connect-distributed.sh /opt/kafka/config/connect-distributed.properties &
Kiểm tra log khởi động (sau 10-15 giây):
tail -n 50 /opt/kafka/logs/connect.log | grep -i "plugin\|connector"
Kết quả mong đợi: Log hiện thông báo Registered connector 'debezium-postgresql' hoặc Loaded plugin 'debezium-postgresql'. Nếu thấy dòng này, nghĩa là plugin đã được nhận diện thành công.
Xác nhận cuối cùng qua API (nếu đã chạy Distributed)
Nếu bạn đã khởi động thành công Kafka Connect Distributed (chờ cluster sẵn sàng), hãy dùng curl để gọi API kiểm tra danh sách connector plugins.
Lệnh gọi API:
curl -s http://localhost:8083/connectors/plugins | jq '.[] | select(.class == "io.debezium.connector.postgresql.PostgresConnector")'
Kết quả mong đợi: JSON trả về chứa thông tin về plugin Debezium PostgreSQL, bao gồm tên class, version, và các connector class có sẵn.
Điều hướng series:
Mục lục: Series: Triển khai Database Change Data Capture với Debezium và Kafka trên Ubuntu 24.04
« Phần 2: Cài đặt và cấu hình Zookeeper cùng Kafka
Phần 4: Cấu hình PostgreSQL để kích hoạt Change Data Capture »