Configuración de Kubernetes
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.
quarkus extension add 'kubernetes-config'
./mvnw quarkus:add-extension -Dextensions='kubernetes-config'
./gradlew addExtension --extensions='kubernetes-config'
Esto añadirá lo siguiente a su archivo de construcción:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-kubernetes-config</artifactId>
</dependency>
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:
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
Type |
Default |
|
---|---|---|
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 |