面向 Apache Kafka 的 GitOps

在 Git 中以 YAML 描述主题、访问权限、配额、schema、SCRAM 用户和 Confluent RBAC。monedula-gitops 会把它与运行中的集群比对，只应用发生变化的部分，并在集群出现漂移时让 CI 失败。同一套清单既可以由 CLI 运行，也可以由 Kubernetes operator 运行。

开始使用（英文） GitHub

brew install monedula-dev/tap/monedula-gitops

manifests/orders.yaml

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 diff -f ./manifests --cluster-config-file ./cluster.yaml# preview: the topic, plus the ACLs its access block compiles to$ monedula-gitops apply -f ./manifests --cluster-config-file ./cluster.yaml$ monedula-gitops verify -f ./manifests --cluster-config-file ./cluster.yaml# exit 0: no drift. exit 1: drift, and the CI job fails.

6: 资源类型，从主题到 Confluent RBAC 角色绑定
8: 在 CI 中测试过的 broker 镜像：Apache Kafka 3.9 到 4.3，Confluent Platform 7.6 到 8.3
25: 可运行的场景，收录在仓库中，每个都经过端到端检查

问题所在

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

主题来自一个脚本，ACL 来自另一个脚本，schema 来自应用的流水线，配额来自管理员，Confluent RBAC 的角色绑定又来自另一套工具。时间一长，只有运行中的集群还描述着这个系统，而这份描述从未经过任何人评审。

工作原理

01 import cluster
导入

把运行中的集群转换为清单。
02 YAML + pull request
声明

以 Kubernetes 风格的 YAML 描述主题、访问权限、配额、schema、SCRAM 用户和角色绑定。
03 diff
比对

diff 和 apply --dry-run 会先展示针对运行中集群的计划。
04 apply
应用

只执行必要的操作。裁剪和有风险的变更需要显式的标志才会执行。
05 verify
验证

发现漂移时 verify 返回退出码 1，因此定时运行的 CI 任务能发现绕过 Git 的变更。

Git 仓库 manifests/*.yaml，在 pull request 中评审
→
CI 中的 CLI validate, diff, apply, verify
Kubernetes 中的 operator CRD，准入 webhook，协调循环
→
Kafka 主题，ACL，配额，SCRAM 用户
Schema Registry 与 MDS schema，Confluent RBAC 角色绑定

Git 中的清单驱动 CI 中的 CLI 和 Kubernetes 中的 operator，再由它们修改 Kafka、Schema Registry 和 MDS。

主题及其访问权限，写在同一份清单里

大多数 Kafka 工具把主题放在一处，把它的访问权限放在另一处。monedula-gitops 把访问权限直接挂在主题上：列出生产者和消费者，相应的主题 ACL 和消费者组 ACL 就会自动生成。在使用 RBAC 的集群上，同一个块还可以编译为 Confluent MDS 角色绑定。

如果你需要前缀模式、共享消费者组或主机限制，还有独立的 KafkaAccessPolicy 和 KafkaRoleBinding 资源可用。

Strimzi: KafkaTopic + KafkaUser
Confluent for Kubernetes: 主题 + 单独的角色绑定资源
Jikkou: 主题 + 单独的 principal 资源
Terraform: 每条 ACL 一个资源
monedula-gitops: 一个带 access 块的 KafkaTopic

导入已有集群

import cluster 会读取主题、ACL、配额、schema，以及在受支持情况下的 RBAC 角色绑定，并写出清单。用同一个集群验证这些清单，不会报告任何漂移。

如何导入集群（英文）

终端

monedula-gitops import cluster --cluster-config-file ./clusters/prod.yaml --output-dir ./imported
monedula-gitops verify -f ./imported -R --cluster-config-file ./clusters/prod.yaml   # exits 0: no drift

SCRAM 用户与 Confluent RBAC 角色绑定

KafkaUser 声明一个 SCRAM 凭据，这样主题、它的访问权限以及使用它的 principal 都一起保存在 Git 中。CLI 从环境变量或文件读取密码；operator 从 Kubernetes Secret 读取密码，或自动生成一个。

KafkaRoleBinding 与 ACL 一起管理 Confluent MDS 角色绑定。

manifests/svc-checkout.yaml

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaUser
metadata:
  name: svc-checkout
spec:
  clusterRef: { name: prod }
  password:
    valueFrom: { env: SVC_CHECKOUT_PASSWORD }

没有任何东西会被意外删除

--dry-run 会预览每一项变更。对于你从 Git 中移除的主题、SCRAM 用户或配额，CLI 从不删除。--prune 只删除仍处于你的清单所声明的某项授权范围内的 ACL 和角色绑定；分区扩容、降低 schema 兼容性或移除配额上限这类有风险的变更要等待 --allow-destructive。在 Kubernetes 中，主题的删除策略决定删除资源时是否同时删除该主题，而 Delete 还需要 allow-delete 注解。

安全门禁（英文）

退出码
0	成功，或 `verify` 未发现漂移
1	检测到漂移（`verify`）
2	校验、配置或连接错误，或某个操作失败
3	只剩下受门禁限制的操作：它们在等待 `--allow-destructive`

安装

HomebrewGoDockerHelm (operator)

Homebrew

brew install monedula-dev/tap/monedula-gitops

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

Docker

docker run --rm ghcr.io/monedula-dev/monedula-gitops:latest --help

Helm (operator)

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

Linux 和 macOS 的预编译二进制文件可在发布页面获取。下一步：CLI 入门（英文）。

常见问题

monedula-gitops 免费吗？可以在工作中使用吗？

是的。它采用 AGPL-3.0 许可证，没有付费版本；在你自己的集群上使用它，无论作为 CLI 还是作为你自己基础设施中的 operator，都不要求你公开代码或清单：AGPL 义务在你分发它（无论是否经过修改）或让他人通过网络使用修改后的版本时适用。如需商业许可，请联系我们。

它支持 Confluent Platform 和 Confluent Cloud 吗？

完全支持 Apache Kafka 和 Confluent Platform，包括 Schema Registry，以及 Confluent Platform 上的 MDS 角色绑定。Confluent Cloud 已针对主题、ACL、schema 和导入完成验证；Cloud 不提供配额和 SCRAM 的 API。测试过的版本见支持的平台（英文）。

它和 Jikkou 有什么不同？

两者都以代码方式管理 Kafka。monedula-gitops 直接在主题上声明访问权限，既能作为 CLI 运行，也能作为持续协调的 Kubernetes operator 运行，并通过 MDS 管理 Confluent Platform 的角色绑定。Jikkou 以 CLI 或 API 服务器的形式运行，覆盖更多平台和资源类型，例如 Kafka Connect 连接器和 Confluent Cloud 角色绑定。对比页面（英文）列出了详细信息及其核对日期。