Apicurio RegistryでAPIとスキーマに秩序をもたらす

KafkaやRESTリクエストを通じてデータが流れるマイクロサービスアーキテクチャを構築している状況を想像してみてください。Avroスキーマが10個以上、OpenAPI仕様がいくつか、Protobufファイルがいくつか溜まっているとします。ある時点で、一つのチームがメッセージスキーマを更新し、別のチームのシステムが「壊れた」という状況に陥ります。変更通知が遅れたためです。身に覚えがありますか？もちろん、Gitにスキーマを保存してプロジェクト間でコピーするという方法がありますが、すぐに混乱を招くようになります。

標準的なAPIコントラクト管理ソリューションの代替手段を探していたところ、Apicurio Registryに出会いました。これはCNCFサンドボックスプロジェクトで、特定の課題を解決します：APIとスキーマのための一元的なリポジトリを提供します。

Gitがあるのに、なぜ必要なのか

主要な特徴は、単にファイルを「棚に置く」ことではなく、レジストリがそのデータとどのように連携するかということです。Apicurio Registryは、スキーマの互換性をリアルタイムで検証できます。プロデューサーサービスが新しいスキーマバージョンを公開しようとすると、レジストリは下位互換性を壊す更新をブロックできます。誤ったデータがメッセージキューに入る前に、エラーを検出できます。

さらに、プロジェクトはバージョニングを自動的に管理します。各スキーマは明確なライフサイクルを持ち、コンシューマは常にどのバージョンを使えばよいか把握できます。

内部構造と動作原理

Apicurioの開発者はQuarkusを基盤に選び、ツールを高速かつ軽量にしました。しかし、最も興味深い点はストレージオプションの柔軟性です。以前はデータベースごとに別々のバイナリがありましたが、バージョン3.0では単一アーティファクトに移行しました。今は単に環境変数を設定するだけです：

• SQL — 古典的な選択肢です。デフォルトでH2を使用し（テストに便利）、本番環境ではPostgreSQLまたはSQL Serverの使用をお勧めします。
• KafkaSQL — データを直接Kafkaトピックに保存します。インフラに別のリレーショナルデータベースを追加したくない場合で、Kafkaクラスタが既にあれば便利です。
• GitOps — 宣言的な管理を求める人向けのオプションです。

Kubernetesを使用している人のために、 готовый operator が用意されています。更新はOLMチャネルを通じて行われるため、クラスタで最新バージョンを維持することは、それほど痛苦ではありません。

試用方法

最も迅速にシステムを確認 방법은、 готовый Dockerイメージを実行することです。ただし重要な点として、UIは別のコンテナに移動されました。

サーバー自体を実行するには：

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

そしてインターフェース用には：

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

その後、管理ダッシュボードは localhost:8888 で利用でき、レジストリのAPIドキュメントは localhost:8080/apis にあります。

適切なテストのためにPostgreSQLを含む完全なセットアップをデプロイしたい場合は、最も簡単な方法はDocker Composeファイルを作成することです：

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

急いでいる人のためのビルドティア

ソースコードを調査して自分でプロジェクトをビルドしようと決めた場合、プロジェクトは3つのビルド「ティア」を提供します。これにより、大幅な時間節約になります。

フラグを使用すると、追加のスタイルチェックやJavadoc生成なしで、サーバコアとJava SDKのみがビルドされます。ビルドは約3分かかります。Go SDKと演算子を含む完全なパッケージが必要な場合は、 を使用してください。これは、プロジェクトが貢献者の時間を大切に考えている素晴らしい例です。

セキュリティの考慮事項

デフォルトでは、レジストリは認証を必要としません。これはローカル開発には適していますが、企業ネットワークでは危険です。このツールはOpenID Connect（OIDC）統合をサポートしています。環境変数とを渡すだけで、Keycloakまたはその他の互換性のあるサーバーを接続できます。設定はREST APIとユーザーインターフェースの両方を対象としています。

まとめ：誰が試みるべきか

Apicurio Registryは、次のようなチームにとって確かに便利です：

1. Kafka активно 使用し、Avro/Protobufスキーマの管理に苦労している。
2. API互換性チェック（OpenAPI/AsyncAPI）の自動化を望んでいる。
3. 単一のエコシステムに密結合されていない、Confluent Schema Registryの軽量な代替手段を探している。

プロジェクトは活発で、ドキュメント（組み込みのAPIドキュメントでさえも）は詳細であり、Quarkusへの移行は運用を快適なものにしています。マイクロサービスのコントラクトが「自由奔放」な状況にあるなら、1時間費やしてこのレジストリを試してみる価値があります。ほとんどのスキーマバージョニングの問題を解決できる可能性が高いでしょう。