0
# Core Resources
1

2
The Fabric8 Kubernetes Client provides fluent DSL operations for all standard Kubernetes resources. This includes fundamental resources like Pods, Services, ConfigMaps, Secrets, Namespaces, and more. All operations follow consistent patterns with type-safe interfaces.
3

4
## Core Operation Interfaces
5

6
### MixedOperation Interface
7

8
The primary interface for resource operations that can work both within specific namespaces and across all namespaces.
9

10
```java { .api }
11
public interface MixedOperation<T extends HasMetadata, L extends KubernetesResourceList<T>, R extends Resource<T>> 
12
    extends NonNamespaceOperation<T, L, R> {
13
    
14
    // Namespace-scoped operations
15
    NonNamespaceOperation<T, L, R> inNamespace(String namespace);
16
    NonNamespaceOperation<T, L, R> inAnyNamespace();
17
    
18
    // All methods from NonNamespaceOperation are also available
19
}
20
```
21

22
### NonNamespaceOperation Interface
23

24
Base interface providing core CRUD and query operations for resources.
25

26
```java { .api }
27
public interface NonNamespaceOperation<T extends HasMetadata, L extends KubernetesResourceList<T>, R extends Resource<T>> {
28
    // Resource selection
29
    R withName(String name);
30
    NonNamespaceOperation<T, L, R> withLabel(String key, String value);
31
    NonNamespaceOperation<T, L, R> withLabelSelector(LabelSelector selector);
32
    NonNamespaceOperation<T, L, R> withField(String key, String value);
33
    NonNamespaceOperation<T, L, R> withFieldSelector(String fieldSelector);
34
    
35
    // List operations
36
    L list();
37
    L list(ListOptions listOptions);
38
    
39
    // Bulk operations
40
    Boolean delete();
41
    Boolean delete(DeleteOptions deleteOptions);
42
    
43
    // Watch operations
44
    Watch watch(Watcher<T> watcher);
45
    Watch watch(String resourceVersion, Watcher<T> watcher);
46
    Watch watch(ListOptions listOptions, Watcher<T> watcher);
47
    
48
    // Waiting operations
49
    List<T> waitUntilReady(long amount, TimeUnit timeUnit) throws InterruptedException;
50
    List<T> waitUntilCondition(Predicate<T> condition, long amount, TimeUnit timeUnit) throws InterruptedException;
51
}
52
```
53

54
### Resource Interface
55

56
Interface for operations on individual Kubernetes resources.
57

58
```java { .api }
59
public interface Resource<T extends HasMetadata> {
60
    // Basic CRUD operations
61
    T get();
62
    T create();
63
    T delete();
64
    Boolean delete(DeleteOptions deleteOptions);
65
    T update();
66
    T patch(String patch);
67
    T patch(PatchContext patchContext, String patch);
68
    T replace();
69
    
70
    // Advanced operations
71
    T fromServer();
72
    T require();
73
    T item();
74
    boolean isReady();
75
    T waitUntilReady(long amount, TimeUnit timeUnit);
76
    T waitUntilCondition(Predicate<T> condition, long amount, TimeUnit timeUnit);
77
    
78
    // Resource version locking
79
    ReplaceDeletable<T> lockResourceVersion();
80
    ReplaceDeletable<T> lockResourceVersion(String resourceVersion);
81
    
82
    // Watch operations
83
    Watch watch(Watcher<T> watcher);
84
    
85
    // Edit operations
86
    T edit();
87
    T edit(Visitor<T> visitor);
88
    T editStatus();
89
    T editStatus(Visitor<T> visitor);
90
    
91
    // Configuration for delete operations
92
    Resource<T> cascading(boolean cascading);
93
    Resource<T> withGracePeriod(long gracePeriodSeconds);
94
    Resource<T> withPropagationPolicy(DeletionPropagation propagationPolicy);
95
    
96
    // Dry run operations
97
    Resource<T> dryRun(boolean isDryRun);
98
}
99
```
100

101
## Core Resource Types
102

103
### Pods
104

105
Pod operations with specialized functionality for container management.
106

107
```java { .api }
108
public interface KubernetesClient {
109
    MixedOperation<Pod, PodList, PodResource> pods();
110
}
111

112
// Pod-specific operations are in PodResource (see Pod Operations doc)
113
```
114

115
Usage Examples:
116

117
```java
118
// List all pods in current namespace
119
PodList pods = client.pods().list();
120

121
// Get a specific pod
122
Pod pod = client.pods().withName("my-pod").get();
123

124
// Create a pod
125
Pod newPod = client.pods().create(new PodBuilder()
126
    .withNewMetadata()
127
        .withName("example-pod")
128
        .withLabels(Map.of("app", "example"))
129
    .endMetadata()
130
    .withNewSpec()
131
        .addNewContainer()
132
            .withName("app")
133
            .withImage("nginx:1.21")
134
            .addNewPort()
135
                .withContainerPort(80)
136
            .endPort()
137
        .endContainer()
138
    .endSpec()
139
    .build());
140

141
// Delete pods by label
142
client.pods().withLabel("app", "example").delete();
143

144
// Watch for pod changes
145
Watch watch = client.pods().watch(new Watcher<Pod>() {
146
    @Override
147
    public void eventReceived(Action action, Pod pod) {
148
        System.out.println(action + ": " + pod.getMetadata().getName());
149
    }
150
    
151
    @Override
152
    public void onClose(WatcherException cause) {
153
        System.out.println("Watch closed: " + cause);
154
    }
155
});
156
```
157

158
### Services
159

160
Service operations for network access management.
161

162
```java { .api }
163
public interface KubernetesClient {
164
    MixedOperation<Service, ServiceList, ServiceResource> services();
165
}
166
```
167

168
Usage Examples:
169

170
```java
171
// Create a service
172
Service service = client.services().create(new ServiceBuilder()
173
    .withNewMetadata()
174
        .withName("my-service")
175
        .withLabels(Map.of("app", "example"))
176
    .endMetadata()
177
    .withNewSpec()
178
        .withSelector(Map.of("app", "example"))
179
        .addNewPort()
180
            .withPort(80)
181
            .withTargetPort(new IntOrString(8080))
182
            .withProtocol("TCP")
183
        .endPort()
184
        .withType("ClusterIP")
185
    .endSpec()
186
    .build());
187

188
// Update service
189
Service updatedService = client.services().withName("my-service").edit(s -> 
190
    new ServiceBuilder(s)
191
        .editSpec()
192
            .withType("LoadBalancer")
193
        .endSpec()
194
        .build());
195

196
// List services with label selector
197
ServiceList services = client.services()
198
    .withLabelSelector(new LabelSelectorBuilder()
199
        .addToMatchLabels("app", "example")
200
        .build())
201
    .list();
202
```
203

204
### ConfigMaps
205

206
ConfigMap operations for configuration data management.
207

208
```java { .api }
209
public interface KubernetesClient {
210
    MixedOperation<ConfigMap, ConfigMapList, Resource<ConfigMap>> configMaps();
211
}
212
```
213

214
Usage Examples:
215

216
```java
217
// Create a ConfigMap
218
ConfigMap configMap = client.configMaps().create(new ConfigMapBuilder()
219
    .withNewMetadata()
220
        .withName("app-config")
221
    .endMetadata()
222
    .withData(Map.of(
223
        "database.url", "jdbc:postgresql://localhost:5432/mydb",
224
        "cache.enabled", "true",
225
        "log.level", "INFO"
226
    ))
227
    .build());
228

229
// Update ConfigMap data
230
client.configMaps().withName("app-config").edit(cm ->
231
    new ConfigMapBuilder(cm)
232
        .addToData("new.property", "new-value")
233
        .build());
234

235
// Get ConfigMap data
236
ConfigMap cm = client.configMaps().withName("app-config").get();
237
String dbUrl = cm.getData().get("database.url");
238
```
239

240
### Secrets
241

242
Secret operations for sensitive data management.
243

244
```java { .api }
245
public interface KubernetesClient {
246
    MixedOperation<Secret, SecretList, Resource<Secret>> secrets();
247
}
248
```
249

250
Usage Examples:
251

252
```java
253
// Create a generic secret
254
Secret secret = client.secrets().create(new SecretBuilder()
255
    .withNewMetadata()
256
        .withName("app-secrets")
257
    .endMetadata()
258
    .withType("Opaque")
259
    .withData(Map.of(
260
        "username", Base64.getEncoder().encodeToString("admin".getBytes()),
261
        "password", Base64.getEncoder().encodeToString("secret123".getBytes())
262
    ))
263
    .build());
264

265
// Create a TLS secret
266
Secret tlsSecret = client.secrets().create(new SecretBuilder()
267
    .withNewMetadata()
268
        .withName("tls-secret")
269
    .endMetadata()
270
    .withType("kubernetes.io/tls")
271
    .withData(Map.of(
272
        "tls.crt", Base64.getEncoder().encodeToString(certData),
273
        "tls.key", Base64.getEncoder().encodeToString(keyData)
274
    ))
275
    .build());
276

277
// Read secret data
278
Secret secret = client.secrets().withName("app-secrets").get();
279
String username = new String(Base64.getDecoder().decode(secret.getData().get("username")));
280
```
281

282
### Namespaces
283

284
Namespace operations for resource isolation and organization.
285

286
```java { .api }
287
public interface KubernetesClient {
288
    NonNamespaceOperation<Namespace, NamespaceList, Resource<Namespace>> namespaces();
289
}
290
```
291

292
Usage Examples:
293

294
```java
295
// Create a namespace
296
Namespace namespace = client.namespaces().create(new NamespaceBuilder()
297
    .withNewMetadata()
298
        .withName("development")
299
        .withLabels(Map.of("environment", "dev"))
300
    .endMetadata()
301
    .build());
302

303
// List all namespaces
304
NamespaceList namespaces = client.namespaces().list();
305

306
// Check if namespace exists
307
boolean exists = client.namespaces().withName("production").get() != null;
308

309
// Delete namespace (this will delete all resources in the namespace)
310
client.namespaces().withName("old-namespace").delete();
311
```
312

313
### Nodes
314

315
Node operations for cluster node management.
316

317
```java { .api }
318
public interface KubernetesClient {
319
    NonNamespaceOperation<Node, NodeList, Resource<Node>> nodes();
320
}
321
```
322

323
Usage Examples:
324

325
```java
326
// List all nodes
327
NodeList nodes = client.nodes().list();
328

329
// Get node details
330
Node node = client.nodes().withName("worker-node-1").get();
331
NodeStatus status = node.getStatus();
332
List<NodeCondition> conditions = status.getConditions();
333

334
// Label a node
335
client.nodes().withName("worker-node-1").edit(n ->
336
    new NodeBuilder(n)
337
        .editMetadata()
338
            .addToLabels("node-role", "worker")
339
        .endMetadata()
340
        .build());
341

342
// Cordon a node (mark as unschedulable)
343
client.nodes().withName("worker-node-1").edit(n ->
344
    new NodeBuilder(n)
345
        .editSpec()
346
            .withUnschedulable(true)
347
        .endSpec()
348
        .build());
349
```
350

351
### Persistent Volumes and Claims
352

353
Storage operations for persistent data management.
354

355
```java { .api }
356
public interface KubernetesClient {
357
    NonNamespaceOperation<PersistentVolume, PersistentVolumeList, Resource<PersistentVolume>> persistentVolumes();
358
    MixedOperation<PersistentVolumeClaim, PersistentVolumeClaimList, Resource<PersistentVolumeClaim>> persistentVolumeClaims();
359
}
360
```
361

362
Usage Examples:
363

364
```java
365
// Create a PersistentVolumeClaim
366
PersistentVolumeClaim pvc = client.persistentVolumeClaims().create(new PersistentVolumeClaimBuilder()
367
    .withNewMetadata()
368
        .withName("app-storage")
369
    .endMetadata()
370
    .withNewSpec()
371
        .withAccessModes("ReadWriteOnce")
372
        .withNewResources()
373
            .addToRequests("storage", new Quantity("10Gi"))
374
        .endResources()
375
        .withStorageClassName("fast-ssd")
376
    .endSpec()
377
    .build());
378

379
// List PVCs by storage class
380
PersistentVolumeClaimList pvcs = client.persistentVolumeClaims()
381
    .withField("spec.storageClassName", "fast-ssd")
382
    .list();
383
```
384

385
### Service Accounts
386

387
Service account operations for pod authentication and authorization.
388

389
```java { .api }
390
public interface KubernetesClient {
391
    MixedOperation<ServiceAccount, ServiceAccountList, ServiceAccountResource> serviceAccounts();
392
}
393
```
394

395
Usage Examples:
396

397
```java
398
// Create a service account
399
ServiceAccount sa = client.serviceAccounts().create(new ServiceAccountBuilder()
400
    .withNewMetadata()
401
        .withName("app-service-account")
402
    .endMetadata()
403
    .build());
404

405
// Create service account with image pull secrets
406
ServiceAccount saWithSecrets = client.serviceAccounts().create(new ServiceAccountBuilder()
407
    .withNewMetadata()
408
        .withName("app-sa-with-secrets")
409
    .endMetadata()
410
    .addNewImagePullSecret()
411
        .withName("registry-secret")
412
    .endImagePullSecret()
413
    .build());
414
```
415

416
## Resource Builder Patterns
417

418
All Kubernetes resources support builder patterns for fluent creation and modification:
419

420
```java
421
// Pod builder example
422
Pod pod = new PodBuilder()
423
    .withNewMetadata()
424
        .withName("example-pod")
425
        .withNamespace("default")
426
        .addToLabels("app", "example")
427
        .addToAnnotations("description", "Example pod")
428
    .endMetadata()
429
    .withNewSpec()
430
        .addNewContainer()
431
            .withName("main")
432
            .withImage("nginx:1.21")
433
            .addNewPort()
434
                .withContainerPort(80)
435
                .withName("http")
436
            .endPort()
437
            .addNewEnv()
438
                .withName("ENV_VAR")
439
                .withValue("example-value")
440
            .endEnv()
441
            .withNewResources()
442
                .addToRequests("cpu", new Quantity("100m"))
443
                .addToRequests("memory", new Quantity("128Mi"))
444
                .addToLimits("cpu", new Quantity("500m"))
445
                .addToLimits("memory", new Quantity("512Mi"))
446
            .endResources()
447
        .endContainer()
448
        .withRestartPolicy("Always")
449
    .endSpec()
450
    .build();
451
```
452

453
## Error Handling
454

455
Resource operations can throw various exceptions that should be handled appropriately:
456

457
```java
458
try {
459
    Pod pod = client.pods().withName("my-pod").get();
460
    if (pod == null) {
461
        System.out.println("Pod not found");
462
    }
463
} catch (KubernetesClientException e) {
464
    if (e.getCode() == 404) {
465
        System.out.println("Pod not found: " + e.getMessage());
466
    } else if (e.getCode() == 403) {
467
        System.out.println("Access denied: " + e.getMessage());
468
    } else {
469
        System.out.println("API error: " + e.getMessage());
470
    }
471
}
472

473
// Using require() method that throws exception if resource not found
474
try {
475
    Pod pod = client.pods().withName("my-pod").require();
476
    // Pod is guaranteed to exist here
477
} catch (ResourceNotFoundException e) {
478
    System.out.println("Required pod not found: " + e.getMessage());
479
}
480
```