---
title: "monedula-gitops"
repo: https://github.com/monedula-dev/monedula-gitops
language: Go
license: AGPL-3.0
status: active
maintainers: ["grzegorz", "michal"]
---> **配套文章：** [Monedula GitOps：面向 CLI 与 Kubernetes 的声明式 Kafka 管理](/blog/monedula-gitops/) 介绍了 `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 由它生成：

```yaml
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
```

## 安装

```bash
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 组自包含配置的场景目录。