The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Kubernetes Config

Quarkus includes the kubernetes-config extension which allows developers to use Kubernetes ConfigMaps and Secrets as a configuration source, without having to mount them into the Pod running the Quarkus application or make any other modifications to their Kubernetes Deployment (or OpenShift DeploymentConfig).

設定

Quarkusプロジェクトを設定したら、プロジェクトのベースディレクトリーで以下のコマンドを実行して、 kubernetes-config エクステンションを追加できます。

CLI
quarkus extension add 'kubernetes-config'
Maven
./mvnw quarkus:add-extension -Dextensions="kubernetes-config"
Gradle
./gradlew addExtension --extensions="kubernetes-config"

これにより、 pom.xml に以下が追加されます:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-kubernetes-config</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-kubernetes-config")

使用方法

このエクステンションは、Kubernet Kubernates クライアント を使用してKubernetes APIサーバーから直接ConfigMapsとSecretsを読み込むことで動作します。

エクステンションは、以下のタイプの ConfigMaps と Secrets を入力ソースとして理解します。

  • リテラルデータを含む ConfigMaps と Secrets (作成方法の例は こちら を参照)

  • ConfigMapsとSecretsは、 application.propertiesapplication.yaml 、または application.yml という名前のファイルから作成されます(作成方法の例は こちら を参照してください)。

このエクステンションは、アプリケーションがKubernetes環境で実行されていないときにAPIコールを行うことを防ぐため、デフォルトでは無効になっています。有効にするには、 quarkus.kubernetes-config.enabled=true を設定してください(特定の プロファイルを使用するなど)。

quarkus.kubernetes-config.config-mapsquarkus.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

詳しくは こちらをご覧ください。

設定リファレンス

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property

タイプ

デフォルト

Whether configuration can be read from secrets. If set to true, Kubernetes resources allowing access to secrets (role and role binding) will be generated.

Environment variable: QUARKUS_KUBERNETES_CONFIG_SECRETS_ENABLED

boolean

false

If set to true, the application will attempt to look up the configuration from the API server

Environment variable: QUARKUS_KUBERNETES_CONFIG_ENABLED

boolean

false

If set to true, the application will not start if any of the configured config sources cannot be located

Environment variable: QUARKUS_KUBERNETES_CONFIG_FAIL_ON_MISSING_CONFIG

boolean

true

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 secrets, will have higher priorities than all ConfigMaps.

Environment variable: QUARKUS_KUBERNETES_CONFIG_CONFIG_MAPS

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 quarkus.kubernetes-config.secrets.enabled. Secrets defined later in this list have a higher priority that ConfigMaps defined earlier in this list. Furthermore, these Secrets have a higher priorities than all ConfigMaps defined in configMaps.

Environment variable: QUARKUS_KUBERNETES_CONFIG_SECRETS

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

string