////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Quarkus - Kubernetes Config

include::./attributes.adoc[]


Quarkus includes the `kubernetes-config` extension which allows developers to use Kubernetes https://cloud.google.com/kubernetes-engine/docs/concepts/configmap[ConfigMaps] and https://cloud.google.com/kubernetes-engine/docs/concepts/secret[Secrets] as a configuration source, without having to mount them into the https://kubernetes.io/docs/concepts/workloads/pods/pod/[Pod] running the Quarkus application.


== Configuration

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

[source,bash]
----
./mvnw quarkus:add-extension -Dextensions="kubernetes-config"
----

This will add the following to your `pom.xml`:

[source,xml]
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-kubernetes-config</artifactId>
</dependency>
----

== Usage

The extension works by reading ConfigMaps and Secrets directly from the Kubernetes API server using the link:kubernetes-client[Kubernetes Client].

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

* ConfigMaps and Secrets that contain literal data (see https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-configmaps-from-literal-values[this] for an example on how to create one)
* ConfigMaps and Secrets created from files named `application.properties`, `application.yaml` or `application.yml` (see https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-configmaps-from-files[this] for an example on how to create one).

You have to explicitly enable the retrieval of ConfigMaps and Secrets by setting `quarkus.kubernetes-config.enabled=true`.
The default is `false` in order to make it easy to test the application locally.

Afterwards, set the `quarkus.kubernetes-config.config-maps` property to configure which ConfigMaps should be used.
Set the `quarkus.kubernetes-config.secrets` property to configure which Secrets should be used.
To access ConfigMaps and Secrets from a specific namespace, you can set the `quarkus.kubernetes-config.namespace` property.

=== Priority of obtained properties

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.

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.

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

=== Kubernetes Permissions

Since reading ConfigMaps involves interacting with the Kubernetes API Server, when https://kubernetes.io/docs/reference/access-authn-authz/rbac/[RBAC] is enabled on the cluster, the https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/[ServiceAccount]
that is used to run the application needs to have the proper permissions for such access.

Thankfully, when using the `kubernetes-config` extension along with the link:deploying-to-kubernetes[Kubernetes] extension, all the necessary Kubernetes resources to make that happen are automatically generated.

==== Secrets

By default, the link:deploying-to-kubernetes[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.

== Configuration Reference

include::{generated-dir}/config/quarkus-kubernetes-config-kubernetes-config-source-config.adoc[opts=optional, leveloffset=+1]
