Wie man mit Apicurio Registry Ordnung in APIs und Schemas bringt

Stellen Sie sich vor, Sie entwickeln eine Microservices-Architektur, in der Daten durch Kafka oder REST-Anfragen fließen. Sie haben ein Dutzend Avro-Schemas, mehrere OpenAPI-Spezifikationen und einige Protobuf-Dateien angesammelt. Irgendwann aktualisiert ein Team ein Nachrichtenschema und das System eines anderen Teams „bricht", weil sie nicht rechtzeitig über die Änderungen informiert wurden. Klingt das bekannt? Natürlich könnten Sie Schemas in Git speichern und zwischen Projekten kopieren, aber das wird schnell zum Chaos.

Ich bin auf Apicurio Registry gestoßen, als ich nach einer Alternative zu Standardlösungen für API-Vertragsmanagement suchte. Es ist ein CNCF-Sandbox-Projekt, das einen spezifischen Schmerzpunkt löst: Es bietet ein zentralisiertes Repository für Ihre APIs und Schemas.

Warum sich die Mühe machen, wenn man Git hat

Die Kernfunktion geht nicht nur darum, eine Datei „ins Regal zu stellen" — es geht darum, wie das Registry mit diesen Daten arbeitet. Apicurio Registry kann die Schema-Kompatibilität in Echtzeit validieren. Wenn ein Producer-Dienst versucht, eine neue Schema-Version zu veröffentlichen, kann das Registry das Update blockieren, wenn es die Rückwärtskompatibilität bricht. Sie fangen den Fehler ab, bevor fehlerhafte Daten in der Message-Queue landen.

Zusätzlich übernimmt das Projekt die Versionierung für Sie. Jedes Schema erhält einen klaren Lebenszyklus, und Konsumenten wissen immer, welche Version sie verwenden sollen.

Was steckt dahinter und wie es funktioniert

Die Apicurio-Entwickler haben sich für Quarkus als Grundlage entschieden, was das Tool schnell und leichtgewichtig macht. Aber der interessanteste Teil ist die Flexibilität bei den Speicheroptionen. Zuvor gab es eine separate Binary für jede Datenbank, und in Version 3.0 sind sie auf ein einzelnes Artefakt umgestiegen. Jetzt setzen Sie einfach die Umgebungsvariable APICURIO_STORAGE_KIND und wählen aus folgenden Optionen:

• SQL — die klassische Wahl. Standardmäßig H2 (praktisch für Tests), aber in der Produktion sind PostgreSQL oder SQL Server die bessere Wahl.
• KafkaSQL — speichert Daten direkt in Kafka-Topics. Das ist praktisch, wenn Sie keine separate relationale Datenbank zu Ihrer Infrastruktur hinzufügen möchten und bereits einen Kafka-Cluster haben.
• GitOps — eine Option für diejenigen, die eine deklarative Verwaltung bevorzugen.

Für diejenigen, die Kubernetes verwenden, gibt es einen fertigen Operator. Updates kommen über OLM-Kanäle, daher ist es nicht allzu schmerzhaft, eine aktuelle Version in Ihrem Cluster zu halten.

Wie man es ausprobieren kann

Der schnellste Weg, sich das System anzusehen, ist das fertige Docker-Image auszuführen. Aber es ist wichtig zu bedenken: Die UI wurde in einen separaten Container ausgelagert.

Um den Server selbst auszuführen:

docker run -it -p 8080:8080 apicurio/apicurio-registry:latest-snapshot

Und für die Oberfläche:

docker run -it -p 8888:8080 apicurio/apicurio-registry-ui:latest-snapshot

Danach ist das Management-Dashboard unter localhost:8888 verfügbar, und die Dokumentation für die eigene API des Registries unter localhost:8080/apis.

Wenn Sie ein vollständiges Setup mit PostgreSQL für richtige Tests bereitstellen möchten, ist der einfachste Weg eine Docker Compose-Datei:

services:
  postgres:
    image: postgres
    environment:
      POSTGRES_USER: apicurio-registry
      POSTGRES_PASSWORD: password
  app:
    image: apicurio/apicurio-registry:3.0.0
    ports:
      - 8080:8080
    environment:
      APICURIO_STORAGE_KIND: 'sql'
      APICURIO_STORAGE_SQL_KIND: 'postgresql'
      APICURIO_DATASOURCE_URL: 'jdbc:postgresql://postgres/apicurio-registry'
      APICURIO_DATASOURCE_USERNAME: apicurio-registry
      APICURIO_DATASOURCE_PASSWORD: password

Build-Stufen für Ungeduldige

Wenn Sie sich entscheiden, sich in den Quellcode zu vertiefen und das Projekt selbst zu bauen, bietet das Projekt drei Build-„Stufen". Das spart viel Zeit.

Mit dem -Dlocal-Flag bauen Sie nur den Server-Kern und das Java SDK ohne zusätzliche Style-Checks und Javadoc-Generierung. Der Build dauert etwa 3 Minuten. Wenn Sie das vollständige Paket mit Go SDK und Operatoren benötigen, verwenden Sie -Dfull. Das ist ein großartiges Beispiel dafür, wie das Projekt auf die Zeit der Contributors achtet.

Sicherheitsaspekte

Standardmäßig erfordert das Registry keine Autorisierung, was für die lokale Entwicklung in Ordnung ist, aber in einem Unternehmensnetzwerk gefährlich. Das Tool unterstützt OpenID Connect (OIDC)-Integration. Sie können Keycloak oder einen anderen kompatiblen Server verbinden, indem Sie einige Umgebungsvariablen übergeben: QUARKUS_OIDC_AUTH_SERVER_URL und QUARKUS_OIDC_CLIENT_ID. Die Konfiguration deckt sowohl die REST-API als auch die Benutzeroberfläche ab.

Zusammenfassung: Für wen es sich lohnt

Apicurio Registry wird definitiv für Teams nützlich sein, die:

1. aktiv Kafka verwenden und Schwierigkeiten haben, Avro/Protobuf-Schemas zu pflegen.
2. API-Kompatibilitätsprüfungen automatisieren möchten (OpenAPI/AsyncAPI).
3. nach einer leichtgewichtigen Alternative zu Confluent Schema Registry suchen, die nicht eng an ein einzelnes Ökosystem gekoppelt ist.

Das Projekt wirkt lebendig, die Dokumentation (sogar die eingebaute API-Dokumentation) ist detailliert, und der Umstieg auf Quarkus macht den Betrieb angenehm. Wenn Ihre Microservices eine „Wildwest-Situation" bei Contracts haben — versuchen Sie, eine Stunde damit zu verbringen, dieses Registry hochzufahren. Sehr wahrscheinlich löst es die meisten Ihrer Schema-Versionsprobleme.