Monedula GitOps — CLI と Kubernetes のための宣言的な Kafka 管理

Kafka の設定が一か所にまとまっていることは、めったにありません。

トピックはあるスクリプトが作り、ACL は別のスクリプトが作り、スキーマはアプリケーションのパイプラインが、クォータは管理者が、Confluent RBAC のロールバインディングはさらに別のツールが作ります。時間が経つと、稼働中のクラスタだけがシステムの唯一の信頼できる記述になります — 意図して書かれたものでも、レビューできるものでもない記述が。

だからこそ私たちは Monedula GitOps を作りました。Kafka のリソースを宣言的でバージョン管理された YAML として管理する、オープンソースのツールです。

目的はシンプルです。

あるべき Kafka の状態を Git に記述し、コードと同じようにレビューし、稼働中のクラスタと比較し、クラスタをその状態へ収束させる。

この記事では、最初の公開リリースである v0.1.0 を紹介します。ドキュメント全体を繰り返すのではなく、モデルと基本的なワークフローに焦点を当てます。

なぜもう 1 つ Kafka 向けの GitOps ツールを?

GitOps はインフラに明確な信頼できる情報源、レビュー履歴、再現可能な変更、そしてドリフト検出をもたらします。しかし Kafka はトピックだけではありません。実用的な管理ツールは、アクセスルール、コンシューマーグループ、クォータ、スキーマ、認証情報、そして Confluent Platform ではロールバインディングも理解する必要があります。

さらに導入の問題もあります。ほとんどの Kafka クラスタはすでに存在しています。GitOps を導入する前に、その完全な状態を手作業でマニフェストとして作り直すのは、大きな移行の壁になります。

Monedula GitOps は、この 2 つの問題を軸に設計しました。

ふつう一緒に扱われる Kafka 固有のリソースをカバーする;
よくあるケース、とくにトピックとその利用を許可されたアプリケーションを簡単に書けるようにする;
インポートのワークフローで既存クラスタをサポートする;
Kubernetes があってもなくても動く。

1 つの宣言的モデル、2 つの実行方法

中心となる設計判断は、CLI と Kubernetes オペレーターが同じリソースモデルと同じリコンサイルエンジンを使うことです。

CLI モードでは、開発マシンや CI/CD パイプラインからマニフェストを検証し、比較し、適用し、確認できます。オペレーターモードでは、同じ Kubernetes スタイルのリソースを CRD としてインストールし、Kubernetes クラスタの中で継続的にリコンサイルします。

そのため、CLI が使う KafkaTopic は Kubernetes のカスタムリソースとして適用することもできます。認証情報の与え方は、当然ながらランタイムごとに異なります — 例えば CLI では環境変数やファイルの参照、オペレーターでは Kubernetes の Secret です — が、あるべき状態、ドリフトのルール、実行のセマンティクスは一貫しています。

これによりチームは、まずパイプライン駆動の変更から始め、2 つ目の設定モデルを設計することなく、後からオペレーターを導入できます。

トピックとそのアクセス権を 1 つのマニフェストに

いちばんよく扱うリソースは、いちばん簡単に書けるべきです。

KafkaTopic には、パーティション数、トピック設定、Schema Registry のスキーマ、そしてプロデューサーとコンシューマーの一般的なアクセスルールをまとめて書けます。

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 を生成します。

Monedula GitOps は、標準の Kafka ACL と、Confluent Platform 固有の RBAC ロールバインディングの両方をサポートします。トピックに閉じたよくある ACL は KafkaTopic に直接書けます。プレフィックス付きリソース、共有コンシューマーグループ、ホスト制限、生の ACL 操作といった高度なケースのために、モデルには独立した KafkaAccessPolicy リソースがあります。Confluent RBAC のロールバインディングは KafkaRoleBinding で管理します。

何を管理できるのか

最初のリリースは、宣言的な管理に必要な主要な Kafka / Confluent のエンティティをカバーします。

KafkaCluster — 接続情報、認証、デフォルト値、Schema Registry、任意の Confluent MDS 設定;
KafkaTopic — トピックのライフサイクル、パーティション、設定、トピックローカルなアクセス、スキーマ;
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 のリリースから入手できます。コンテナイメージは ghcr.io/monedula-dev/monedula-gitops で公開しています。

Kubernetes オペレーターは Helm でインストールします。

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

CLI の設定とオペレーターのインストールの詳細はリポジトリを参照してください。

クイックスタート

KafkaCluster の設定と 1 つ以上のマニフェストが用意できれば、基本のワークフローはごく短いものです。

# 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 はドリフトを見つけると 0 以外の終了コードを返すので、CI のゲートとして使えます。リスクのある操作にはガードがかかっており、削除とプルーニングは明示的に有効化しないと実行されません。

完結したローカル環境として、リポジトリには実行できるクイックスタートが 2 つ入っています。Docker Compose と Kafka、Schema Registry を使う CLI のプレイグラウンドと、ローカルの Kubernetes クラスタ上で動くオペレーターのプレイグラウンドです。

Import で既存クラスタから始める

GitOps ツールは空のクラスタでは簡単にデモできます。現実の環境が空であることは、まずありません。

import cluster コマンドは現在の Kafka の状態を読み取り、そこから Monedula のマニフェストを生成します。

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

インポーターは、トピック、アクセスルール、クォータ、スキーマ、SCRAM ユーザー、そしてサポートされている場合は Confluent RBAC のロールバインディングを再構成します。単純なプロデューサーとコンシューマーの ACL は該当する KafkaTopic に畳み込まれ、高度な、あるいは曖昧なルールは独立したリソースになります。

Kafka は既存の SCRAM パスワードを開示できないため、インポートされたユーザーにはプレースホルダーのシークレット参照が入ります。適用する前に実際の値を与える必要があります。

大事なのはラウンドトリップです。インポートしたディレクトリを同じクラスタに対して検証すると、ドリフトは報告されないはずです。

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

つまり Import は単なるエクスポート機能ではありません。既存の Kafka 環境を、Git で管理されるあるべき状態へ移すためのオンボーディング経路です。

サンプルはプロジェクトの一部

複雑な Kafka の設定を学ぶのに、リファレンスドキュメントが常に最良の方法とはかぎりません。

リポジトリには、25 個の自己完結した設定セットからなる充実したシナリオカタログが入っています。トピック、インラインおよび高度なアクセスルール、クォータ、スキーマ、ドリフトとリコンサイル、プルーニング、削除ポリシー、マルチテナンシー、Import、SCRAM ユーザー、SASL_SSL、mTLS、OAuth、Confluent MDS/RBAC までを扱います。

各シナリオにはマニフェスト、解説、期待される結果、後片付けの手順が含まれます。そのまま例として実行することも、出発点として書き換えることも、自分の設定を考えるヒントとして使うこともできます。

これは最初のリリースです — ぜひ試してください

v0.1.0 は Monedula GitOps の最初の公開リリースです。

このツールは複数の Kafka API、認可モデル、認証方式、リソースのライフサイクルをカバーしています。それなりに複雑なソフトウェアであり、組み合わせやエッジケースによっては、まだ期待どおりに動かないことがあるかもしれません。

まずは使い捨ての環境か非本番環境から始め、diff や apply --dry-run の出力をよく確認し、破壊的な操作は計画された変更を確認したうえで有効にしてください。

そして何より、実際に試してください。さまざまな Kafka ディストリビューション、セキュリティ設定、運用モデルこそ、現場からのフィードバックが本当に役に立つ場所です。バグ、分かりにくい挙動、足りないユースケースを見つけたら、GitHub の issue を立ててください。

まとめ

Monedula GitOps は、Kafka のトピック、アクセス、クォータ、スキーマ、ユーザー、Confluent RBAC を 1 つの宣言的モデルにまとめ、CI に馴染む CLI からでも Kubernetes オペレーターからでも扱えるようにします。空のクラスタから始めることも、既存のクラスタをインポートすることもでき、実行できるクイックスタートと作り込まれたシナリオでツールを学べます。

最初のリリースは GitHub で公開中です。