28/2/24, 11:15 Kubernetes Client - Quarkus

The English version of quarkus.io is the official

project site. Translated sites are community
supported on a best-effort basis.

 volver al índice 3.7.3 - Latest 

KUBERNETES
CLIENT
Quarkus includes the kubernetes-client
extension which enables the use of the Fabric8
Kubernetes Client in native mode while also
making it easier to work with.

Having a Kubernetes Client extension in

Quarkus is very useful in order to unlock the
power of Kubernetes Operators. Kubernetes
Operators are quickly emerging as a new class
of Cloud Native applications. These applications
essentially watch the Kubernetes API and react
to changes on various resources and can be
used to manage the lifecycle of all kinds of
complex systems like databases, messaging
systems and much more. Being able to write
such operators in Java with the very low
footprint that native images provide is a great
match.

Configuración
Once you have your Quarkus project configured
you can add the kubernetes-client
extension to your project by running the
following command in your project base
directory.
https://es.quarkus.io/guides/kubernetes-client.html 1/21
28/2/24, 11:15 Kubernetes Client - Quarkus

CLI Maven

Gradle

quarkus extension add 

kubernetes-client

Esto añadirá lo siguiente a su archivo de

construcción:

pom.xml build.gradle

<dependency> 
<groupId>io.quarkus</groupId>
<artifactId>quarkus-
kubernetes-client</artifactId>
</dependency>

Uso
Quarkus configures a Bean of type
KubernetesClient which can be injected into
application code using the well known CDI
methods. This client can be configured using
various properties as can be seen in the
following example:

quarkus.kubernetes- 
client.trust-certs=false
quarkus.kubernetes-
client.namespace=default

Note that the full list of properties is available in

the Dev Services section of the configuration
reference.

In dev mode and when running tests, Dev

Services for Kubernetes automatically starts a
Kubernetes API server.

Customizing and overriding

https://es.quarkus.io/guides/kubernetes-client.html 2/21
28/2/24, 11:15 Kubernetes Client - Quarkus

Quarkus provides multiple integration points for

influencing the Kubernetes Client provided as a
CDI bean.

Kubernetes Client Config customization

The first integration point is the use of the

io.quarkus.kubernetes.client.Kubernet
esConfigCustomizer interface. When such a
bean exists, it allows for arbitrary
customizations of the
io.fabric8.kubernetes.client.Config
created by Quarkus (which takes into account
the quarkus.kubernetes-client.*
properties).

Alternatively, application code can override the

io.fabric8.kubernetes.client.Config or
even the
io.fabric8.kubernetes.client.Kubernet
esClient bean (which are normally provided
by the extension) by simply declaring custom
versions of those beans.

An example of this can be seen in the following

snippet:

@Singleton 
public class
KubernetesClientProducer {

@Produces
public KubernetesClient
kubernetesClient() {
// here you would create a
custom client
return new
DefaultKubernetesClient();
}
}

Kubernetes Client ObjectMapper

customization

https://es.quarkus.io/guides/kubernetes-client.html 3/21
28/2/24, 11:15 Kubernetes Client - Quarkus

The Fabric8 Kubernetes Client uses its own

ObjectMapper instance for serialization and
deserialization of Kubernetes resources. This
mapper is provided to the client through a
KubernetesSerialization instance that’s
injected into the KubernetesClient bean.

If for some reason you must customize the

default ObjectMapper bean provided by this
extension and used by the Kubernetes Client,
you can do so by declaring a bean that
implements the
KubernetesClientObjectMapperCustomize
r interface.

The following code snippet contains an example

of a
KubernetesClientObjectMapperCustomize
r to set the ObjectMapper locale:

@Singleton 
public static class Customizer
implements
KubernetesClientObjectMapperCustom
izer {
@Override
public void
customize(ObjectMapper
objectMapper) {

objectMapper.setLocale(Locale.ROOT
);
}
}

Furthermore, if you must replace the default

ObjectMapper bean used by the Kubernetes
Client that the extension creates automatically,
you can do so by declaring a bean of type
@KubernetesClientObjectMapper. The
following code snippet shows how you can
declare this bean:

@Singleton 
public class

https://es.quarkus.io/guides/kubernetes-client.html 4/21
28/2/24, 11:15 Kubernetes Client - Quarkus

KubernetesObjectMapperProducer {
@KubernetesClientObjectMapper
@Singleton
@Produces
public ObjectMapper
kubernetesClientObjectMapper() {
return new ObjectMapper();
}
}

The static
io.fabric8.kubernetes.client.utils.Serialization
utils class is deprecated and should not be used. Access to
 Serialization.jsonMapper() should be replaced by the
usage of @KubernetesClientObjectMapperCustomizer`
declared beans.

Probando
To make testing against a mock Kubernetes API
extremely simple, Quarkus provides the
WithKubernetesTestServer annotation
which automatically launches a mock of the
Kubernetes API server and sets the proper
environment variables needed so that the
Kubernetes Client configures itself to use said
mock. Tests can inject the mock server and set it
up in any way necessary for the particular
testing using the @KubernetesTestServer
annotation.

Let’s assume we have a REST endpoint defined

like so:

@Path("/pod") 
public class Pods {

private final KubernetesClient

kubernetesClient;

public Pods(KubernetesClient
kubernetesClient) {
this.kubernetesClient =
kubernetesClient;
https://es.quarkus.io/guides/kubernetes-client.html 5/21
28/2/24, 11:15 Kubernetes Client - Quarkus

@GET
@Path("/{namespace}")
public List<Pod> pods(String
namespace) {
return
kubernetesClient.pods().inNamespac
e(namespace).list().getItems();
}
}

We could write a test for this endpoint very

easily like so:

// you can even configure 

aspects like crud, https and port
on this annotation
@WithKubernetesTestServer
@QuarkusTest
public class KubernetesClientTest
{

@KubernetesTestServer
KubernetesServer mockServer;
@Inject
KubernetesClient client;

@BeforeEach
public void before() {
final Pod pod1 = new
PodBuilder().withNewMetadata().wit
hName("pod1").withNamespace("test"
).and().build();
final Pod pod2 = new
PodBuilder().withNewMetadata().wit
hName("pod2").withNamespace("test"
).and().build();

// Set up Kubernetes so
that our "pretend" pods are
created

client.pods().resource(pod1).creat
e();

client.pods().resource(pod2).creat

https://es.quarkus.io/guides/kubernetes-client.html 6/21
28/2/24, 11:15 Kubernetes Client - Quarkus

e();
}

@Test
public void
testInteractionWithAPIServer() {

RestAssured.when().get("/pod/test"
).then()
.body("size()",
is(2));
}

Note that to take advantage of these features,

the quarkus-test-kubernetes-client
dependency needs to be added, for example
like so:

pom.xml build.gradle

<dependency> 
<groupId>io.quarkus</groupId>
<artifactId>quarkus-test-
kubernetes-client</artifactId>
<scope>test</scope>
</dependency>

By default, the mock server will be in CRUD

mode, so you have to use the client to build
your state before your application can retrieve
it, but you can also set it up in non-CRUD mode
and mock all HTTP requests made to
Kubernetes:

// you can even configure 

aspects like crud, https and port
on this annotation
@WithKubernetesTestServer(crud =
false)
@QuarkusTest
public class KubernetesClientTest
{

https://es.quarkus.io/guides/kubernetes-client.html 7/21
28/2/24, 11:15 Kubernetes Client - Quarkus

@KubernetesTestServer
KubernetesServer mockServer;

@BeforeEach
public void before() {
final Pod pod1 = new
PodBuilder().withNewMetadata().wit
hName("pod1").withNamespace("test"
).and().build();
final Pod pod2 = new
PodBuilder().withNewMetadata().wit
hName("pod2").withNamespace("test"
).and().build();

// Mock any HTTP request

to Kubernetes pods so that our
pods are returned

mockServer.expect().get().withPath
("/api/v1/namespaces/test/pods")
.andReturn(200,
new
PodListBuilder().withNewMetadata()
.withResourceVersion("1").endMetad
ata().withItems(pod1, pod2)

.build())
.always();
}

@Test
public void
testInteractionWithAPIServer() {

RestAssured.when().get("/pod/test"
).then()
.body("size()",
is(2));
}

You can also use the setup attribute on the

@WithKubernetesTestServer annotation to
provide a class that will configure the
KubernetesServer instance:

https://es.quarkus.io/guides/kubernetes-client.html 8/21
28/2/24, 11:15 Kubernetes Client - Quarkus

@WithKubernetesTestServer(setu 
p = MyTest.Setup.class)
@QuarkusTest
public class MyTest {

public static class Setup

implements
Consumer<KubernetesServer> {

@Override
public void
accept(KubernetesServer server) {

server.expect().get().withPath("/a
pi/v1/namespaces/test/pods")
.andReturn(200, new
PodList()).always();
}
}

// tests
}

Alternately, you can create an extension of the

KubernetesServerTestResource class to
ensure all your @QuarkusTest enabled test
classes share the same mock server setup via
the QuarkusTestResource annotation:

public class 
CustomKubernetesMockServerTestReso
urce extends
KubernetesServerTestResource {

@Override
protected void
configureServer() {
super.configureServer();

server.expect().get().withPath("/a
pi/v1/namespaces/test/pods")
.andReturn(200, new
PodList()).always();
}
}

https://es.quarkus.io/guides/kubernetes-client.html 9/21
28/2/24, 11:15 Kubernetes Client - Quarkus

and use this in your other test classes as follows:

@QuarkusTestResource(CustomKub 
ernetesMockServerTestResource.clas
s)
@QuarkusTest
public class KubernetesClientTest
{

//tests will now use the

configured server...
}

Note on implementing
or extending generic
types
Due to the restrictions imposed by GraalVM,
extra care needs to be taken when
implementing or extending generic types
provided by the client if the application is
intended to work in native mode. Essentially
every implementation or extension of generic
classes such as Watcher, ResourceHandler or
CustomResource needs to specify their
associated Kubernetes model class (or, in the
case of CustomResource, regular Java types) at
class definition time. To better understand this,
suppose we want to watch for changes to
Kubernetes Pod resources. There are a couple
ways to write such a Watcher that are
guaranteed to work in native:

client.pods().watch(new 
Watcher<Pod>() {
@Override
public void
eventReceived(Action action, Pod
pod) {
// do something
}

https://es.quarkus.io/guides/kubernetes-client.html 10/21
28/2/24, 11:15 Kubernetes Client - Quarkus

@Override
public void
onClose(KubernetesClientException
e) {
// do something
}
});

or

public class 
PodResourceWatcher implements
Watcher<Pod> {
@Override
public void
eventReceived(Action action, Pod
pod) {
// do something
}

@Override
public void
onClose(KubernetesClientException
e) {
// do something
}
}

...

client.pods().watch(new
PodResourceWatcher());

Note that defining the generic type via a class

hierarchy similar to the following example will
also work correctly:

public abstract class 

MyWatcher<S> implements Watcher<S>
{
}

...

https://es.quarkus.io/guides/kubernetes-client.html 11/21
28/2/24, 11:15 Kubernetes Client - Quarkus

client.pods().watch(new
MyWatcher<Pod>() {
@Override
public void
eventReceived(Action action, Pod
pod) {
// do something
}
});

The following example will

not work in native mode
because the generic type of
watcher cannot be
determined by looking at the
 class and method definitions
thus making Quarkus unable
to properly determine the
Kubernetes model class for
which reflection registration
is needed:

public class ResourceWatcher<T 

extends HasMetadata> implements
Watcher<T> {
@Override
public void
eventReceived(Action action, T
resource) {
// do something
}

@Override
public void
onClose(KubernetesClientException
e) {
// do something
}
}

client.pods().watch(new
ResourceWatcher<Pod>());

https://es.quarkus.io/guides/kubernetes-client.html 12/21
28/2/24, 11:15 Kubernetes Client - Quarkus

Note on using Elliptic

Curve keys
Please note that if you would like to use Elliptic
Curve keys with Kubernetes Client then adding a
BouncyCastle PKIX dependency is required:

pom.xml build.gradle

<dependency> 

<groupId>org.bouncycastle</groupId
>
<artifactId>bcpkix-
jdk18on</artifactId>
</dependency>

Note that internally an

org.bouncycastle.jce.provider.BouncyC
astleProvider provider will be registered if it
has not already been registered.

You can have this provider registered as

described in the BouncyCastle or BouncyCastle
FIPS sections.

Access to the
Kubernetes API
In many cases in order to access the Kubernetes
API server a ServiceAccount, Role and
RoleBinding will be necessary. An example
that allows listing all pods could look something
like this:

--- 
apiVersion: v1
kind: ServiceAccount
metadata:
name: <applicationName>
namespace: <namespace>
---
https://es.quarkus.io/guides/kubernetes-client.html 13/21
28/2/24, 11:15 Kubernetes Client - Quarkus

apiVersion:
rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: <applicationName>
namespace: <namespace>
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["list"]
---
apiVersion:
rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: <applicationName>
namespace: <namespace>
roleRef:
kind: Role
name: <applicationName>
apiGroup:
rbac.authorization.k8s.io
subjects:
- kind: ServiceAccount
name: <applicationName>
namespace: <namespace>

Replace <applicationName> and

<namespace> with your values. Have a look at
Configure Service Accounts for Pods to get
further information.

OpenShift Client
If the targeted Kubernetes cluster is an
OpenShift cluster, it is possible to access it
through the openshift-client extension, in a
similar way. This leverages the dedicated fabric8
openshift client, and provides access to
OpenShift proprietary objects (e.g. Route,
ProjectRequest, BuildConfig …​)

Note that the configuration properties are

shared with the kubernetes-client

https://es.quarkus.io/guides/kubernetes-client.html 14/21
28/2/24, 11:15 Kubernetes Client - Quarkus

extension. In particular, they have the same

quarkus.kubernetes-client prefix.
Add the extension with:

CLI Maven

Gradle

quarkus extension add 

openshift-client

Note that openshift-client extension has a

dependency on the kubernetes-client
extension.

To use the client, inject an OpenShiftClient

instead of the KubernetesClient:

@Inject 
private OpenShiftClient
openshiftClient;

If you need to override the default

OpenShiftClient, provide a producer such as:

@Singleton 
public class
OpenShiftClientProducer {

@Produces
public OpenShiftClient
openshiftClient() {
// here you would create a
custom client
return new
DefaultOpenShiftClient();
}
}

Mock support is also provided in a similar

fashion:


https://es.quarkus.io/guides/kubernetes-client.html 15/21
28/2/24, 11:15 Kubernetes Client - Quarkus

@QuarkusTestResource(OpenShiftMock
ServerTestResource.class)
@QuarkusTest
public class OpenShiftClientTest {

@MockServer
private OpenShiftMockServer
mockServer;
...

Or by using the @WithOpenShiftTestServer

similar to the @WithKubernetesTestServer
explained in the previous section:

@WithOpenShiftTestServer 
@QuarkusTest
public class OpenShiftClientTest {

@OpenShiftTestServer
private OpenShiftServer
mockOpenShiftServer;
...

To use this feature, you have to add a

dependency on quarkus-test-openshift-
client:

pom.xml build.gradle

<dependency> 
<groupId>io.quarkus</groupId>
<artifactId>quarkus-test-
openshift-client</artifactId>
<scope>test</scope>
</dependency>

Referencia de
configuración
 Configuration property fixed at build time - All
other configuration properties are overridable
at runtime
https://es.quarkus.io/guides/kubernetes-client.html 16/21
28/2/24, 11:15 Kubernetes Client - Quarkus

FILTER CONFIGURATION

Configuration property

 quarkus.kubernetes-client.trust-certs
Whether the client should trust a self-signed certific
 Show more

 quarkus.kubernetes-client.api-server-url
URL of the Kubernetes API server
 Show more

 quarkus.kubernetes-client.namespace
Default namespace to use
 Show more

 quarkus.kubernetes-client.ca-cert-file
CA certificate file
 Show more

 quarkus.kubernetes-client.ca-cert-data
CA certificate data
 Show more

 quarkus.kubernetes-client.client-cert-fi
Client certificate file
 Show more

 quarkus.kubernetes-client.client-cert-da
Client certificate data
 Show more

 quarkus.kubernetes-client.client-key-fil
Client key file
 Show more

 quarkus.kubernetes-client.client-key-dat
Client key data
 Show more

 quarkus.kubernetes-client.client-key-alg
Client key algorithm
 Show more

 quarkus.kubernetes-client.client-key-pas
Client key passphrase
 Show more

 quarkus.kubernetes-client.username
Kubernetes auth username
 Show more

 quarkus.kubernetes-client.password
Kubernetes auth password
 Show more

 quarkus.kubernetes-client.token
Kubernetes oauth token
 Show more

 quarkus.kubernetes-client.watch-reconnec
Watch reconnect interval
 Show more
https://es.quarkus.io/guides/kubernetes-client.html 17/21
28/2/24, 11:15 Kubernetes Client - Quarkus

 quarkus.kubernetes-client.watch-reconnec
Maximum reconnect attempts in case of watch failu
 Show more

 quarkus.kubernetes-client.connection-tim
Maximum amount of time to wait for a connection w
 Show more

 quarkus.kubernetes-client.request-timeou
Maximum amount of time to wait for a request to th
 Show more

 quarkus.kubernetes-client.request-retry-
Maximum number of retry attempts for API request
 Show more

 quarkus.kubernetes-client.request-retry-
Time interval between retry attempts for API reques
 Show more

 quarkus.kubernetes-client.http-proxy
HTTP proxy used to access the Kubernetes API serve
 Show more

 quarkus.kubernetes-client.https-proxy
HTTPS proxy used to access the Kubernetes API serv
 Show more

 quarkus.kubernetes-client.proxy-username
Proxy username
 Show more

 quarkus.kubernetes-client.proxy-password
Proxy password
 Show more

 quarkus.kubernetes-client.no-proxy
IP addresses or hosts to exclude from proxying
 Show more

 quarkus.kubernetes-client.generate-rbac
Enable the generation of the RBAC manifests. If ena
 Show more

Dev Services

 quarkus.kubernetes-client.devservices.en
If Dev Services for Kubernetes should be used. (defa
 Show more

 quarkus.kubernetes-client.devservices.ap
The kubernetes api server version to use. If not set,
 Show more

 quarkus.kubernetes-client.devservices.fl
The flavor to use (kind, k3s or api-only). Default to a
 Show more

 quarkus.kubernetes-client.devservices.ov
By default, if a kubeconfig is found, Dev Services for
 Show more
https://es.quarkus.io/guides/kubernetes-client.html 18/21
28/2/24, 11:15 Kubernetes Client - Quarkus

 quarkus.kubernetes-client.devservices.sh
Indicates if the Kubernetes cluster managed by Qua
 Show more

 quarkus.kubernetes-client.devservices.se
The value of the quarkus-dev-service-kuberne
 Show more

 quarkus.kubernetes-client.devservices.co
Environment variables that are passed to the contai
 Show more

About the Duration format

To write duration values, use
the standard
java.time.Duration
format. See the
Duration#parse() Java API
documentation for more
information.

You can also use a simplified

format, starting with a
number:

If the value is only a

number, it represents
time in seconds.
 If the value is a number
followed by ms, it
represents time in
milliseconds.

In other cases, the simplified

format is translated to the
java.time.Duration
format for parsing:

If the value is a number

followed by h, m, or s, it
is prefixed with PT.
If the value is a number
followed by d, it is
prefixed with P.

https://es.quarkus.io/guides/kubernetes-client.html 19/21
28/2/24, 11:15 Kubernetes Client - Quarkus

Configuración
Uso
Customizing and overriding
Probando
Note on implementing or
extending generic types
Note on using Elliptic Curve keys
Access to the Kubernetes API
OpenShift Client
Referencia de configuración

QuarkusNavigation Follow UsGet Languages Quarkus

is Help is
Home Twitter English
open. made
All About Mastodon Support
Português(Brasileiro) of
dependencies
Blog Facebook GuíasEspañol community
of FAQ 简体中文 projects
Podcast Linkedin
this
Primeros Eclipse
project Events Youtube 日本語
pasos Vert.x
are Boletín de GitHub
available
noticias Stack SmallRye
under Overflow Hibernate
Hoja de ruta
the Discussions Netty
ApacheSecurity policy
Development RESTEasy
SoftwareUso mailing
License Apache
Brand list
2.0 Camel
or
Eclipse
compatible
MicroProfile
license.

https://es.quarkus.io/guides/kubernetes-client.html 20/21
28/2/24, 11:15 Kubernetes Client - Quarkus

And
This many
website more...
was
built
with
Jekyll,
is
hosted
on
GitHub
Pages
and
is
completely
open
source.
If
you
want
to
make
it
better,
fork
the
website
and
show
us
what
you’ve
got.

 CC by 3.0 |
Sponsored by
Privacy Policy

https://es.quarkus.io/guides/kubernetes-client.html 21/21