Kubernetes Config

Quarkus包含`kubernetes-config`扩展，允许开发人员使用Kubernetes ConfigMaps和 Secrets作为配置源，而无需将它们安装到运行Quarkus应用程序的 Pod中，或对他们的Kubernetes`Deployment`（或OpenShift`DeploymentConfig`）进行任何其他修改。

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).

Configuration

一旦您配置好Quarkus项目，您就可以在项目基本目录中运行以下命令，来添加`kubernetes-config`扩展。

Once you have your Quarkus project configured you can add the kubernetes-config extension by running the following command in your project base directory.

Unresolved directive in kubernetes-config.adoc - include::{includes}/devtools/extension-add.adoc[]

这会将以下内容添加到构建文件中：

This will add the following to your build file:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-kubernetes-config</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-kubernetes-config")

Usage

该扩展是通过使用Kubernetes Client从Kubernetes API服务器直接读取ConfigMap和Secret来工作的。

The extension works by reading ConfigMaps and Secrets directly from the Kubernetes API server using the Kubernetes Client.

该扩展将以下ConfigMap和Secret类型识别为输入源：

The extension understands the following types of ConfigMaps and Secrets as input sources:

ConfigMaps and Secrets that contain literal data (see this for an example on how to create one)
ConfigMaps and Secrets created from files named application.properties, application.yaml or application.yml (see this for an example on how to create one).

该扩展在默认情况下处于禁用状态，以防止应用程序在不处于Kubernetes环境中运行时进行API调用。要启用它，请设置`quarkus.kubernetes-config.enabled=true`（例如使用特定的profile）。

The extension is disabled by default in order to prevent the application for making API calls when it is not running in a Kubernetes environment. To enable it, set quarkus.kubernetes-config.enabled=true (for example using a specific profile).

`quarkus.kubernetes-config.config-maps`和`quarkus.kubernetes-config.secrets`的值决定了哪些ConfigMap和/或Secret将用作配置源。请记住，这些ConfigMap和Secret必须与正在运行的应用程序处于相同的Kubernetes`Namespace`中。如果要将它们放在不同的名称空间中，则必须将`quarkus.kubernetes-config.namespace`设置为正确的值。

The values of quarkus.kubernetes-config.config-maps and quarkus.kubernetes-config.secrets determine which ConfigMaps and/or Secrets will be used as configuration sources. Keep in mind that these ConfigMaps and Secrets must be in the same Kubernetes Namespace as the running application. If they are to be found in a different namespace, then quarkus.kubernetes-config.namespace must be set to the proper value.

Priority of obtained properties

从ConfigMap和Secret获得的属性具有比`application.properties`（或YAML等价物）中找到的同名任何属性更高的优先级（即它们覆盖它们），但它们的优先级低于通过环境变量或Java系统属性设置的属性的优先级。

The properties obtained from the ConfigMaps and Secrets have a higher priority than (i.e. they override) any properties of the same name that are found in application.properties (or the YAML equivalents), but they have lower priority than properties set via Environment Variables or Java System Properties.

此外，当使用多个ConfigMap（或Secret）时，列表中后面定义的ConfigMap（或Secret）优先于列表中前面定义的ConfigMap。

Furthermore, when multiple ConfigMaps (or Secrets) are used, ConfigMaps (or Secrets) defined later in the list have a higher priority that ConfigMaps defined earlier in the list.

最后，当同时使用ConfigMap和Secret时，后者的优先级始终高于前者。

Finally, when both ConfigMaps and Secrets are used, the latter always a higher priority than the former.

Kubernetes Permissions

由于读取ConfigMap涉及与Kubernetes API服务器交互，因此当在集群上启用 RBAC时，用于运行应用程序的 ServiceAccount需要具有进行此类访问的适当权限。

Since reading ConfigMaps involves interacting with the Kubernetes API Server, when RBAC is enabled on the cluster, the ServiceAccount that is used to run the application needs to have the proper permissions for such access.

值得庆幸的是，当将`kubernetes-config`扩展与Kubernetes扩展一起使用时，将自动生成实现上述目的所需的所有必要的Kubernetes资源。

Thankfully, when using the kubernetes-config extension along with the Kubernetes extension, all the necessary Kubernetes resources to make that happen are automatically generated.

Secrets

默认情况下，Kubernetes扩展不会生成允许访问秘钥的必要资源。设置`quarkus.kubernetes-config.secrets.enabled=true`以生成必要的角色和相应的角色绑定。

By default, the Kubernetes extension doesn’t generate the necessary resources to allow accessing secrets. Set quarkus.kubernetes-config.secrets.enabled=true to generate the necessary role and corresponding role binding.

Example configuration

一个非常常见的用例是部署需要访问关系数据库的Quarkus应用程序，而该数据库本身已部署在Kubernetes上。使用`quarkus-kubernetes-config`扩展可以非常简单地处理此用例。

A very common use case is to deploy a Quarkus application that needs to access a relational database which has itself already been deployed on Kubernetes. Using the quarkus-kubernetes-config extension makes this use case very simple to handle.

让我们假设我们的Quarkus应用程序需要与PostgreSQL通信，并且当PostgreSQL部署在我们的Kubernetes集群上时，一个名为`postgresql`的`Secret`作为该部署的一部分被创建，并且包含以下条目：

Let’s assume that our Quarkus application needs to talk to PostgreSQL and that when PostgreSQL was deployed on our Kubernetes cluster, a Secret named postgresql was created as part of that deployment and contains the following entries:

database-name
database-user
database-password

使Quarkus使用这些条目连接数据库的一种可能方法是使用以下配置：

One possible way to make Quarkus use these entries to connect the database is to use the following configuration:

%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	Enable reading of secrets. Note the use of `%prod` profile as we only want this setting applied when the application is running in production.
2	Configure the name of the secret that will be used. This doesn’t need to be prefixed with the `%prod` profile as it won’t have any effect if secret reading is disabled.
3	Quarkus will substitute `${database-name}` with the value obtained from the entry with name `database-name` of the `postgres` Secret. `somehost` is the name of the Kubernetes `Service` that was created when PostgreSQL was deployed to Kubernetes.
4	Quarkus will substitute `${database-user}` with the value obtained from the entry with name `database-user` of the `postgres` Secret.
5	Quarkus will substitute `${database-password}` with the value obtained from the entry with name `database-password` of the `postgres` Secret.

上面的值允许应用程序完全忽略在生产中使用的实际数据库配置，同时也不妨碍在开发时使用应用程序。

The values above allow the application to be completely agnostic of the actual database configuration used in production while also not inhibiting the usability of the application at development time.

Alternatives

使用 @"13" 扩展是完全可选的，因为应用程序还可以通过其他方式进行配置以使用 ConfigMaps 或 Secrets。

The use of the quarkus-kubernetes-config extensions is completely optional as there are other ways an application can be configured to use ConfigMaps or Secrets.

一种常见的替代方法是在 Kubernetes @"14" 上将 ConfigMap 和 / Secret 的各个条目映射到环境变量 - 有关更详细的信息，请参见 @"16"。在 Quarkus 中实现此目的时，我们可以使用 @"15" 扩展（负责创建 Kubernetes 清单并包含以下配置），并对其进行如下配置：

One common alternative is to map each entry of the ConfigMap and / Secret to an environment variable on the Kubernetes Deployment - see this for more details. To achieve that in Quarkus, we could use the quarkus-kubernetes extension (which is responsible for creating Kubernetes manifests and include the following configuration) and configure it as so:

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}

上述配置的最终结果是将以下 @"17" 部分应用于生成的 @"18"：

The end result of the above configuration would be the following env part being applied the generated 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

有关更详细的信息，请参见 @"19"。

See this for more details.

Configuration Reference

@"20"

Unresolved directive in kubernetes-config.adoc - include::{generated-dir}/config/quarkus-kubernetes-config.adoc[]