0
# Quarkus Kubernetes Client Extension
1
2
The Quarkus Kubernetes Client extension provides seamless integration with Kubernetes clusters through the Fabric8 Kubernetes Client. It enables developers to build cloud-native applications that interact with Kubernetes APIs, create operators, watch resources, and manage complex distributed systems with full CDI integration and native compilation support.
3
4
## Package Information
5
6
- **Package Name**: quarkus-kubernetes-client
7
- **Package Type**: maven
8
- **Group ID**: io.quarkus
9
- **Artifact ID**: quarkus-kubernetes-client
10
- **Language**: Java
11
- **Installation**: Add dependency to Maven pom.xml
12
- **Maven Dependency**:
13
```xml
14
<dependency>
15
<groupId>io.quarkus</groupId>
16
<artifactId>quarkus-kubernetes-client</artifactId>
17
</dependency>
18
```
19
20
## Core Imports
21
22
```java
23
import io.fabric8.kubernetes.client.KubernetesClient;
24
import io.fabric8.kubernetes.client.Config;
25
import io.quarkus.kubernetes.client.KubernetesConfigCustomizer;
26
import io.quarkus.kubernetes.client.KubernetesClientObjectMapperCustomizer;
27
import jakarta.inject.Inject;
28
```
29
30
## Basic Usage
31
32
```java
33
import io.fabric8.kubernetes.client.KubernetesClient;
34
import io.fabric8.kubernetes.client.Watcher;
35
import io.fabric8.kubernetes.client.WatcherException;
36
import io.fabric8.kubernetes.api.model.Pod;
37
import io.fabric8.kubernetes.api.model.PodList;
38
import io.fabric8.kubernetes.api.model.ConfigMapBuilder;
39
import jakarta.inject.Inject;
40
import jakarta.enterprise.context.ApplicationScoped;
41
42
@ApplicationScoped
43
public class KubernetesService {
44
45
@Inject
46
KubernetesClient kubernetesClient;
47
48
public void listPods() {
49
// List all pods in the default namespace
50
PodList pods = kubernetesClient.pods().list();
51
for (Pod pod : pods.getItems()) {
52
System.out.println("Pod: " + pod.getMetadata().getName());
53
}
54
}
55
56
public void createConfigMap() {
57
// Create a ConfigMap
58
kubernetesClient.configMaps()
59
.create(new ConfigMapBuilder()
60
.withNewMetadata()
61
.withName("my-config")
62
.withNamespace("default")
63
.endMetadata()
64
.addToData("key", "value")
65
.build());
66
}
67
68
public void watchPods() {
69
// Watch for pod changes
70
kubernetesClient.pods().watch(new Watcher<Pod>() {
71
@Override
72
public void eventReceived(Action action, Pod pod) {
73
System.out.println("Pod " + action + ": " + pod.getMetadata().getName());
74
}
75
76
@Override
77
public void onClose(WatcherException cause) {
78
// Handle close
79
}
80
});
81
}
82
}
83
```
84
85
## Architecture
86
87
The Quarkus Kubernetes Client extension bridges the Fabric8 Kubernetes Client with Quarkus's CDI container and native compilation capabilities:
88
89
- **CDI Integration**: Automatic injection of KubernetesClient beans with customizable configuration
90
- **Configuration Management**: Properties-based configuration with customization hooks
91
- **Serialization Layer**: Jackson ObjectMapper integration for Kubernetes resource handling
92
- **Build-time Processing**: SPI for extension developers to integrate at build time
93
- **Native Support**: GraalVM native image compatibility with reflection configuration
94
- **DevServices Integration**: Automatic test cluster setup for development
95
96
## Configuration
97
98
Configure the Kubernetes client using `application.properties`:
99
100
```properties
101
# Connection settings
102
quarkus.kubernetes-client.api-server-url=https://kubernetes.example.com:6443
103
# Deprecated: Use api-server-url instead
104
quarkus.kubernetes-client.master-url=https://kubernetes.example.com:6443
105
quarkus.kubernetes-client.namespace=my-namespace
106
quarkus.kubernetes-client.trust-certs=true
107
108
# Authentication
109
quarkus.kubernetes-client.token=${KUBERNETES_TOKEN}
110
quarkus.kubernetes-client.ca-cert-file=/path/to/ca.crt
111
quarkus.kubernetes-client.client-cert-file=/path/to/client.crt
112
quarkus.kubernetes-client.client-key-file=/path/to/client.key
113
114
# Timeouts and retries
115
quarkus.kubernetes-client.connection-timeout=PT10S
116
quarkus.kubernetes-client.request-timeout=PT30S
117
quarkus.kubernetes-client.request-retry-backoff-limit=5
118
quarkus.kubernetes-client.request-retry-backoff-interval=PT1S
119
120
# Watch settings
121
quarkus.kubernetes-client.watch-reconnect-interval=PT30S
122
quarkus.kubernetes-client.watch-reconnect-limit=10
123
124
# Proxy settings
125
quarkus.kubernetes-client.http-proxy=http://proxy.example.com:8080
126
quarkus.kubernetes-client.https-proxy=https://proxy.example.com:8443
127
quarkus.kubernetes-client.proxy-username=proxyuser
128
quarkus.kubernetes-client.proxy-password=proxypass
129
quarkus.kubernetes-client.no-proxy=localhost,127.0.0.1
130
131
# RBAC generation
132
quarkus.kubernetes-client.generate-rbac=true
133
134
# DevServices (for testing)
135
quarkus.kubernetes-client.devservices.enabled=true
136
quarkus.kubernetes-client.devservices.api-version=v1.28.0
137
quarkus.kubernetes-client.devservices.image-name=kindest/node:v1.28.0
138
quarkus.kubernetes-client.devservices.flavor=kind
139
quarkus.kubernetes-client.devservices.override-kubeconfig=false
140
quarkus.kubernetes-client.devservices.manifests=/path/to/manifest1.yaml,/path/to/manifest2.yaml
141
quarkus.kubernetes-client.devservices.shared=true
142
quarkus.kubernetes-client.devservices.service-name=kubernetes
143
quarkus.kubernetes-client.devservices.container-env.ENV_VAR=value
144
```
145
146
## Capabilities
147
148
### CDI Kubernetes Client Injection
149
150
Direct injection of fully configured KubernetesClient instances via CDI.
151
152
```java { .api }
153
@Inject
154
KubernetesClient kubernetesClient;
155
```
156
157
The KubernetesClient is produced by:
158
159
```java { .api }
160
@Singleton
161
public class KubernetesClientProducer {
162
@DefaultBean
163
@Singleton
164
@Produces
165
public KubernetesClient kubernetesClient(KubernetesSerialization kubernetesSerialization, Config config);
166
}
167
```
168
169
### Kubernetes Configuration Customization
170
171
Customize the Kubernetes client configuration by implementing the KubernetesConfigCustomizer interface.
172
173
```java { .api }
174
public interface KubernetesConfigCustomizer {
175
/**
176
* Customize the Kubernetes client configuration.
177
* Called during Config bean creation before the KubernetesClient is built.
178
*
179
* @param config the Config instance to customize
180
*/
181
void customize(Config config);
182
}
183
```
184
185
**Usage Example:**
186
187
```java
188
import io.fabric8.kubernetes.client.Config;
189
import io.quarkus.kubernetes.client.KubernetesConfigCustomizer;
190
import jakarta.enterprise.context.ApplicationScoped;
191
import java.util.Map;
192
193
@ApplicationScoped
194
public class MyConfigCustomizer implements KubernetesConfigCustomizer {
195
@Override
196
public void customize(Config config) {
197
// Add custom headers
198
config.setCustomHeaders(Map.of("X-Custom-Header", "value"));
199
200
// Override specific settings
201
config.setMaxConcurrentRequests(100);
202
config.setMaxConcurrentRequestsPerHost(50);
203
}
204
}
205
```
206
207
### ObjectMapper Customization
208
209
Customize the Jackson ObjectMapper used for Kubernetes resource serialization and deserialization.
210
211
```java { .api }
212
public interface KubernetesClientObjectMapperCustomizer {
213
/**
214
* Customize the ObjectMapper used by the KubernetesClient.
215
* Called during ObjectMapper creation to configure JSON handling.
216
*
217
* @param objectMapper the ObjectMapper instance to customize
218
*/
219
void customize(ObjectMapper objectMapper);
220
}
221
```
222
223
**Usage Example:**
224
225
```java
226
import com.fasterxml.jackson.databind.ObjectMapper;
227
import io.quarkus.kubernetes.client.KubernetesClientObjectMapperCustomizer;
228
import jakarta.enterprise.context.ApplicationScoped;
229
import java.text.SimpleDateFormat;
230
import java.util.Locale;
231
232
@ApplicationScoped
233
public class MyObjectMapperCustomizer implements KubernetesClientObjectMapperCustomizer {
234
@Override
235
public void customize(ObjectMapper objectMapper) {
236
// Set locale for consistent serialization
237
objectMapper.setLocale(Locale.ROOT);
238
239
// Configure date formatting
240
objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'"));
241
}
242
}
243
```
244
245
### CDI Qualifiers
246
247
Specialized CDI qualifiers for injection of specific Kubernetes-related beans.
248
249
```java { .api }
250
@Qualifier
251
@Retention(RUNTIME)
252
@Target({ METHOD, FIELD, PARAMETER, TYPE })
253
@Documented
254
public @interface KubernetesClientObjectMapper {
255
final class Literal extends AnnotationLiteral<KubernetesClientObjectMapper>
256
implements KubernetesClientObjectMapper {
257
public static final Literal INSTANCE = new Literal();
258
}
259
}
260
261
@Qualifier
262
@Retention(RUNTIME)
263
@Target({ METHOD, FIELD, PARAMETER, TYPE })
264
public @interface KubernetesResources {
265
}
266
```
267
268
**Usage Example:**
269
270
```java
271
import com.fasterxml.jackson.databind.ObjectMapper;
272
import io.quarkus.kubernetes.client.KubernetesClientObjectMapper;
273
import jakarta.inject.Inject;
274
275
@ApplicationScoped
276
public class MyService {
277
278
@Inject
279
@KubernetesClientObjectMapper
280
ObjectMapper kubernetesObjectMapper;
281
282
public void processKubernetesJson(String json) {
283
// Use the Kubernetes-specific ObjectMapper
284
Pod pod = kubernetesObjectMapper.readValue(json, Pod.class);
285
}
286
}
287
```
288
289
### SPI Build Items for Extension Development
290
291
Build-time API for other Quarkus extensions to integrate with the Kubernetes client.
292
293
```java { .api }
294
public final class KubernetesClientBuildItem extends SimpleBuildItem {
295
public KubernetesClientBuildItem(Config config, HttpClient.Factory httpClientFactory);
296
297
/**
298
* Get the Kubernetes client configuration.
299
* @return the Config instance
300
*/
301
public Config getConfig();
302
303
/**
304
* Get the HTTP client factory used by the Kubernetes client.
305
* @return the HttpClient.Factory instance
306
*/
307
public HttpClient.Factory getHttpClientFactory();
308
309
/**
310
* Build a KubernetesClient instance for build-time use.
311
* @return a configured KubernetesClient instance
312
*/
313
public KubernetesClient buildClient();
314
}
315
316
public final class KubernetesResourcesBuildItem extends SimpleBuildItem {
317
public KubernetesResourcesBuildItem(String[] resourceClasses);
318
319
/**
320
* Get the array of Kubernetes resource class names to register.
321
* @return array of resource class names
322
*/
323
public String[] getResourceClasses();
324
}
325
326
public final class KubernetesClientCapabilityBuildItem extends SimpleBuildItem {
327
public KubernetesClientCapabilityBuildItem(boolean generateRbac);
328
329
/**
330
* Check if RBAC generation is enabled.
331
* @return true if RBAC generation is enabled
332
*/
333
public boolean isGenerateRbac();
334
}
335
```
336
337
### DevServices Integration
338
339
Build items for DevServices test container integration.
340
341
```java { .api }
342
public final class KubernetesDevServiceInfoBuildItem extends SimpleBuildItem {
343
public KubernetesDevServiceInfoBuildItem(String kubeConfig, String containerId);
344
345
/**
346
* Get the KubeConfig as YAML string for the test container.
347
* @return the KubeConfig as YAML string
348
*/
349
public String getKubeConfig();
350
351
/**
352
* Get the container ID of the running kind test container.
353
* @return the containerId of the running test container
354
*/
355
public String getContainerId();
356
}
357
358
public final class KubernetesDevServiceRequestBuildItem extends SimpleBuildItem {
359
public KubernetesDevServiceRequestBuildItem(String flavor);
360
361
/**
362
* Get the flavor of the kubernetes cluster to start.
363
* @return the flavor of the kubernetes cluster (kind, k3s, etc)
364
*/
365
public String getFlavor();
366
}
367
```
368
369
## Configuration Properties
370
371
All configuration properties use the `quarkus.kubernetes-client` prefix:
372
373
```java { .api }
374
@ConfigMapping(prefix = "quarkus.kubernetes-client")
375
@ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)
376
public interface KubernetesClientBuildConfig {
377
378
/** Whether the client should trust a self-signed certificate if so presented by the API server */
379
Optional<Boolean> trustCerts();
380
381
/** URL of the Kubernetes API server */
382
Optional<String> apiServerUrl();
383
384
/** @deprecated Use api-server-url instead */
385
@Deprecated(forRemoval = true)
386
Optional<String> masterUrl();
387
388
/** Default namespace to use */
389
Optional<String> namespace();
390
391
/** CA certificate file */
392
Optional<String> caCertFile();
393
394
/** CA certificate data */
395
Optional<String> caCertData();
396
397
/** Client certificate file */
398
Optional<String> clientCertFile();
399
400
/** Client certificate data */
401
Optional<String> clientCertData();
402
403
/** Client key file */
404
Optional<String> clientKeyFile();
405
406
/** Client key data */
407
Optional<String> clientKeyData();
408
409
/** Client key algorithm */
410
Optional<String> clientKeyAlgo();
411
412
/** Client key passphrase */
413
Optional<String> clientKeyPassphrase();
414
415
/** Kubernetes auth username */
416
Optional<String> username();
417
418
/** Kubernetes auth password */
419
Optional<String> password();
420
421
/** Kubernetes oauth token */
422
Optional<String> token();
423
424
/** Watch reconnect interval */
425
Optional<Duration> watchReconnectInterval();
426
427
/** Maximum reconnect attempts in case of watch failure */
428
OptionalInt watchReconnectLimit();
429
430
/** Maximum amount of time to wait for a connection with the API server to be established */
431
Optional<Duration> connectionTimeout();
432
433
/** Maximum amount of time to wait for a request to the API server to be completed */
434
Optional<Duration> requestTimeout();
435
436
/** Maximum number of retry attempts for API requests that fail with an HTTP code of >= 500 */
437
OptionalInt requestRetryBackoffLimit();
438
439
/** Time interval between retry attempts for API requests that fail with an HTTP code of >= 500 */
440
Optional<Duration> requestRetryBackoffInterval();
441
442
/** HTTP proxy used to access the Kubernetes API server */
443
Optional<String> httpProxy();
444
445
/** HTTPS proxy used to access the Kubernetes API server */
446
Optional<String> httpsProxy();
447
448
/** Proxy username */
449
Optional<String> proxyUsername();
450
451
/** Proxy password */
452
Optional<String> proxyPassword();
453
454
/** IP addresses or hosts to exclude from proxying */
455
Optional<List<String>> noProxy();
456
457
/** Enable the generation of the RBAC manifests */
458
@WithDefault("true")
459
boolean generateRbac();
460
461
/** DevServices configuration for testing */
462
KubernetesDevServicesBuildTimeConfig devservices();
463
}
464
465
@ConfigMapping(prefix = "quarkus.kubernetes-client.devservices")
466
public interface KubernetesDevServicesBuildTimeConfig {
467
468
/** If Dev Services for Kubernetes should be used (default: true) */
469
@WithDefault("true")
470
boolean enabled();
471
472
/** The kubernetes api server version to use */
473
Optional<String> apiVersion();
474
475
/** The kubernetes image to use */
476
Optional<String> imageName();
477
478
/** The flavor to use (kind, k3s or api-only). Default: api-only */
479
Optional<Flavor> flavor();
480
481
/** Override kubeconfig config if found. Default: false */
482
@WithDefault("false")
483
boolean overrideKubeconfig();
484
485
/** List of manifest file paths to apply on startup */
486
Optional<List<String>> manifests();
487
488
/** Whether the Kubernetes cluster is shared. Default: true */
489
@WithDefault("true")
490
boolean shared();
491
492
/** Service name for shared clusters. Default: kubernetes */
493
@WithDefault("kubernetes")
494
String serviceName();
495
496
/** Environment variables passed to the container */
497
Map<String, String> containerEnv();
498
499
enum Flavor {
500
kind, // needs privileged docker
501
k3s, // needs privileged docker
502
api_only // api only
503
}
504
}
505
```
506
507
## CDI Producers
508
509
The extension provides several CDI producers that create the necessary beans:
510
511
```java { .api }
512
@Singleton
513
public class KubernetesConfigProducer {
514
@DefaultBean
515
@Singleton
516
@Produces
517
public Config config(KubernetesClientBuildConfig buildConfig,
518
@All List<KubernetesConfigCustomizer> customizers);
519
}
520
521
@Singleton
522
public class KubernetesClientObjectMapperProducer {
523
@KubernetesClientObjectMapper
524
@DefaultBean
525
@Priority(Integer.MIN_VALUE)
526
@Singleton
527
@Produces
528
public ObjectMapper kubernetesClientObjectMapper(@All List<KubernetesClientObjectMapperCustomizer> customizers);
529
}
530
531
@Singleton
532
public class KubernetesSerializationProducer {
533
@DefaultBean
534
@Singleton
535
@Produces
536
public KubernetesSerialization kubernetesSerialization(
537
@KubernetesClientObjectMapper ObjectMapper objectMapper,
538
@KubernetesResources Class[] kubernetesResources);
539
}
540
```
541
542
## External Dependencies
543
544
The extension integrates with these key Fabric8 Kubernetes Client classes:
545
546
- `io.fabric8.kubernetes.client.KubernetesClient` - Main client interface for Kubernetes operations
547
- `io.fabric8.kubernetes.client.Config` - Configuration for the Kubernetes client
548
- `io.fabric8.kubernetes.client.utils.KubernetesSerialization` - Serialization utilities for Kubernetes resources
549
- `com.fasterxml.jackson.databind.ObjectMapper` - JSON serialization/deserialization
550
- `io.fabric8.kubernetes.client.http.HttpClient` - HTTP client abstraction for Kubernetes API calls
551
552
## Testing and DevServices
553
554
The extension provides automatic DevServices integration for testing:
555
556
```java
557
// DevServices automatically starts a kind cluster for tests
558
@QuarkusTest
559
public class KubernetesClientTest {
560
561
@Inject
562
KubernetesClient client;
563
564
@Test
565
public void testKubernetesOperations() {
566
// Test against the automatically started cluster
567
PodList pods = client.pods().list();
568
assertThat(pods).isNotNull();
569
}
570
}
571
```
572
573
Configuration for DevServices:
574
575
```properties
576
# Enable DevServices (default: true in test mode)
577
quarkus.kubernetes-client.devservices.enabled=true
578
579
# Choose cluster flavor
580
quarkus.kubernetes-client.devservices.flavor=kind
581
582
# Or use k3s
583
quarkus.kubernetes-client.devservices.flavor=k3s
584
585
# Or use api-only (for minimal testing)
586
quarkus.kubernetes-client.devservices.flavor=api-only
587
```