Kafka 的配置很少集中在一个地方。

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

这正是我们做 Monedula GitOps 的原因：一个把 Kafka 资源当作声明式、可版本化 YAML 来管理的开源工具。

目标很简单：

在 Git 中描述期望的 Kafka 状态，像评审代码一样评审它，把它和运行中的集群做比较，再让集群向它收敛。

本文介绍首个公开版本 v0.1.0。它聚焦于模型和基本工作流，而不是重复完整文档。

为什么还要再做一个 Kafka 的 GitOps 工具？

GitOps 给基础设施带来清晰的事实来源、评审历史、可重复的变更和漂移检测。但 Kafka 不只是主题。一个真正好用的管理工具还必须理解访问规则、消费者组、配额、schema、凭据，以及在 Confluent Platform 里的 RBAC 角色绑定。

还有一个落地问题：大多数 Kafka 集群早就存在了。在采用 GitOps 之前手工把它们的完整状态重建成清单，是一道很高的迁移门槛。

Monedula GitOps 就是围绕这两个问题设计的：

  • 覆盖那些通常要放在一起的 Kafka 专有资源；
  • 让最常见的场景保持简单，尤其是一个主题以及被允许使用它的应用；
  • 通过导入流程支持已有集群；
  • 用不用 Kubernetes 都能工作。

一套声明式模型，两种运行方式

最核心的设计决定是：CLI 和 Kubernetes operator 使用同一套资源模型和同一个协调（reconciliation）引擎。

在 CLI 模式下，可以在开发机或 CI/CD 流水线中校验、比较、应用和验证清单。在 operator 模式下，同样这些 Kubernetes 风格的资源被安装为 CRD，并在 Kubernetes 集群内部持续协调。

因此，CLI 使用的 KafkaTopic 也可以作为 Kubernetes 自定义资源来应用。凭据的提供方式在两种运行时中自然不同——例如 CLI 用环境变量或文件引用，operator 用 Kubernetes Secret——但期望状态、漂移规则和执行语义保持一致。

这样，团队可以先从流水线驱动的变更开始，之后再引入 operator，而不必设计第二套配置模型。

一个清单里写清主题和它的访问权限

用得最多的资源，也应该是最容易描述的资源。

一个 KafkaTopic 可以包含分区数、主题配置、Schema Registry 中的 schema，以及常见的生产者和消费者访问规则：

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

根据这份清单，Monedula GitOps 会管理该主题，并生成对应的主题 ACL 和消费者组 ACL。

Monedula GitOps 同时支持标准的 Kafka ACL 和 Confluent Platform 特有的 RBAC 角色绑定。常见的、只作用于本主题的 ACL 可以直接写在 KafkaTopic 里；对于前缀资源、共享消费者组、主机限制或原始 ACL 操作这类高级场景，模型提供了单独的 KafkaAccessPolicy 资源。Confluent RBAC 角色绑定则由 KafkaRoleBinding 管理。

它能管理什么？

首个版本覆盖了声明式管理所需的主要 Kafka 与 Confluent 实体：

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

CLI 还提供校验、漂移检测、安全预览、预检、应用、验证和导入等命令。

安装

用 Homebrew 安装 CLI：

brew install monedula-dev/tap/monedula-gitops

或者用 Go：

go install github.com/monedula-dev/monedula-gitops/cmd/monedula-gitops@latest

预编译二进制可以在 GitHub releases 获取。容器镜像发布在 ghcr.io/monedula-dev/monedula-gitops。

用 Helm 安装 Kubernetes operator：

helm install monedula-gitops \
  oci://ghcr.io/monedula-dev/charts/monedula-gitops

完整的 CLI 配置和 operator 安装说明见仓库。

快速上手

有了一份 KafkaCluster 配置和一个或多个清单之后，基本流程很短：

# 预览 Git 与运行中集群之间的差异
monedula-gitops diff -f ./manifests \
  --cluster-config-file ./cluster.yaml

# 应用期望状态
monedula-gitops apply -f ./manifests \
  --cluster-config-file ./cluster.yaml

# 确认没有残留漂移
monedula-gitops verify -f ./manifests \
  --cluster-config-file ./cluster.yaml

发现漂移时 verify 会返回非零退出码，因此适合用作 CI 的门禁。有风险的操作都有防护，删除和裁剪（pruning）则必须显式开启。

想要一个完整的本地环境，仓库里有两个可运行的快速上手示例：一个是用 Docker Compose、Kafka 和 Schema Registry 搭起来的 CLI 演练场，另一个是在本地 Kubernetes 集群上的 operator 演练场。

用 Import 从已有集群开始

GitOps 工具在空集群上很容易演示。真实环境很少是空的。

import cluster 命令会读取当前的 Kafka 状态，并据此生成 Monedula 清单：

monedula-gitops import cluster \
  --cluster-config-file ./cluster.yaml \
  --output-dir ./imported

导入器会重建主题、访问规则、配额、schema、SCRAM 用户，以及受支持情况下的 Confluent RBAC 角色绑定。简单的生产者和消费者 ACL 会被折叠进相应的 KafkaTopic；高级或含义不明确的规则则成为独立资源。

Kafka 无法透露已有的 SCRAM 密码，所以导入出来的用户里是占位的 secret 引用，必须先补齐才能应用。

关键性质是往返一致：把导入出来的目录对同一个集群做验证，应当报告没有漂移。

monedula-gitops verify -f ./imported -R \
  --cluster-config-file ./cluster.yaml

所以 Import 不只是一个导出功能。它是一条上手路径，把已有的 Kafka 环境逐步带向由 Git 管理的期望状态。

示例是项目的一部分

要学会一套复杂的 Kafka 配置，参考文档未必是最好的方式。

仓库里有一份内容丰富的场景目录，包含 25 组自包含的配置。它们覆盖主题、内联与高级访问规则、配额、schema、漂移与协调、裁剪、删除策略、多租户、Import、SCRAM 用户、SASL_SSL、mTLS、OAuth 以及 Confluent MDS/RBAC。

每个场景都带有清单、说明、预期结果和清理步骤。你可以把它们当例子跑起来，改造成自己的起点，或者作为设计自身配置的灵感。

这是首个版本——请动手试试

v0.1.0 是 Monedula GitOps 的首个公开版本。

这个工具覆盖了多个 Kafka API、授权模型、认证方式和资源生命周期。它是一个相当复杂的软件，某些组合或边界情况可能还不完全符合预期。

请先从一次性的或非生产环境开始，仔细查看 diff 或 apply --dry-run 的输出，并且只有在确认过计划中的变更之后再启用破坏性操作。

最重要的是，请动手试试。不同的 Kafka 发行版、安全配置和运维模式，恰恰是真实反馈最有价值的地方。如果你发现 bug、含糊的行为或缺失的用例，欢迎在 GitHub 上提 issue。

小结

Monedula GitOps 把 Kafka 主题、访问权限、配额、schema、用户和 Confluent RBAC 收进同一套声明式模型，既能通过对 CI 友好的 CLI 使用，也能通过 Kubernetes operator 使用。你可以从空集群起步，也可以导入已有集群，并借助可运行的快速上手示例和成型的场景来熟悉这个工具。

首个版本现已在 GitHub 上发布。