datastax/burnell

Burnell

镜像概述和主要用途

Burnell是Pulsar集群的代理工具，旨在增强Pulsar集群的安全性、可管理性和可观测性。它通过提供JWT认证授权、Admin API代理、租户级权限控制、日志查询、使用计量及监控指标暴露等功能，简化Pulsar集群的运维和多租户管理。

核心功能和特性

• 生成与Pulsar Java认证授权兼容的JWT令牌
• 基于Pulsar JWT的认证与授权
• 代理完整的https://pulsar.apache.org/admin-rest-api/
• 对Pulsar Admin REST API实施租户级授权
• 在Broker上暴露租户Prometheus指标
• 提供函数日志查询接口
• 支持带分页的统计信息查询
• 提供Pulsar Beam Webhook和主题管理REST API，并强制执行租户级授权
• 租户及租户命名空间使用计量（总字节数、消息入站/出站量）
• 初始化模式：配置Pulsar Kubernetes集群的TLS密钥和JWT
• 修复模式：修复Pulsar Kubernetes集群的TLS密钥和JWT
• Pulsar WebSocket代理：将HTTP参数中的令牌设置到HTTP头中

运行模式

Burnell支持三种运行模式，默认模式为proxy：

bash
# 代理模式（默认）
burnell -mode proxy

# 初始化模式
burnell -mode init

# 修复模式
burnell -mode healer

REST API详细说明

生成JWT令牌

生成JWT令牌需在GET请求的Authorization头中指定超级用户角色的JWT（格式为Bearer <token>），请求路径如下：

/subject/{user-subject}

用户主题（user-subject）仅允许字母、数字和连字符。

可通过查询参数指定令牌签名方法和过期时间，默认签名方法为RS256，默认无过期时间：

/subject/{user-subject}?exp=<duration>&alg=<signMethod>

• 支持的时间单位：d（天）、y（年）及Go time包定义的https://golang.org/pkg/time/#ParseDuration
• 支持的签名方法：详见相关规范

生成的JWT可在相同加密密钥方案下被Pulsar验证。

租户函数日志检索

提供从函数工作节点抓取滚动日志的功能。

函数日志检索端点及查询参数

默认返回最新日志的最后几行，端点格式：

/function-logs/{tenant}/{namespace}/{function-name}
/function-logs/{tenant}/{namespace}/{function-name}/{instance}

未指定实例时，默认实例为0。

示例：

/function-logs/ming-luo/namespace2/for-monitor-function

如需检索更早或更新的日志，使用查询参数backwardpos（向后位置）或forwardpos（向前位置）指定日志文件中的字节索引。这些值可从上次查询响应的BackwardPosition和ForwardPosition字段获取。系统会返回完整日志行，需使用响应中的准确位置，否则可能导致日志截断：

/function-logs/{tenant}/{namespace}/{function-name}?backwardpos=45000

客户端需自行跟踪日志文件的前后位置，参数值必须为正数。backwardpos或forwardpos为0时，将backwardpos重置为日志文件的EOF，显示最后几行。

响应 payload 大小通常为1-2KB，示例：

json
{
    "BackwardPosition": 47987,
    "ForwardPosition": 49427,
    "Logs": "[2020-03-30 12:31:57 +0000] [ERROR] log.py: Traceback (most recent call last):\n[2020-03-30 12:31:57 +0000] [ERROR] log.py:   File \"/pulsar/instances/python-instance/python_instance_main.py\", line 211, in <module>\n[2020-03-30 12:31:57 +0000] [ERROR] log.py: main()\n[2020-03-30 12:31:57 +0000] [ERROR] log.py:   File \"/pulsar/instances/python-instance/python_instance_main.py\", line 192, in main\n[2020-03-30 12:31:57 +0000] [ERROR] log.py: pyinstance.run()\n[2020-03-30 12:31:57 +0000] [ERROR] log.py:   File \"/pulsar/instances/python-instance/python_instance.py\", line 189, in run\n[2020-03-30 12:31:57 +0000] [ERROR] log.py: **consumer_args\n"
}

函数实例与工作节点ID映射

通过function-status端点查询函数实例及其工作节点ID的映射关系和函数状态：

/function-status/{tenant}/{namespace}/{function-name}

租户主题统计收集器

主题统计端点

方法：GET

/stats/topics/{tenant}?limit=10&offset=0

可在请求体中指定需查询的主题列表。该端点默认从5秒轮询一次的本地缓存获取数据，指定主题列表时将直接查询Broker Admin REST端点：

json
{"tenant":"ming-luo","sessionId":"reserverd for snapshot iteration","offset":1,"total":1,"data":{"persistent://ming-luo/namespace2/test-topic3":{"averageMsgSize":0,"backlogSize":0,"msgRateIn":0,"msgRateOut":0,"msgThroughputIn":0,"msgThroughputOut":0,"pendingAddEntriesCount":0,"producerCount":0,"publishers":[],"replication":{},"storageSize":0,"subscriptions":{"mysub":{"consumers":[],"msgBacklog":0,"msgRateExpired":0,"msgRateOut":0,"msgRateRedeliver":0,"msgThroughputOut":0,"numberOfEntriesSinceFirstNotAckedMessage":1,"totalNonContiguousDeletedMessagesRange":0,"type":"Exclusive"}}}}}

按租户命名空间分组主题

/admin/v2/topics/{tenant}

租户和命名空间级使用计量

租户使用计量端点

返回所有租户的使用计量数据，包括消息数、总字节入站/出站量及积压大小。需超级用户令牌：

/tenantsusage

命名空间使用计量端点

返回指定租户下各命名空间的使用计量数据，包括消息数、总字节入站/出站量及积压大小。需超级用户令牌或租户令牌：

/namespacesusage/{tenant}

租户CRUD

提供租户策略管理功能，租户策略包括消息保留策略、功能代码及命名空间、生产者、消费者的限制。

资源端点

/k/tenant/{tenant}

{tenant}为租户名称，所有REST调用均需指定。

支持的HTTP方法

GET, DELETE, POST

请求头

需包含超级角色令牌：

-H "Authorization: Bearer $SUPERROLE_TOKEN"

创建带套餐的租户

bash
curl -v -X POST \
-H "Authorization: Bearer $SUPERROLE_TOKEN" \
-d '{"PlanType": "free"}' \
"http://localhost:8964/k/tenant/ming-luo"

响应示例：

json
{"name":"ming-luo","tenantStatus":1,"org":"","users":"","planType":"free","updatedAt":"2020-04-17T13:39:09.315634076-04:00","policy":{"name":"free","numOfTopics":5,"numOfNamespaces":1,"messageHourRetention":48,"messageRetention":172800000000000,"numofProducers":3,"numOfConsumers":5,"functions":1,"featureCodes":""},"audit":"initial creation,"}

更新租户套餐

可升级/降级套餐或指定单个套餐属性及功能代码。policy.messageHourRetention（整数）为数据保留小时数，policy.messageRetention为内部保留的纳秒级保留时间。

bash
curl -v -X POST \
-H "Authorization: Bearer $SUPERROLE_TOKEN" \
-d '{"PlanType": "free", "policy":{"name":"free","numOfTopics":5,"numOfNamespaces":1,"messageRetention":172800000000000,"numofProducers":3,"numOfConsumers":5,"functions":3,"featureCodes":"broker-metrics"}}' \
"http://localhost:8964/k/tenant/ming-luo"

获取租户信息

bash
curl -H "Authorization: Bearer $SUPERROLE_TOKEN" "http://localhost:8964/k/tenant/ming-luo"

删除租户

bash
curl -X DELETE -H "Authorization: Bearer $SUPERROLE_TOKEN" "http://localhost:8964/k/tenant/ming-luo"

租户级Prometheus指标

暴露/pulsarmetrics端点，返回与租户相关的Pulsar Prometheus指标，租户通过Authorization令牌识别。使用超级用户令牌时，返回所有联邦Prometheus指标。

抓取配置要求

建议抓取配置设置honor_timestamps: true以保留原始时间戳，honor_labels: true可选（可通过exported_标签识别指标）。详见https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config%E3%80%82

Pulsar Admin REST API代理

Pulsar Admin REST API（函数、sink、source对应admin\v2和admin\v3）通过相同路由代理，/admin/v2/broker-stats除外。

/admin/v2/broker-stats响应聚合所有Broker统计信息，按Broker名称排序，支持分页：

bash
curl -X GET \
-H "Authorization: Bearer $SUPERROLE_TOKEN" \
"https://<pulsar proxy server fqdn>:8964/admin/v2/broker-stats/metrics?limit=2&offset=0"

• limit=0：单次返回所有Broker
• 未指定limit和offset：返回按字母顺序排序的第一个Broker

响应包含新的offset和总数：

json
{"total":1,"offset":1,"data":[{"broker":"10.244.1.221:8080","data":[{"...

Docker部署

构建镜像

bash
docker build -t burnell .

运行logcollector

bash
# 构建logcollector镜像
docker build -t burnell-logcollector -f ./dockerfiles/logserver/Dockerfile .

# 运行logcollector容器
docker run --rm -it -p 4042:4042 -e "LogServerPort=:4042" --name burnell-logcollector docker.xuanyuan.run/burnell-logcollector:latest

使用场景和适用范围

• Pulsar集群的认证与授权管理
• 多租户Pulsar集群的权限隔离与资源控制
• Pulsar函数日志集中查询与故障排查
• 租户级资源使用计量与监控
• Pulsar Kubernetes集群的初始化与证书修复