Kubernetes Config
Quarkusには、 kubernetes-config エクステンションが含まれており、開発者は ConfigMaps と Secrets を Quarkusアプリケーションを実行している Pod にマウントしたり、Kubernetes Deployment (あるいは OpenShift DeploymentConfig)に何の変更もしなくても設定ソースとして使用することができます。
設定
Quarkusプロジェクトを設定したら、プロジェクトのベースディレクトリーで以下のコマンドを実行して、 kubernetes-config エクステンションを追加できます。
quarkus extension add kubernetes-config./mvnw quarkus:add-extension -Dextensions='kubernetes-config'./gradlew addExtension --extensions='kubernetes-config'これにより、 pom.xml に以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-kubernetes-config</artifactId>
</dependency>implementation("io.quarkus:quarkus-kubernetes-config")使用方法
このエクステンションは、Kubernet Kubernates クライアント を使用してKubernetes APIサーバーから直接ConfigMapsとSecretsを読み込むことで動作します。
エクステンションは、以下のタイプの ConfigMaps と Secrets を入力ソースとして理解します。
このエクステンションは、アプリケーションがKubernetes環境で実行されていないときにAPIコールを行うことを防ぐため、デフォルトでは無効になっています。有効にするには、 quarkus.kubernetes-config.enabled=true を設定してください（特定の プロファイルを使用するなど）。
quarkus.kubernetes-config.config-maps と quarkus.kubernetes-config.secrets の値は、どの ConfigMaps および/または Secrets を設定ソースとして使用するかを決定します。これらのConfigMapsとSecretsは、実行中のアプリケーションと同じKubernetes Namespace にある必要があることに留意してください。もしそれらが異なる名前空間にある場合は、 quarkus.kubernetes-config.namespace を適切な値に設定する必要があります。
取得したプロパティーの優先順位
ConfigMapsとSecretsから取得したプロパティーは、 application.properties (またはYAMLの等価物)にある同名のプロパティーよりも高い優先度を持っています(すなわち、それらは上書きされます)が、環境変数やJavaシステムプロパティーを介して設定されたプロパティーよりも優先度は低くなります。
さらに、複数のConfigMap(またはSecret)を使用している場合、後から定義されたConfigMap(またはSecret)は、先に定義されたConfigMap(またはSecret)よりも優先度が高くなります。
最後に、ConfigMapsとSecretsの両方を使用する場合、常に後者の方が前者よりも優先度が高くなります。
Kubernetesのパーミッション
ConfigMapsの読み込みにはKubernetes API Serverとのやりとりが含まれるため、クラスター上で RBAC が有効になっている場合、アプリケーションを実行するために使用される ServiceAccount に適切なアクセス権限が必要になります。
ありがたいことに、 Kubernetes エクステンションと一緒に kubernetes-config エクステンションを使うと、それを実現するために必要なKubernetesリソースがすべて自動的に生成されます。
Secrets
デフォルトでは、 Kubernetes エクステンションはSecretsにアクセスできるようにするために必要なリソースを生成しません。 quarkus.kubernetes-config.secrets.enabled=true を設定して、必要なロールと対応するロールバインディングを生成します。
設定例
非常に一般的なユースケースは、それ自体がすでにKubernetesにデプロイされているリレーショナルデータベースにアクセスする必要があるQuarkusアプリケーションをデプロイすることです。 quarkus-kubernetes-config エクステンションを使用することで、このユースケースを非常に簡単に扱うことができます。
ここでは、QuarkusアプリケーションがPostgreSQLと通信する必要があり、PostgreSQLがKubernetesクラスタにデプロイされたときに、そのデプロイの一部として postgresql という名前の Secret が作成され、以下のエントリが含まれていたと仮定します。
-
database-name -
database-user -
database-password
Quarkusがこれらのエントリーを使用してデータベースに接続する方法としては、以下のような設定が考えられます。
%prod.quarkus.kubernetes-config.secrets.enabled=true (1)
quarkus.kubernetes-config.secrets=postgresql (2)
%prod.quarkus.datasource.jdbc.url=postgresql://somehost:5432/${database-name} (3)
%prod.quarkus.datasource.username=${database-user} (4)
%prod.quarkus.datasource.password=${database-password} (5)| 1 | Secretsの読み取りを有効にします。アプリケーションが本番稼動しているときにのみこの設定を適用するため、 %prod プロファイルを使用していることに注意してください。 |
| 2 | 使用されるSecretsの名前を設定します。Secretsの読み取りが無効になっている場合は何の効果もありませんので、この名前の前に %prod プロファイルを付ける必要はありません。 |
| 3 | Quarkusは、 ${database-name} を postgres Secret の database-name という名前のエントリから取得した値で置き換えます。 somehost は、PostgreSQL を Kubernetes にデプロイした際に作成された Kubernetes の Service の名前です。 |
| 4 | Quarkusは、 ${database-user} を postgres Secret の database-user という名前のエントリから得た値で置き換えます。 |
| 5 | Quarkusは、 ${database-password} を postgres Secret の database-password という名前のエントリから得た値で置き換えます。 |
上記の値は、本番環境で使用されている実際のデータベース構成に完全に依存しないようにすると同時に、開発時のアプリケーションの使い勝手を阻害しないようにしています。
代替案
アプリケーションがConfigMapsやSecretsを使用するように設定する方法は他にもあるため、 quarkus-kubernetes-config エクステンションの使用は完全に任意です。
一般的な代替案としては、ConfigMapと/ Secretの各エントリをKubernetes Deployment の環境変数にマッピングする方法があります - 詳細は こちらを参照してください。Quarkusでこれを実現するには、 quarkus-kubernetes エクステンション（Kubernetesマニフェストの作成を担当し、以下の設定を含む）を使用し、以下のように設定します。
quarkus.kubernetes.env.secrets=postgresql
quarkus.kubernetes.env.mapping.database-name.from-secret=postgresql
quarkus.kubernetes.env.mapping.database-name.with-key=database-name
quarkus.kubernetes.env.mapping.database-user.from-secret=postgresql
quarkus.kubernetes.env.mapping.database-user.with-key=database-user
quarkus.kubernetes.env.mapping.database-password.from-secret=postgresql
quarkus.kubernetes.env.mapping.database-password.with-key=database-password
%prod.quarkus.datasource.jdbc.url=postgresql://somehost:5432/${database-name}
%prod.quarkus.datasource.username=${database-user}
%prod.quarkus.datasource.password=${database-password}上記の構成では、最終的に次のような env 部分が、生成された Deployment に適用されます。
env:
- name: DATABASE_NAME
valueFrom:
secretKeyRef:
key: database-name
name: postgresql
- name: DATABASE_USER
valueFrom:
secretKeyRef:
key: database-user
name: postgresql
- name: DATABASE_PASSWORD
valueFrom:
secretKeyRef:
key: database-password
name: postgresql詳しくは こちらをご覧ください。
設定リファレンス
ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能
型 |
デフォルト |
|
|---|---|---|
Whether configuration can be read from secrets. If set to Environment variable: Show more |
boolean |
|
The name of the role. Environment variable: Show more |
string |
|
The namespace of the role. Environment variable: Show more |
string |
|
Whether the role is cluster wide or not. By default, it’s not a cluster wide role. Environment variable: Show more |
boolean |
|
If the current role is meant to be generated or not. If not, it will only be used to generate the role binding resource. Environment variable: Show more |
boolean |
|
If set to true, the application will attempt to look up the configuration from the API server Environment variable: Show more |
boolean |
|
If set to true, the application will not start if any of the configured config sources cannot be located Environment variable: Show more |
boolean |
|
ConfigMaps to look for in the namespace that the Kubernetes Client has been configured for. ConfigMaps defined later in this list have a higher priority that ConfigMaps defined earlier in this list. Furthermore, any Secrets defined in Environment variable: Show more |
list of string |
|
Secrets to look for in the namespace that the Kubernetes Client has been configured for. If you use this, you probably want to enable Environment variable: Show more |
list of string |
|
Namespace to look for config maps and secrets. If this is not specified, then the namespace configured in the kubectl config context is used. If the value is specified and the namespace doesn’t exist, the application will fail to start. Environment variable: Show more |
string |
