0
# Image Operations
1

2
This document covers OpenShift image management operations, including image streams, image stream tags, image imports, and container registry operations.
3

4
## Core Imports
5

6
```java { .api }
7
import io.fabric8.openshift.client.OpenShiftClient;
8
import io.fabric8.openshift.api.model.Image;
9
import io.fabric8.openshift.api.model.ImageList;
10
import io.fabric8.openshift.api.model.ImageStream;
11
import io.fabric8.openshift.api.model.ImageStreamList;
12
import io.fabric8.openshift.api.model.ImageStreamTag;
13
import io.fabric8.openshift.api.model.ImageStreamTagList;
14
import io.fabric8.openshift.api.model.ImageTag;
15
import io.fabric8.openshift.api.model.ImageTagList;
16
import io.fabric8.openshift.api.model.ImageStreamImport;
17
import io.fabric8.openshift.api.model.ImageStreamMapping;
18
import io.fabric8.openshift.api.model.ImageStreamImage;
19
import io.fabric8.kubernetes.client.dsl.Resource;
20
import io.fabric8.kubernetes.client.dsl.MixedOperation;
21
import io.fabric8.kubernetes.client.dsl.NonNamespaceOperation;
22
import io.fabric8.kubernetes.client.dsl.NamespacedInOutCreateable;
23
```
24

25
## Image Operations
26

27
### Basic Image Operations
28

29
```java { .api }
30
// List all images in the cluster
31
ImageList images = client.images().list();
32

33
// Get a specific image by name
34
Image image = client.images()
35
    .withName("sha256:abc123...")
36
    .get();
37

38
// List images with label selector
39
ImageList labeledImages = client.images()
40
    .withLabel("version", "latest")
41
    .list();
42
```
43

44
### Image Information
45

46
```java { .api }
47
// Get image metadata
48
Image image = client.images()
49
    .withName("sha256:abc123...")
50
    .get();
51

52
String dockerImageReference = image.getDockerImageReference();
53
ObjectMeta metadata = image.getDockerImageMetadata();
54
List<String> layers = image.getDockerImageLayers();
55
String manifest = image.getDockerImageManifest();
56
```
57

58
## ImageStream Operations
59

60
### Basic ImageStream Operations
61

62
```java { .api }
63
// List all image streams in a namespace
64
ImageStreamList imageStreams = client.imageStreams()
65
    .inNamespace("my-project")
66
    .list();
67

68
// Get a specific image stream
69
ImageStream imageStream = client.imageStreams()
70
    .inNamespace("my-project")
71
    .withName("my-app")
72
    .get();
73

74
// Create a new image stream
75
ImageStream newImageStream = new ImageStreamBuilder()
76
    .withNewMetadata()
77
        .withName("my-new-app")
78
        .withNamespace("my-project")
79
        .addToLabels("app", "my-new-app")
80
    .endMetadata()
81
    .withNewSpec()
82
        .addNewTag()
83
            .withName("latest")
84
            .withNewFrom()
85
                .withKind("DockerImage")
86
                .withName("registry.example.com/my-app:latest")
87
            .endFrom()
88
        .endTag()
89
    .endSpec()
90
    .build();
91

92
ImageStream created = client.imageStreams()
93
    .inNamespace("my-project")
94
    .create(newImageStream);
95
```
96

97
### ImageStream Tag Management
98

99
```java { .api }
100
// Add a new tag to an image stream
101
ImageStream updated = client.imageStreams()
102
    .inNamespace("my-project")
103
    .withName("my-app")
104
    .edit(is -> new ImageStreamBuilder(is)
105
        .editSpec()
106
            .addNewTag()
107
                .withName("v2.0")
108
                .withNewFrom()
109
                    .withKind("DockerImage")
110
                    .withName("registry.example.com/my-app:2.0.0")
111
                .endFrom()
112
            .endTag()
113
        .endSpec()
114
        .build());
115

116
// Remove a tag from an image stream
117
ImageStream tagRemoved = client.imageStreams()
118
    .inNamespace("my-project")
119
    .withName("my-app")
120
    .edit(is -> new ImageStreamBuilder(is)
121
        .editSpec()
122
            .removeFromTags(is.getSpec().getTags().stream()
123
                .filter(tag -> "old-tag".equals(tag.getName()))
124
                .findFirst()
125
                .orElse(null))
126
        .endSpec()
127
        .build());
128
```
129

130
### ImageStream Status and History
131

132
```java { .api }
133
// Get image stream status
134
ImageStream imageStream = client.imageStreams()
135
    .inNamespace("my-project")
136
    .withName("my-app")
137
    .get();
138

139
List<NamedTagEventList> tags = imageStream.getStatus().getTags();
140
for (NamedTagEventList tag : tags) {
141
    System.out.println("Tag: " + tag.getTag());
142
    for (TagEvent event : tag.getItems()) {
143
        System.out.println("  Image: " + event.getImage());
144
        System.out.println("  Created: " + event.getCreated());
145
    }
146
}
147
```
148

149
## ImageStreamTag Operations
150

151
### Working with ImageStreamTags
152

153
```java { .api }
154
// Get a specific image stream tag
155
ImageStreamTag imageStreamTag = client.imageStreamTags()
156
    .inNamespace("my-project")
157
    .withName("my-app:latest")
158
    .get();
159

160
// List all image stream tags in namespace
161
ImageStreamTagList allTags = client.imageStreamTags()
162
    .inNamespace("my-project")
163
    .list();
164

165
// Create or update an image stream tag
166
ImageStreamTag newTag = new ImageStreamTagBuilder()
167
    .withNewMetadata()
168
        .withName("my-app:stable")
169
        .withNamespace("my-project")
170
    .endMetadata()
171
    .withNewTag()
172
        .withNewFrom()
173
            .withKind("ImageStreamTag")
174
            .withName("my-app:latest")
175
        .endFrom()
176
    .endTag()
177
    .build();
178

179
ImageStreamTag created = client.imageStreamTags()
180
    .inNamespace("my-project")
181
    .create(newTag);
182
```
183

184
### ImageStreamTag Information
185

186
```java { .api }
187
// Get tag information
188
ImageStreamTag tag = client.imageStreamTags()
189
    .inNamespace("my-project")
190
    .withName("my-app:latest")
191
    .get();
192

193
Image tagImage = tag.getImage();
194
String dockerImageReference = tag.getTag().getFrom().getName();
195
List<TagCondition> conditions = tag.getTag().getConditions();
196
```
197

198
## ImageTag Operations
199

200
### Basic ImageTag Operations
201

202
```java { .api }
203
// List image tags in namespace
204
ImageTagList imageTags = client.imageTags()
205
    .inNamespace("my-project")
206
    .list();
207

208
// Get specific image tag
209
ImageTag imageTag = client.imageTags()
210
    .inNamespace("my-project")
211
    .withName("my-app:latest")
212
    .get();
213

214
// Create image tag
215
ImageTag newImageTag = new ImageTagBuilder()
216
    .withNewMetadata()
217
        .withName("my-app:production")
218
        .withNamespace("my-project")
219
    .endMetadata()
220
    .withNewSpec()
221
        .withNewFrom()
222
            .withKind("ImageStreamTag")
223
            .withName("my-app:latest")
224
        .endFrom()
225
    .endSpec()
226
    .build();
227

228
ImageTag created = client.imageTags()
229
    .inNamespace("my-project")
230
    .create(newImageTag);
231
```
232

233
## Image Import Operations
234

235
### ImageStreamImport Operations
236

237
```java { .api }
238
// Import external image into image stream
239
ImageStreamImport imageImport = new ImageStreamImportBuilder()
240
    .withNewMetadata()
241
        .withName("my-app")
242
        .withNamespace("my-project")
243
    .endMetadata()
244
    .withNewSpec()
245
        .withImport(true)
246
        .withNewRepository()
247
            .withNewFrom()
248
                .withKind("DockerImage")
249
                .withName("registry.example.com/my-app:latest")
250
            .endFrom()
251
            .withNewImportPolicy()
252
                .withInsecure(false)
253
                .withScheduled(true)
254
            .endImportPolicy()
255
        .endRepository()
256
        .addNewImage()
257
            .withNewFrom()
258
                .withKind("DockerImage")
259
                .withName("registry.example.com/my-app:v1.0")
260
            .endFrom()
261
            .withNewTo()
262
                .withName("v1.0")
263
            .endTo()
264
            .withNewImportPolicy()
265
                .withInsecure(false)
266
            .endImportPolicy()
267
        .endImage()
268
    .endSpec()
269
    .build();
270

271
ImageStreamImport result = client.imageStreamImports()
272
    .inNamespace("my-project")
273
    .create(imageImport);
274
```
275

276
### ImageStreamMapping Operations
277

278
```java { .api }
279
// Create image stream mapping (typically used by registry)
280
ImageStreamMapping mapping = new ImageStreamMappingBuilder()
281
    .withNewMetadata()
282
        .withName("my-app")
283
        .withNamespace("my-project")
284
    .endMetadata()
285
    .withNewImage()
286
        .withDockerImageReference("registry.example.com/my-app@sha256:abc123...")
287
        .withNewMetadata()
288
            .withName("sha256:abc123...")
289
        .endMetadata()
290
    .endImage()
291
    .withTag("latest")
292
    .build();
293

294
ImageStreamMapping created = client.imageStreamMappings()
295
    .inNamespace("my-project")
296
    .create(mapping);
297
```
298

299
## ImageStreamImage Operations
300

301
### Getting ImageStreamImage
302

303
```java { .api }
304
// Get image stream image (read-only)
305
ImageStreamImage imageStreamImage = client.imageStreamImages()
306
    .inNamespace("my-project")
307
    .withName("my-app@sha256:abc123...")
308
    .get();
309

310
String dockerImageReference = imageStreamImage.getImage().getDockerImageReference();
311
ObjectMeta imageMetadata = imageStreamImage.getImage().getDockerImageMetadata();
312
```
313

314
## Advanced Image Operations
315

316
### Watching Image Changes
317

318
```java { .api }
319
// Watch image stream changes
320
client.imageStreams()
321
    .inNamespace("my-project")
322
    .withName("my-app")
323
    .watch(new Watcher<ImageStream>() {
324
        @Override
325
        public void eventReceived(Action action, ImageStream imageStream) {
326
            System.out.println("ImageStream " + action + ": " + 
327
                imageStream.getMetadata().getName());
328
                
329
            if (imageStream.getStatus() != null && imageStream.getStatus().getTags() != null) {
330
                imageStream.getStatus().getTags().forEach(tag -> 
331
                    System.out.println("  Tag: " + tag.getTag() + 
332
                        " (" + tag.getItems().size() + " images)"));
333
            }
334
        }
335
        
336
        @Override
337
        public void onClose(WatcherException cause) {
338
            System.out.println("Watch closed: " + cause.getMessage());
339
        }
340
    });
341
```
342

343
### Image Pull Secrets
344

345
```java { .api }
346
// Create image pull secret
347
Secret pullSecret = new SecretBuilder()
348
    .withNewMetadata()
349
        .withName("registry-secret")
350
        .withNamespace("my-project")
351
    .endMetadata()
352
    .withType("kubernetes.io/dockerconfigjson")
353
    .addToData(".dockerconfigjson", 
354
        Base64.getEncoder().encodeToString(dockerConfig.getBytes()))
355
    .build();
356

357
client.secrets()
358
    .inNamespace("my-project")
359
    .create(pullSecret);
360

361
// Link pull secret to image stream
362
ImageStream linked = client.imageStreams()
363
    .inNamespace("my-project")
364
    .withName("my-app")
365
    .edit(is -> new ImageStreamBuilder(is)
366
        .editSpec()
367
            .addNewTag()
368
                .withName("secure")
369
                .withNewFrom()
370
                    .withKind("DockerImage")
371
                    .withName("private-registry.com/my-app:latest")
372
                .endFrom()
373
                .withNewReferencePolicy()
374
                    .withType("Local")
375
                .endReferencePolicy()
376
                .withNewImportPolicy()
377
                    .withInsecure(false)
378
                .endImportPolicy()
379
            .endTag()
380
        .endSpec()
381
        .build());
382
```
383

384
### Image Pruning Operations
385

386
```java { .api }
387
// Get images that can be pruned (using image pruner configuration)
388
// This typically requires cluster admin privileges
389
List<Image> allImages = client.images().list().getItems();
390

391
// Filter images for potential pruning based on age and usage
392
long cutoffTime = System.currentTimeMillis() - (30 * 24 * 60 * 60 * 1000L); // 30 days
393

394
List<Image> candidatesForPruning = allImages.stream()
395
    .filter(image -> {
396
        String created = image.getDockerImageMetadata().getCreated();
397
        // Parse created timestamp and compare with cutoff
398
        return parseTimestamp(created) < cutoffTime;
399
    })
400
    .collect(Collectors.toList());
401
```
402

403
## Usage Examples
404

405
### Complete Image Management Example
406

407
```java
408
import io.fabric8.openshift.client.OpenShiftClient;
409
import io.fabric8.openshift.api.model.*;
410

411
public class ImageManager {
412
    private final OpenShiftClient client;
413
    
414
    public ImageManager(OpenShiftClient client) {
415
        this.client = client;
416
    }
417
    
418
    public void setupApplicationImages(String namespace, String appName, 
419
                                    String externalImage) {
420
        // 1. Create image stream
421
        ImageStream imageStream = createImageStream(namespace, appName);
422
        
423
        // 2. Import external image
424
        importExternalImage(namespace, appName, externalImage, "latest");
425
        
426
        // 3. Create additional tags
427
        createTag(namespace, appName, "stable", "latest");
428
        
429
        // 4. Monitor import status
430
        waitForImageImport(namespace, appName, "latest");
431
        
432
        System.out.println("Image setup completed for " + appName);
433
    }
434
    
435
    private ImageStream createImageStream(String namespace, String appName) {
436
        ImageStream existing = client.imageStreams()
437
            .inNamespace(namespace)
438
            .withName(appName)
439
            .get();
440
            
441
        if (existing != null) {
442
            return existing;
443
        }
444
        
445
        return client.imageStreams()
446
            .inNamespace(namespace)
447
            .create(new ImageStreamBuilder()
448
                .withNewMetadata()
449
                    .withName(appName)
450
                    .withNamespace(namespace)
451
                    .addToLabels("app", appName)
452
                .endMetadata()
453
                .withNewSpec()
454
                    .withLookupPolicy(new ImageLookupPolicyBuilder()
455
                        .withLocal(true)
456
                        .build())
457
                .endSpec()
458
                .build());
459
    }
460
    
461
    private void importExternalImage(String namespace, String appName, 
462
                                   String externalImage, String tag) {
463
        ImageStreamImport imageImport = new ImageStreamImportBuilder()
464
            .withNewMetadata()
465
                .withName(appName)
466
                .withNamespace(namespace)
467
            .endMetadata()
468
            .withNewSpec()
469
                .withImport(true)
470
                .addNewImage()
471
                    .withNewFrom()
472
                        .withKind("DockerImage")
473
                        .withName(externalImage)
474
                    .endFrom()
475
                    .withNewTo()
476
                        .withName(tag)
477
                    .endTo()
478
                    .withNewImportPolicy()
479
                        .withInsecure(false)
480
                        .withScheduled(false)
481
                    .endImportPolicy()
482
                .endImage()
483
            .endSpec()
484
            .build();
485
            
486
        ImageStreamImport result = client.imageStreamImports()
487
            .inNamespace(namespace)
488
            .create(imageImport);
489
            
490
        // Check import status
491
        if (result.getStatus() != null && result.getStatus().getImages() != null) {
492
            result.getStatus().getImages().forEach(imageStatus -> {
493
                if (imageStatus.getStatus().getStatus().equals("Success")) {
494
                    System.out.println("Successfully imported: " + 
495
                        imageStatus.getTag());
496
                } else {
497
                    System.err.println("Failed to import " + imageStatus.getTag() + 
498
                        ": " + imageStatus.getStatus().getMessage());
499
                }
500
            });
501
        }
502
    }
503
    
504
    private void createTag(String namespace, String appName, 
505
                          String newTag, String sourceTag) {
506
        client.imageStreamTags()
507
            .inNamespace(namespace)
508
            .create(new ImageStreamTagBuilder()
509
                .withNewMetadata()
510
                    .withName(appName + ":" + newTag)
511
                    .withNamespace(namespace)
512
                .endMetadata()
513
                .withNewTag()
514
                    .withNewFrom()
515
                        .withKind("ImageStreamTag")
516
                        .withName(appName + ":" + sourceTag)
517
                        .withNamespace(namespace)
518
                    .endFrom()
519
                .endTag()
520
                .build());
521
    }
522
    
523
    private void waitForImageImport(String namespace, String appName, String tag) {
524
        client.imageStreams()
525
            .inNamespace(namespace)
526
            .withName(appName)
527
            .waitUntilCondition(imageStream -> {
528
                if (imageStream.getStatus() == null || 
529
                    imageStream.getStatus().getTags() == null) {
530
                    return false;
531
                }
532
                
533
                return imageStream.getStatus().getTags().stream()
534
                    .anyMatch(namedTag -> 
535
                        tag.equals(namedTag.getTag()) && 
536
                        !namedTag.getItems().isEmpty());
537
            }, 5, TimeUnit.MINUTES);
538
    }
539
    
540
    public void promoteImage(String namespace, String appName, 
541
                           String fromTag, String toTag) {
542
        // Promote image from one tag to another
543
        ImageStreamTag sourceTag = client.imageStreamTags()
544
            .inNamespace(namespace)
545
            .withName(appName + ":" + fromTag)
546
            .get();
547
            
548
        if (sourceTag == null) {
549
            throw new RuntimeException("Source tag not found: " + fromTag);
550
        }
551
        
552
        client.imageStreamTags()
553
            .inNamespace(namespace)
554
            .createOrReplace(new ImageStreamTagBuilder()
555
                .withNewMetadata()
556
                    .withName(appName + ":" + toTag)
557
                    .withNamespace(namespace)
558
                .endMetadata()
559
                .withNewTag()
560
                    .withNewFrom()
561
                        .withKind("ImageStreamImage")
562
                        .withName(appName + "@" + sourceTag.getImage().getName())
563
                        .withNamespace(namespace)
564
                    .endFrom()
565
                .endTag()
566
                .build());
567
                
568
        System.out.println("Promoted " + fromTag + " to " + toTag);
569
    }
570
}
571
```
572

573
## Types
574

575
### Image
576

577
```java { .api }
578
public class Image implements HasMetadata {
579
    public ObjectMeta getMetadata();
580
    public String getDockerImageReference();
581
    public ObjectMeta getDockerImageMetadata();
582
    public List<ImageLayer> getDockerImageLayers();
583
    public String getDockerImageManifest();
584
    public String getDockerImageManifestMediaType();
585
    public ImageSignature getSignatures();
586
}
587

588
public class ImageLayer {
589
    public String getName();
590
    public Long getSize();
591
    public String getMediaType();
592
}
593
```
594

595
### ImageStream
596

597
```java { .api }
598
public class ImageStream implements HasMetadata {
599
    public ObjectMeta getMetadata();
600
    public ImageStreamSpec getSpec();
601
    public ImageStreamStatus getStatus();
602
}
603

604
public class ImageStreamSpec {
605
    public ImageLookupPolicy getLookupPolicy();
606
    public List<TagReference> getTags();
607
}
608

609
public class ImageStreamStatus {
610
    public String getDockerImageRepository();
611
    public String getPublicDockerImageRepository();
612
    public List<NamedTagEventList> getTags();
613
}
614

615
public class TagReference {
616
    public String getName();
617
    public ObjectReference getFrom();
618
    public TagReferencePolicy getReferencePolicy();
619
    public String getGeneration();
620
    public TagImportPolicy getImportPolicy();
621
}
622
```
623

624
### ImageStreamTag
625

626
```java { .api }
627
public class ImageStreamTag implements HasMetadata {
628
    public ObjectMeta getMetadata();
629
    public TagReference getTag();
630
    public String getGeneration();
631
    public List<TagCondition> getConditions();
632
    public Image getImage();
633
}
634

635
public class TagCondition {
636
    public String getType();  // ImportSuccess
637
    public String getStatus(); // True, False, Unknown
638
    public String getLastTransitionTime();
639
    public String getReason();
640
    public String getMessage();
641
    public String getGeneration();
642
}
643
```
644

645
### ImageStreamImport
646

647
```java { .api }
648
public class ImageStreamImport implements HasMetadata {
649
    public ObjectMeta getMetadata();
650
    public ImageStreamImportSpec getSpec();
651
    public ImageStreamImportStatus getStatus();
652
}
653

654
public class ImageStreamImportSpec {
655
    public Boolean getImport();
656
    public RepositoryImportSpec getRepository();
657
    public List<ImageImportSpec> getImages();
658
}
659

660
public class ImageImportSpec {
661
    public ObjectReference getFrom();
662
    public LocalObjectReference getTo();
663
    public TagImportPolicy getImportPolicy();
664
    public Boolean getIncludeManifest();
665
    public TagReferencePolicy getReferencePolicy();
666
}
667
```