Konfiguracja Kafki rzadko mieszka w jednym miejscu.
Tematy tworzy jeden skrypt, ACL-e drugi, schematy — pipeline’y aplikacji, limity ustawia administrator, a powiązania ról Confluent RBAC powstają jeszcze w innym narzędziu. Z czasem jedynym wiarygodnym opisem systemu staje się działający klaster — opisem, którego nikt nie zaprojektował i którego nie da się przejrzeć.
Dlatego stworzyliśmy Monedula GitOps: otwartoźródłowe narzędzie do zarządzania zasobami Kafki jako deklaratywnym, wersjonowanym YAML-em.
Cel jest prosty:
Opisz pożądany stan Kafki w Gicie, przejrzyj go jak kod, porównaj z działającym klastrem i doprowadź klaster do tego stanu.
Ten artykuł przedstawia pierwsze publiczne wydanie, v0.1.0. Skupia się na modelu i podstawowym przepływie pracy, a nie na powtarzaniu pełnej dokumentacji.
Po co kolejne narzędzie GitOps do Kafki?
GitOps daje infrastrukturze jasne źródło prawdy, historię przeglądów, powtarzalne zmiany i wykrywanie dryfu. Kafka to jednak nie tylko tematy. Użyteczne narzędzie do zarządzania musi też rozumieć reguły dostępu, grupy konsumentów, limity, schematy, poświadczenia, a w Confluent Platform — powiązania ról RBAC.
Jest jeszcze problem wdrożenia: większość klastrów Kafki już istnieje. Ręczne odtwarzanie ich pełnego stanu w manifestach przed przejściem na GitOps tworzy wysoki próg migracji.
Monedula GitOps zaprojektowaliśmy wokół obu tych problemów:
- obejmij te zasoby specyficzne dla Kafki, które zwykle idą w parze;
- uprość najczęstszy przypadek, czyli temat i aplikacje, które mają prawo z niego korzystać;
- wspieraj istniejące klastry dzięki importowi;
- działaj zarówno z Kubernetesem, jak i bez niego.
Jeden deklaratywny model, dwa sposoby uruchomienia
Kluczowa decyzja projektowa jest taka, że CLI i operator Kubernetesa używają tego samego modelu zasobów i tego samego silnika uzgadniania.
W trybie CLI manifesty można walidować, porównywać, stosować i weryfikować z maszyny dewelopera albo z pipeline’u CI/CD. W trybie operatora te same zasoby w stylu Kubernetesa instaluje się jako CRD i są one w sposób ciągły uzgadniane wewnątrz klastra Kubernetesa.
KafkaTopic używany przez CLI może więc zostać zastosowany również jako zasób niestandardowy Kubernetesa. Poświadczenia dostarcza się naturalnie inaczej w każdym środowisku uruchomieniowym — na przykład przez zmienne środowiskowe lub odwołania do plików w CLI oraz Sekrety Kubernetesa w operatorze — ale pożądany stan, reguły dryfu i semantyka wykonania pozostają spójne.
Dzięki temu zespół może zacząć od zmian sterowanych pipeline’em, a później wdrożyć operator bez projektowania drugiego modelu konfiguracji.
Temat i dostęp do niego w jednym manifeście
Zasób, z którym pracuje się najczęściej, powinien być też najłatwiejszy do opisania.
KafkaTopic może zawierać liczbę partycji, konfigurację tematu, schemat z Schema Registry oraz typowe reguły dostępu dla producentów i konsumentów:
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-ordersNa podstawie tego manifestu Monedula GitOps zarządza tematem i generuje odpowiadające mu ACL-e tematu oraz grupy konsumentów.
Monedula GitOps obsługuje zarówno standardowe ACL-e Kafki, jak i powiązania ról RBAC specyficzne dla Confluent Platform. Typowe ACL-e lokalne dla tematu można zdefiniować wprost w KafkaTopic; dla przypadków zaawansowanych — takich jak zasoby z prefiksem, współdzielone grupy konsumentów, ograniczenia hostów czy surowe operacje ACL — model udostępnia osobny zasób KafkaAccessPolicy. Powiązaniami ról Confluent RBAC zarządza KafkaRoleBinding.
Czym może zarządzać?
Pierwsze wydanie obejmuje główne encje Kafki i Confluenta potrzebne do zarządzania deklaratywnego:
KafkaCluster— dane połączenia, uwierzytelnianie, wartości domyślne, Schema Registry i opcjonalna konfiguracja Confluent MDS;KafkaTopic— cykl życia tematu, partycje, konfiguracja, dostęp lokalny dla tematu i schematy;KafkaAccessPolicy— zaawansowane i współdzielone reguły ACL Kafki;KafkaQuota— limity dla użytkownika, client-id i IP;KafkaUser— poświadczenia SCRAM w Kafce;KafkaRoleBinding— powiązania ról MDS/RBAC w Confluent Platform.
CLI udostępnia też polecenia walidacji, wykrywania dryfu, bezpiecznych podglądów, kontroli wstępnych (preflight), stosowania zmian, weryfikacji i importu.
Instalacja
Zainstaluj CLI przez Homebrew:
brew install monedula-dev/tap/monedula-gitopsAlbo przez Go:
go install github.com/monedula-dev/monedula-gitops/cmd/monedula-gitops@latestGotowe binaria są dostępne w wydaniach na GitHubie. Obraz kontenera publikujemy pod ghcr.io/monedula-dev/monedula-gitops.
Zainstaluj operator Kubernetesa przez Helma:
helm install monedula-gitops \
oci://ghcr.io/monedula-dev/charts/monedula-gitopsPełną konfigurację CLI i instalację operatora opisuje repozytorium.
Szybki start
Kiedy masz już konfigurację KafkaCluster i jeden lub więcej manifestów, podstawowy przepływ jest krótki:
# Podejrzyj różnicę między Gitem a działającym klastrem
monedula-gitops diff -f ./manifests \
--cluster-config-file ./cluster.yaml
# Zastosuj pożądany stan
monedula-gitops apply -f ./manifests \
--cluster-config-file ./cluster.yaml
# Potwierdź, że nie został żaden dryf
monedula-gitops verify -f ./manifests \
--cluster-config-file ./cluster.yamlverify zwraca niezerowy kod wyjścia, gdy wykryje dryf, więc nadaje się na bramkę w CI. Ryzykowne operacje są zabezpieczone, a usuwanie i przycinanie (pruning) wymagają wyraźnej zgody.
Kompletne środowisko lokalne dają dwa gotowe do uruchomienia quickstarty w repozytorium: plac zabaw dla CLI z Docker Compose, Kafką i Schema Registry oraz plac zabaw dla operatora na lokalnym klastrze Kubernetesa.
Zacznij od istniejącego klastra dzięki importowi
Narzędzia GitOps łatwo pokazać na pustym klastrze. Prawdziwe środowiska rzadko są puste.
Polecenie import cluster odczytuje bieżący stan Kafki i generuje z niego manifesty Monedula:
monedula-gitops import cluster \
--cluster-config-file ./cluster.yaml \
--output-dir ./importedImporter odtwarza tematy, reguły dostępu, limity, schematy, użytkowników SCRAM oraz — tam, gdzie jest to wspierane — powiązania ról Confluent RBAC. Proste ACL-e producentów i konsumentów trafiają do odpowiedniego KafkaTopic; reguły zaawansowane lub niejednoznaczne stają się osobnymi zasobami.
Kafka nie potrafi ujawnić istniejących haseł SCRAM, więc zaimportowani użytkownicy zawierają zastępcze odwołania do sekretów, które trzeba uzupełnić przed zastosowaniem.
Ważna jest podróż w obie strony: weryfikacja zaimportowanego katalogu wobec tego samego klastra nie powinna zgłosić żadnego dryfu.
monedula-gitops verify -f ./imported -R \
--cluster-config-file ./cluster.yamlImport nie jest więc tylko funkcją eksportu. To ścieżka wdrożenia, która pozwala przenieść istniejące środowisko Kafki w stronę pożądanego stanu zarządzanego z Gita.
Przykłady są częścią projektu
Dokumentacja referencyjna nie zawsze jest najlepszym sposobem na naukę skomplikowanej konfiguracji Kafki.
Repozytorium zawiera bogaty katalog scenariuszy z 25 samodzielnymi zestawami konfiguracji. Obejmują tematy, wbudowane i zaawansowane reguły dostępu, limity, schematy, dryf i uzgadnianie, przycinanie, polityki usuwania, wielodostępność, import, użytkowników SCRAM, SASL_SSL, mTLS, OAuth oraz Confluent MDS/RBAC.
Każdy scenariusz zawiera manifesty, wyjaśnienie, oczekiwane rezultaty i instrukcje sprzątania. Można je uruchamiać jako przykłady, adaptować jako punkty wyjścia albo traktować jako inspirację do własnych ustawień.
To pierwsze wydanie — przetestuj je
v0.1.0 to pierwsze publiczne wydanie Monedula GitOps.
Narzędzie obejmuje kilka API Kafki, modele autoryzacji, metody uwierzytelniania i cykle życia zasobów. To dość skomplikowany kawałek oprogramowania i niektóre kombinacje albo przypadki brzegowe mogą jeszcze nie działać dokładnie tak, jak się tego spodziewasz.
Zacznij od środowiska jednorazowego lub nieprodukcyjnego, uważnie przeglądaj wynik diff albo apply --dry-run, a operacje destrukcyjne włączaj dopiero po przejrzeniu planowanych zmian.
Przede wszystkim jednak: przetestuj je. Różne dystrybucje Kafki, konfiguracje bezpieczeństwa i modele operacyjne to dokładnie te miejsca, w których informacja zwrotna z praktyki jest najcenniejsza. Jeśli znajdziesz błąd, niejasne zachowanie albo brakujący przypadek użycia, załóż zgłoszenie na GitHubie.
Podsumowanie
Monedula GitOps sprowadza tematy Kafki, dostęp, limity, schematy, użytkowników i Confluent RBAC do jednego deklaratywnego modelu, który działa przez przyjazne CI narzędzie CLI albo przez operator Kubernetesa. Możesz zacząć od pustego klastra, zaimportować istniejący i poznać narzędzie dzięki gotowym quickstartom i opracowanym scenariuszom.
Pierwsze wydanie jest już dostępne na GitHubie.