用途:指导在 Redpanda 代码库中新增或修改 Admin v2 ConnectRPC 端点,涉及端点从 proto 定义到测试接入的每一层。
主要能力与流程:
- 编写 proto:在 proto/redpanda/core/admin/v2/ 下新增 .proto,package 固定为 redpanda.core.admin.v2,必须设置 option (pbgen.cpp_namespace) = "proto::admin";每个 RPC 必须带 option (pbgen.rpc) = { authz: ... },admin v2 默认 SUPERUSER,使用 USER 或 PUBLIC 需核心团队批准。可选 http_route 添加 HTTP 别名。
- Bazel 构建:每个 .proto 需在 BUILD 中添加成对的 proto_library 与 redpanda_proto_library 目标,deps 分别对应 import 与生成的 C++ 依赖。
- C++ 实现:在 src/v/redpanda/admin/services/ 下新增服务类,实现类命名 admin::<service>_service_impl,处理函数签名为 ss::future<...response> name(serde::pb::rpc::context, Request)。支持校验异常、leader 重定向、节点代理、license 校验等模式。
- 注册服务:在 src/v/redpanda/BUILD 与 application_admin.cc 中加入依赖与 add_service 调用。
- 构建格式化:执行 bazel build 与 clang_format。
- 重新生成 ducktape Python 绑定:需先安装 uv 并运行 bazel fetch //proto/...,随后执行 tools/regenerate_ducktape_protos.sh,生成文件须提交,CI 会检查新鲜度。
- 为新服务添加 ducktape 客户端访问器:修改 tests/rptest/clients/admin/v2.py。
限制与注意:Go 绑定不在本仓库生成,rpk 消费新 RPC 属后续独立任务;验证错误必须抛出 rpc.h 中的类型化异常;处理函数签名固定不可偏离;CI 强制要求生成文件与源码一致。具体参考示例与完整代码细节见官方技能页面。