monedula-gitops — Monedula

配套文章： Monedula GitOps：面向 CLI 与 Kubernetes 的声明式 Kafka 管理介绍了 v0.1.0 版本、资源模型和基本工作流。

为什么

Kafka 的配置很少集中在一个地方。主题来自一个脚本，ACL 来自另一个脚本， schema 来自应用的流水线，配额来自管理员，Confluent RBAC 的角色绑定又来自另一套工具。时间一长，运行中的集群成了这个系统唯一可靠的描述——但那既不是有意设计出来的描述，也不是能被评审的描述。

monedula-gitops 让这份描述变得明确：在 Git 中描述期望的 Kafka 状态，像评审代码一样评审它，把它和运行中的集群做比较，再让集群向它收敛。

Kafka 不只是主题，所以这套模型覆盖了那些通常要放在一起的资源——访问规则、消费者组、配额、schema、凭据，以及在 Confluent Platform 上的 RBAC 角色绑定。

一套模型，两种运行时

CLI 和 Kubernetes operator 使用同一套资源模型和同一个协调引擎。

CLI —— 在开发机或 CI/CD 流水线中校验、比较、应用和验证清单。发现漂移时 verify 会返回非零退出码，因此可以直接用作 CI 门禁。
Operator —— 把同样这些 Kubernetes 风格的资源安装为 CRD，并在集群内部持续协调。

凭据在两种运行时中的提供方式不同——CLI 用环境变量或文件引用，operator 用 Kubernetes Secret——但期望状态、漂移规则和执行语义保持一致。团队可以先从流水线驱动的变更开始，之后再引入 operator，而不必设计第二套配置模型。

能管理什么

KafkaCluster（连接、认证、默认值、Schema Registry、可选的 Confluent MDS）、 KafkaTopic（生命周期、分区、配置、主题本地访问权限、schema）、 KafkaAccessPolicy（高级的和共享的 ACL 规则）、KafkaQuota（按用户、 client-id 和 IP 的配额）、KafkaUser（SCRAM 凭据），以及 KafkaRoleBinding （Confluent MDS/RBAC）。

最常见的场景依然很小：一个主题和被允许使用它的应用写在同一份清单里，对应的主题 ACL 和消费者组 ACL 由它生成：

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaTopic
metadata:
  name: orders
spec:
  clusterRef:
    name: prod
  topicName: orders
  partitions: 6
  access:
    producers:
      - principal: User:svc-checkout
    consumers:
      - principal: User:svc-fraud
        group: fraud-orders

安装

brew install monedula-dev/tap/monedula-gitops

也可以通过 go install、GitHub releases 中的预编译二进制，或 ghcr.io/monedula-dev/monedula-gitops 容器镜像获取。operator 用 Helm 从 oci://ghcr.io/monedula-dev/charts/monedula-gitops 安装。

从已有集群开始

真实环境很少是空的，所以 import cluster 会读取当前的 Kafka 状态并据此生成清单——主题、访问规则、配额、schema、SCRAM 用户，以及受支持情况下的 Confluent RBAC 角色绑定。关键在于往返一致：把导入出来的目录对同一个集群做验证，应当报告没有漂移。

有风险的操作都有防护，删除和裁剪必须显式开启。仓库里还有两个可运行的快速上手示例（基于 Docker Compose 的 CLI 演练场，以及本地 Kubernetes 上的 operator 演练场）和一份包含 25 组自包含配置的场景目录。