Quarkusエクステンションレジストリ
Quarkus CLI 、 Maven 、 Gradle プラグインなどのQuarkus開発ツール、または code.quarkus.io を使用して、Quarkusエコシステムを一覧表示し、特定の条件に一致するエクステンションを検索できます。Quarkusエコシステムには、 Quarkusプラットフォーム エクステンションや、コミュニティによって提供されたその他のさまざまなエクステンションが含まれ、その多くは Quarkiverse Hub でホストされています。
利用可能なすべてのQuarkusエクステンションに関する情報は、 Quarkus extension registries によって開発ツールに提供されます。
Quarkusのエクステンションレジストリは、以下の情報を提供するデータベースです:
-
利用可能なQuarkusプラットフォームのうち、どのプラットフォームが新規プロジェクトやアップデートに推奨されているか。
-
利用可能なプラットフォーム以外のエクステンションについて、それらがどのQuarkusバージョンと互換性があるか。
registry.quarkus.io
registry.quarkus.io にあるレジストリは、デフォルトのQuarkusコミュニティエクステンションレジストリです。このレジストリは、 Quarkusコミュニティプラットフォーム のリリースごとに更新され、 Quarkiverse Hub にホストされているエクステンションも含まれます。
Mavenリポジトリ
registry.quarkus.io にあるレジストリは、Maven スナップショット リポジトリであり、プラットフォームとエクステンションカタログをMaven JSONアーティファクトとして開発ツールに提供します。エクステンションカタログはダウンロードされると、ユーザーのローカルMavenリポジトリにキャッシュされ、インターネットネットワーク（またはレジストリ自体）が利用できない場合でも、開発ツールで利用できます。
ローカルにキャッシュされたエクステンションカタログアーティファクトは、定期的に更新がチェックされ、それらのカタログの新しいバージョンがレジストリで利用可能な場合は更新されます。更新をチェックするデフォルトの間隔は毎日で、これはSNAPSHOTアーティファクトのデフォルトのMavenリポジトリ updatePolicy に一致します。
Mavenリポジトリの設定
以下のリポジトリの設定は、説明のためだけに示されており、ユーザーの settings.xml やアプリケーションの pom.xml に追加する必要はありません。Quarkusの開発ツールには、このリポジトリがあらかじめ設定されています。
|
registry.quarkus.io の Mavenリポジトリ設定 は以下の通りです。
<repository>
<id>registry.quarkus.io</id>
<name>Quarkus community extension registry</name>
<url>https://registry.quarkus.io/maven</url>
<snapshots>
<enabled>true</enabled>
<updatePolicy>daily</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</snapshots>
</repository>Quarkus開発ツールが初期化されると、このリポジトリ設定が自動的にMavenリゾルバに追加され、 registry.quarkus.io からのプラットフォームおよびエクステンションカタログの解決に使用されます。
Mavenリポジトリのミラーとプロキシ
Quarkus dev toolsのMavenリゾルバが初期化されると、ユーザー settings.xml の関連するMavenミラーとプロキシは、あたかも registry.quarkus.io Mavenリポジトリがユーザー settings.xml で構成されているかのように、自動的に registry.quarkus.io Mavenリポジトリ設定に適用されます。
つまり、例えば registry.quarkus.io Maven リポジトリに一致する Maven リポジトリミラーを適用した場合、 registry.quarkus.io Maven リポジトリを対応する Maven サーバーインスタンス (Nexus など) のミラーリポジトリグループに追加する必要があります。
デフォルトのレジストリMavenリポジトリ設定の上書き
デフォルトのレジストリ Maven リポジトリ設定は、実際にはユーザー settings.xml において、 registry.quarkus.io をその <id> の値として希望の <repository> 設定を追加するだけで、上書きすることができます。そのようなリポジトリ構成がユーザー settings.xml で見つかった場合、開発ツールは上述のデフォルトの registry.quarkus.io リポジトリ構成の代わりにそれを使用します。
Quarkus Extensionのレジストリクライアント設定
通常、Quarkusのコミュニティユーザーは、自分の環境でレジストリ関連の設定を行う必要はありません。 registry.quarkus.io にホストされているレジストリは、デフォルトですべてのQuarkus開発ツールで有効になっています。しかし、カスタムのレジストリクライアント設定が役立つ場面がいくつかあるかもしれません。例えば、ローカルレジストリキャッシュのアップデートポリシーの変更や、追加の（デフォルトではない）Quarkusエクステンションレジストリの設定などです。
レジストリクライアント設定の場所
Quarkus開発ツールを起動すると、以下の手順でレジストリクライアント設定ファイルの検索が行われます:
-
quarkus.tools.configシステムプロパティがチェックされ、存在すればその値がレジストリクライアント設定ファイルへのパスとして使用されます。 -
カレントディレクトリに
.quarkus/config.yamlファイルが存在するかどうかを確認し、ファイルが存在すれば、それを使用してレジストリクライアントが設定されます。 -
ユーザーのホームディレクトリに
~/.quarkus/config.yamlファイルが存在するかどうかを確認し、ファイルが存在する場合は、それを使用してレジストリクライアントを設定します。 -
上記のいずれの手順でも設定ファイルが見つからない場合は、デフォルトの registry.quarkus.io 設定が使用されます。
複数のレジストリーを設定
registry.quarkus.io はデフォルトのQuarkusコミュニティエクステンションレジストリですが、常に唯一のレジストリであることを意図しているわけではありません。他の組織が、独自のQuarkusエクステンションレジストリを作成し、独自の Quarkusプラットフォームや 個別の（プラットフォーム以外の）Quarkusエクステンションを提供すると便利だと考えるかもしれません。自分の環境でカスタムのQuarkusエクステンションレジストリを有効にしたい場合は、レジストリのクライアント設定ファイルに追加する必要があります。
レジストリクライアント設定ファイルは、レジストリのリストを含むシンプルなYAMLファイルです。例えば以下のようになります:
registries:
- registry.acme.org
- registry.quarkus.io上記の設定では、 registry.acme.org と registry.quarkus.io の2つのレジストリが有効になります。レジストリの順序は実際に重要です。Quarkusの開発ツールがユーザーの要求に応じてエクステンションを探す場合、レジストリは設定された順、つまりリストの上から下に向かって検索されます。最初に見つかったエクステンションやプラットフォームは、ユーザーが好むものとして扱われます。
registry.quarkus.io はデフォルトのレジストリで、通常は明示的に設定する必要はありませんが、ユーザーがカスタムレジストリリストを提供し、その中に registry.quarkus.io が含まれていない場合は、 registry.quarkus.io は有効になりません。
|
たとえば、以下は、デフォルトの registry.quarkus.ioレジストリをカスタムのものに置き換えるレジストリクライアント設定です:
registries:
- registry.acme.orgエクステンションカタログのオファリングへの制限
| この機能は Quarkus 3.26.0 で導入され、今後のバージョンで進化していく予定です。 |
エクステンションオファリングメタデータ に記載されているように、エクステンションは、専門チームまたは組織によって提供およびサポートされる1つ以上のオファリングに関連付けられる場合があります。
Quarkus エクステンションレジストリークライアントは、レジストリーが提供するエクステンションカタログを特定のオファリングに制限するように設定できます。例えば、registry.acme.org が複数のオファリングに関連付けられたエクステンションを提供していると仮定した場合、以下の設定では、acme-cloud オファリングに関連付けられたエクステンションのみがレジストリークライアントによって返されます。
registries:
- registry.acme.org:
offering: acme-cloud (1)
- registry.quarkus.io| 1 | registry.acme.org によって提供されるエクステンションカタログを、acme-cloud オファリングを構成するエクステンションに制限します。 |
| オファリングが設定されていない場合、レジストリーから返されるエクステンションの完全なカタログがユーザーに提供されます。 |
現時点では、レジストリーごとに1つのオファリングのみを設定できます。
レジストリキャッシュ更新ポリシーの調整
通常、Quarkusのエクステンションレジストリは、Mavenスナップショットリポジトリとして実装されます。レジストリからMavenアーティファクトとして解決されたプラットフォームおよびエクステンションカタログは、ユーザーのローカルMavenリポジトリにキャッシュされます。プラットフォームとエクステンションカタログは、実際には、レジストリクライアントによって定期的に更新がチェックされる SNAPSHOT アーティファクトです。更新をチェックするレジストリのデフォルトの間隔は、Maven の updatePolicy snapshot repositories のデフォルト値と一致しており、 daily となっています。このデフォルトは、例えばレジストリ設定で上書きすることができます:
registries:
- registry.acme.org:
update-policy: "always"
- registry.quarkus.io上記の例では、 registry.acme.org レジストリは、カタログ要求ごとにカタログの更新がチェックされ、 registry.quarkus.io レジストリは、1日1回（その日の最初のカタログ要求時）にカタログの更新がチェックされます。
以下がレジストリの update-policy の値の選択肢の完全なリストです:
-
always- カタログ要求のたびに更新情報を確認する。
-
daily（デフォルト） - 1日1回、最初のカタログ要求時に、カタログの更新をチェック。
-
interval:X (Xは整数、分単位) - 分単位のカスタム間隔。
-
never - カタログを一度解決すると、更新をチェックしない。
設定でレジストリを無効化
設定ファイルに記載されているすべてのレジストリは、デフォルトで有効になっています。その設定に enabled: false を追加することで、レジストリを無効にすることができます。例えば、以下のようになります:
registries:
- registry.acme.org
- registry.quarkus.io:
enabled: false上記の設定では、 registry.acme.org のみが有効です。上記の設定は、以下と同等です:
registries:
- registry.acme.orgデバッグモードの有効化
レジストリクライアントは、デフォルトでは多くの情報をログ出力していません。しかし、舞台裏でMavenリポジトリから様々なアーティファクトを解決します。アーティファクトの転送やその他のデバッグ関連のメッセージをログに記録したい場合は、設定でデバッグモードを有効にすることができます。例えば、以下のようになります:
debug: true
registries:
- registry.acme.org
- registry.quarkus.ioレジストリのURLを上書きする
レジストリのURLが変更される場合がありますが、IDは同じである必要があります。（Mavenの座標が照会されるため）レジストリのURLを上書きするには、次のように追加します:
registries:
- registry.acme.org
- registry.quarkus.io:
maven:
repository:
url: https://internal.registry.acme.org/mavenNexusリポジトリプロキシとして登録する方法
QuarkusエクステンションレジストリをNexusリポジトリプロキシとして登録できます。これらの操作を行うには、管理者である必要があります。
Nexus 2.x
いくつかのオプションを設定する必要があります:
-
Repository PolicyをSnapshotに設定。 -
Download Remote Indexesを無効化。 -
Allow File Browsingを無効化。 -
Include in Searchの無効化。
以下は、その例です:
Nexus 3.x
-
maven2(proxy)リポジトリの作成 -
Version PolicyをSnapshotに設定 -
Remote StorageURLを設定します。https://registry.quarkus.io/maven
環境変数
レジストリークライアントを使用するアプリケーションは、環境変数を使用して設定できます。
QUARKUS_REGISTRIES 環境変数を使用すると、有効にするレジストリーをコンマ区切りのレジストリー ID のリストとして指定できます。例えば
QUARKUS_REGISTRIES=registry.acme.org,registry.quarkus.io
これだけで、デフォルト設定を使用して2つのレジストリーからエクステンションカタログをプルするようにレジストリークライアントを初期化するのに十分です。
特定のレジストリーオプションは、それぞれの環境変数で初期化できます。そのような各オプションには、次の環境変数プレフィックスが付与されます。
QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_
ここで、<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID> は、各文字が大文字に変換され、． が _ に置き換えられたレジストリー ID です。例えば、REGISTRY_ACME_ORG となります。
以下に、このアプローチに従って設定できる様々なオプションの例を示します。
リポジトリー URL
QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_REPO_URL=<REPO_URL>
例:
QUARKUS_REGISTRY_REGISTRY_ACME_ORG_REPO_URL=https://internal.registry.acme.org/maven
更新ポリシー
QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_UPDATE_POLICY=<UPDATE_POLICY>
例:
QUARKUS_REGISTRY_REGISTRY_ACME_ORG_UPDATE_POLICY=always
オファリング
QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_OFFERING=<OFFERING>
例:
QUARKUS_REGISTRY_REGISTRY_ACME_ORG_OFFERING=acme-magic
推奨ストリーム元
プラットフォームごとに許容される最も古いストリーム値を設定します。設定された値よりも古いストリームはクライアントによって無視されます。
QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_RECOMMEND_STREAMS_FROM_<UPPERCASED_AND_UNDERSCORED_PLATFORM_KEY>=<STREAM_ID>
ここで、UPPERCASED_AND_UNDERSCORED_PLATFORM_KEY は、各文字が大文字に変換され、． が _ に置き換えられたプラットフォームキーです。例えば、IO_QUARKUS_PLATFORM となります。
例:
QUARKUS_REGISTRY_REGISTRY_ACME_ORG_RECOMMEND_STREAMS_FROM_IO_QUARKUS_PLATFORM=3.27
