---
title: "Monedula GitOps: deklaratywne zarządzanie Kafką dla CLI i Kubernetesa"
date: 2026-08-24T00:00:00.000Z
author: "grzegorz"
excerpt: "Monedula GitOps zarządza tematami Kafki, dostępem, limitami, schematami, użytkownikami i Confluent RBAC na podstawie wersjonowanych manifestów — przez CLI albo przez operator Kubernetesa."
---
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](https://github.com/monedula-dev/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:

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

Na 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:

```bash
brew install monedula-dev/tap/monedula-gitops
```

Albo przez Go:

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

Gotowe binaria są dostępne w [wydaniach na GitHubie](https://github.com/monedula-dev/monedula-gitops/releases/latest). Obraz kontenera publikujemy pod `ghcr.io/monedula-dev/monedula-gitops`.

Zainstaluj operator Kubernetesa przez Helma:

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

Pełną [konfigurację CLI](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/cli.md) i [instalację operatora](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/operator.md) opisuje repozytorium.

## Szybki start

Kiedy masz już konfigurację `KafkaCluster` i jeden lub więcej manifestów, podstawowy przepływ jest krótki:

```bash
# 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.yaml
```

`verify` 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](https://github.com/monedula-dev/monedula-gitops/tree/main/quickstart) 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:

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

Importer 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.

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

Import 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](https://github.com/monedula-dev/monedula-gitops/tree/main/scenarios) 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](https://github.com/monedula-dev/monedula-gitops/issues).

## 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](https://github.com/monedula-dev/monedula-gitops).