By Version

Configuración de Kubernetes

Configuración
Uso
- Prioridad de las propiedades obtenidas
- Permisos de Kubernetes
Ejemplo de configuración
- Alternativas
Referencia de configuración

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

Configuración

Una vez que tenga configurado su proyecto Quarkus, puede añadir la extensión kubernetes-config ejecutando el siguiente comando en el directorio base de su proyecto.

CLI

quarkus extension add 'kubernetes-config'

Maven

./mvnw quarkus:add-extension -Dextensions='kubernetes-config'

Gradle

./gradlew addExtension --extensions='kubernetes-config'

Esto añadirá lo siguiente a su archivo de construcción:

pom.xml

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

build.gradle

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

Uso

La extensión funciona leyendo ConfigMaps y Secretos directamente desde el servidor de la API de Kubernetes utilizando el Cliente Kubernetes.

La extensión entiende los siguientes tipos de ConfigMaps y Secretos como fuentes de entrada:

ConfigMaps y Secretos que contienen datos literales (vea esto para un ejemplo sobre cómo crear uno)
ConfigMaps y Secretos creados a partir de archivos denominados application.properties, application.yaml o application.yml (ver aquí un ejemplo de cómo crear uno).

La extensión está desactivada por defecto para evitar que la aplicación realice llamadas a la API cuando no se ejecuta en un entorno Kubernetes. Para habilitarla, configure quarkus.kubernetes-config.enabled=true (por ejemplo, utilizando un perfil específico).

Los valores de quarkus.kubernetes-config.config-maps y quarkus.kubernetes-config.secrets determinan qué ConfigMaps y/o Secretos se utilizarán como fuentes de configuración. Tenga en cuenta que estos ConfigMaps y Secretos deben estar en el mismo Kubernetes Namespace que la aplicación en ejecución. Si se encuentran en un espacio de nombres diferente, entonces quarkus.kubernetes-config.namespace debe establecerse en el valor adecuado.

Prioridad de las propiedades obtenidas

Las propiedades obtenidas a partir de los ConfigMaps y Secretos tienen mayor prioridad que (es decir, anulan) cualquier propiedad del mismo nombre que se encuentre en application.properties (o los equivalentes en YAML), pero tienen menor prioridad que las propiedades establecidas a través de Variables de Entorno o Propiedades del Sistema Java.

Además, cuando se utilizan varios ConfigMaps (o Secretos), los ConfigMaps (o Secretos) definidos más tarde en la lista tienen una mayor prioridad que los ConfigMaps definidos anteriormente en la lista.

Por último, cuando se utilizan tanto ConfigMaps como Secretos, estos últimos siempre tienen mayor prioridad que los primeros.

Permisos de Kubernetes

Dado que la lectura de ConfigMaps implica la interacción con el servidor de la API de Kubernetes, cuando el RBAC está habilitado en el clúster, la ServiceAccount que se utiliza para ejecutar la aplicación debe tener los permisos adecuados para dicho acceso.

Afortunadamente, cuando se utiliza la extensión kubernetes-config junto con la extensión Kubernetes, se generan automáticamente todos los recursos Kubernetes necesarios para que esto ocurra.

Secretos

Por defecto, la extensión de Kubernetes no genera los recursos necesarios para permitir el acceso a los secretos. Configure quarkus.kubernetes-config.secrets.enabled=true para generar el rol necesario y el correspondiente enlace de rol.

Ejemplo de configuración

Un caso de uso muy común es desplegar una aplicación de Quarkus que necesita acceder a una base de datos relacional que a su vez ya ha sido desplegada en Kubernetes. El uso de la extensión quarkus-kubernetes-config hace que este caso de uso sea muy sencillo de manejar.

Supongamos que nuestra aplicación Quarkus necesita hablar con PostgreSQL y que cuando PostgreSQL se desplegó en nuestro clúster Kubernetes, se creó un Secret llamado postgresql como parte de ese despliegue y contiene las siguientes entradas:

database-name
database-user
database-password

Una posible forma de hacer que Quarkus utilice estas entradas para conectar la base de datos es utilizar la siguiente configuración:

%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	Habilitar la lectura de secretos. Tenga en cuenta el uso del perfil `%prod` ya que sólo queremos que esta configuración se aplique cuando la aplicación se ejecute en producción.
2	Configure el nombre del secreto que se utilizará. No es necesario anteponer el perfil `%prod`, ya que no tendrá ningún efecto si la lectura del secreto está desactivada.
3	Quarkus sustituirá `${database-name}` por el valor obtenido de la entrada con nombre `database-name` del `postgres` Secret. `somehost` es el nombre del Kubernetes `Service` que se creó cuando se desplegó PostgreSQL en Kubernetes.
4	Quarkus sustituirá `${database-user}` por el valor obtenido de la entrada con nombre `database-user` del `postgres` Secret.
5	Quarkus sustituirá `${database-password}` por el valor obtenido de la entrada con nombre `database-password` del `postgres` Secret.

Los valores anteriores permiten que la aplicación sea completamente agnóstica con respecto a la configuración de la base de datos real utilizada en producción, al tiempo que no inhibe la usabilidad de la aplicación en tiempo de desarrollo.

Alternativas

El uso de las extensiones de quarkus-kubernetes-config es completamente opcional, ya que existen otras formas de configurar una aplicación para que utilice ConfigMaps o Secrets.

Una alternativa común es mapear cada entrada del ConfigMap y/o Secret a una variable de entorno en el Kubernetes Deployment - ver esto para más detalles. Para lograr eso en Quarkus, podríamos utilizar la extensión quarkus-kubernetes (que se encarga de crear manifiestos de Kubernetes e incluir la siguiente configuración) y configurarla así:

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}

El resultado final de la configuración anterior sería la siguiente env parte que se aplica el Deployment generado:

          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

Vea esto para más detalles.

Referencia de configuración

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.kubernetes-config.secrets.enabled` 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` Show more	boolean	`false`
`quarkus.kubernetes-config.secrets-role-config.name` The name of the role. Environment variable: `QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_NAME` Show more	string	`view-secrets`
`quarkus.kubernetes-config.secrets-role-config.namespace` The namespace of the role. Environment variable: `QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_NAMESPACE` Show more	string
`quarkus.kubernetes-config.secrets-role-config.cluster-wide` Whether the role is cluster wide or not. By default, it’s not a cluster wide role. Environment variable: `QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_CLUSTER_WIDE` Show more	boolean	`false`
`quarkus.kubernetes-config.secrets-role-config.generate` 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: `QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_GENERATE` Show more	boolean	`true`
`quarkus.kubernetes-config.enabled` If set to true, the application will attempt to look up the configuration from the API server Environment variable: `QUARKUS_KUBERNETES_CONFIG_ENABLED` Show more	boolean	`false`
`quarkus.kubernetes-config.fail-on-missing-config` 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` Show more	boolean	`true`
`quarkus.kubernetes-config.config-maps` 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` Show more	list of string
`quarkus.kubernetes-config.secrets` 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` Show more	list of string
`quarkus.kubernetes-config.namespace` 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` Show more	string

Configuration property

Type

Default

quarkus.kubernetes-config.secrets.enabled

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

quarkus.kubernetes-config.secrets-role-config.name

The name of the role.

Environment variable: QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_NAME

string

view-secrets

quarkus.kubernetes-config.secrets-role-config.namespace

The namespace of the role.

Environment variable: QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_NAMESPACE

string

quarkus.kubernetes-config.secrets-role-config.cluster-wide

Whether the role is cluster wide or not. By default, it’s not a cluster wide role.

Environment variable: QUARKUS_KUBERNETES_CONFIG_SECRETS_ROLE_CONFIG_CLUSTER_WIDE

boolean

false

quarkus.kubernetes-config.secrets-role-config.generate

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

boolean

true

quarkus.kubernetes-config.enabled

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

quarkus.kubernetes-config.fail-on-missing-config

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

quarkus.kubernetes-config.config-maps

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

quarkus.kubernetes-config.secrets

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

quarkus.kubernetes-config.namespace

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