Điều kiện tiên quyết
- Confluent Cloud: một environment có ít nhất một cluster Kafka, và quyền tạo API key, tốt nhất là cho một service account.
- Kafka tự vận hành: một broker có địa chỉ bootstrap mà CloudThinker truy cập được qua mạng, mặc định cổng
9092. File không có thiết lập nào cho SASL/SCRAM, mTLS, client certificate hay CA tùy chỉnh, nên broker phải chấp nhận kết nối của CloudThinker mà không cần những thứ đó. Đừng mở broker kiểu này ra internet: chỉ cho phép các egress IP của CloudThinker. Tài liệu này không công bố danh sách egress IP của CloudThinker: hãy hỏi đầu mối CloudThinker của bạn, hoặc liên hệ chúng tôi. Xem Truy cập dịch vụ nội bộ để biết các lựa chọn khác. - Một trình soạn thảo văn bản để viết file JSON.
- Role Admin trong workspace CloudThinker, role có quyền thêm và sửa kết nối. Xem Roles.
Chọn scope
Trên Confluent Cloud, mỗi cặp API key mở một scope. Hãy bắt đầu với scope Kafka cluster và thêm các scope khác sau bằng cách tải lên file đã cập nhật. Với Kafka tự vận hành, chỉBOOTSTRAP_SERVERS và SCHEMA_REGISTRY_ENDPOINT (tùy chọn) có tác dụng, mọi scope khác chỉ dành cho Confluent Cloud.
Thiết lập
- Confluent Cloud
- Kafka tự vận hành
1
Thu thập các trường của cluster
Trong Confluent Cloud, mở Environments và chọn environment của bạn. ID của environment (
env-...) là KAFKA_ENV_ID. Mở cluster và sao chép bootstrap server, REST endpoint và cluster ID (lkc-...).2
Tạo một cặp API key cho mỗi scope
Vào Settings → API keys và nhấn Add API key. Với production, chọn Service account. Tạo key cho Kafka cluster trước, sau đó mỗi scope tùy chọn bạn đã chọn thì tạo một key. Lưu từng key và secret ngay khi tạo. Chọn tài nguyên tương ứng với từng scope:
3
Thu thập các trường của scope tùy chọn
- Schema Registry: trong environment, mở Stream Governance → Schema Registry và sao chép endpoint.
- Flink: mở Flink → Compute pools, chọn pool và sao chép ID (
lfcp-...). REST endpoint có dạnghttps://flink.<region>.<provider>.confluent.cloud, chẳng hạnhttps://flink.us-east-1.aws.confluent.cloud.FLINK_ENV_IDlà IDenv-...của environment chứa pool, thường trùng giá trị vớiKAFKA_ENV_ID. Organization ID nằm trong Settings → Organizations. - Giá trị mặc định tùy chọn cho Flink:
FLINK_ENV_NAMElà tên hiển thị của environment, dùng làm catalog mặc định.FLINK_DATABASE_NAMElà tên hiển thị của cluster Kafka, dùng làm database mặc định. Đặt hai giá trị này để agent gọi tên table mà không cần đường dẫn đầy đủcatalog.database.table.
4
Viết file JSON
Lưu một file, chẳng hạn
kafka.json. Chỉ giữ các scope bạn đã tạo key, và xóa hẳn các dòng còn lại:5
Tải file lên CloudThinker
Mở More → Workspace settings → Connections và chọn Apache Kafka. Kéo file vào vùng tải lên, hoặc nhấn choose a JSON file. Nhấn Connect.Trạng thái thành công: kết nối hiện trạng thái Connected. Chạy prompt xác minh bên dưới để chắc chắn agent thấy được các topic.
Chi tiết kết nối
Biểu mẫu chỉ có một trường tải lên. File phải là một JSON object với các giá trị kiểu chuỗi, chỉ dùng các key liệt kê trong Chọn scope. File có key nào khác, hoặc có giá trị không phải chuỗi, sẽ bị từ chối.Quyền yêu cầu
Confluent Cloud: tạo key cho một service account, và chỉ cấp cho account đó những gì agent cần.-
Kafka cluster: giới hạn ACL vào các topic agent cần đọc. Việc lấy mẫu message đọc qua một consumer group, nên account cũng cần quyền
READtrên consumer group: - Cloud resource management: tối thiểu MetricsViewer để xem số liệu.
- Schema Registry: DeveloperRead trên các subject agent cần liệt kê.
- Flink: FlinkDeveloper trong environment chứa compute pool.
Khả năng của agent
Các lệnh gọi đánh dấu Có sẽ đi qua Approvals của workspace trước.
Mọi thay đổi do agent thực hiện đều đi qua Approvals của workspace trước. Ở chế độ mặc định Auto · Rules + AI · Ask me, AI judgment có thể cho một thay đổi an toàn chạy mà không cần hỏi. Allow Rule cũng vậy, sau khi CloudThinker bật Rule enforcement cho workspace của bạn. Chọn Manual nếu bạn muốn tự phê duyệt mọi thay đổi.
Số partition không đổi được qua cấu hình topic. Dùng giao diện Confluent Cloud, hoặc xóa rồi tạo lại topic.
Xác minh kết nối
Ví dụ prompt
Thay đổi file sau này
Để thêm scope hoặc xoay vòng key, viết một file đầy đủ chứa mọi scope bạn muốn giữ. Mở kết nối, nhấn biểu tượng bút chì trên dòng của kết nối, rồi trong Edit Instance nhấn Replace…. Tải file lên và nhấn Save and test. Nếu bước kiểm tra lỗi, CloudThinker giữ lại thông tin xác thực cũ. Xem Xoay vòng thông tin xác thực.Khắc phục sự cố
Connection refused hoặc timeout
Connection refused hoặc timeout
CloudThinker không truy cập được broker. Kiểm tra broker đang chạy, cổng
9092 đã mở trên firewall, và BOOTSTRAP_SERVERS đúng. Broker chỉ bind vào 127.0.0.1 thì không truy cập được từ bên ngoài host của nó.Lỗi xác thực dữ liệu sau khi tải lên file thiếu
Lỗi xác thực dữ liệu sau khi tải lên file thiếu
Có key scope xuất hiện nhưng giá trị rỗng. Xóa hẳn cả key lẫn giá trị của mọi scope bạn không dùng.
"SCHEMA_REGISTRY_ENDPOINT": "" sẽ lỗi, còn bỏ hẳn key thì được.Câu hỏi về số liệu hoặc billing bị lỗi
Câu hỏi về số liệu hoặc billing bị lỗi
File không có cặp
CONFLUENT_CLOUD_API_KEY, hoặc account của key thiếu MetricsViewer. Thêm scope cloud và tải file lên lại. Trên cluster tự vận hành, các API này không dùng được.Schema Registry bị lỗi
Schema Registry bị lỗi
Kiểm tra CloudThinker truy cập được
SCHEMA_REGISTRY_ENDPOINT. Với bản tự vận hành, mở cổng 8081. Với Confluent Cloud, xác nhận key Schema Registry thuộc cùng environment.Bảo mật
- Quyền tối thiểu — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
- Chỉ đọc theo mặc định — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
- Xoay vòng thông tin xác thực — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
- Thu hồi khi bàn giao — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.
- Kafka tự vận hành không dùng thông tin xác thực: lời khuyên chỉ đọc ở trên chỉ áp dụng cho key Confluent Cloud. Broker tự vận hành chấp nhận mọi thứ cấu hình của chính nó cho phép, nên hãy giới hạn truy cập mạng như bên dưới, và nhớ rằng thao tác produce và tạo vẫn đi qua Approvals.
- Mỗi scope một cặp key: cấp cho mỗi scope một key riêng trên service account, để bạn thu hồi quyền Flink hoặc Tableflow mà không ảnh hưởng tới key Kafka cluster.
- Giới hạn truy cập mạng: dùng firewall rule để chỉ cho lưu lượng của CloudThinker tới bootstrap và REST endpoint, nhất là với broker tự vận hành không có thông tin xác thực.
- Xóa file cục bộ: file JSON chứa mọi secret ở dạng văn bản thường. Xóa file sau khi tải lên, hoặc chỉ lưu trong secrets manager.
- Coi message là dữ liệu nhạy cảm: message được lấy mẫu có thể chứa dữ liệu cá nhân hoặc token mà producer đã ghi. Chỉ cấp quyền
READtrên topic ở những nơi agent cần xem.
Liên quan
Approvals
Quyết định thay đổi Kafka nào được chạy, phải chờ một người, hoặc bị từ chối.
Kết nối RabbitMQ
Kết nối một message broker khác.