An image is basically an object that can be used to deploy an operating system to an OpenShift container, such as a Linux Red Hat operating system. These are typically small, lightweight operating systems that just contain the core features needed to run the operating system in an OpenShift container. Often, images come precompiled with certain features. For example, a Python image would contain the requirements needed to run a Python application in the container. A Node.js image would contain the requirements needed to run a Node.js application in the container.

A deployment includes a certain image and the deployment creates a replica set (which is the number of pods that should be created) and then the replica set should spawn pods, and each pod should include a container. The container runs the operating system.

If you are not familiar with the oc command, refer to OpenShift - Getting Started with the oc command.

The oc new-app command is used to deploy an application.

There are various ways to deploy an app.

• From GitHub (https://github.com)
• From Docker Hub (https://hub.docker.com)
• From an image
• From an image stream (this article)
• From a build
• From a template
• From a JSON or YAML file (templates)

An image stream doesn't have anything to do with "streaming" services like Spotify (to stream music) or Netflix (to stream movies). Instead, an image stream will list similar images. For example, let's say you have a handful of Python images.

~]$ oc get images | grep -i python
sha256:0c2f708b4977469d090719d939778eb95b42c02c1da6476aa95f2e875920652b   registry.redhat.io/ubi9/python-39@sha256:0c2f708b4977469d090719d939778eb95b42c02c1da6476aa95f2e875920652b
sha256:190ea81f2f64ccf7f7c8cb9dc4612eda59eb9e3d2e17f71727a270f078f5114a   registry.redhat.io/ubi8/python-27@sha256:190ea81f2f64ccf7f7c8cb9dc4612eda59eb9e3d2e17f71727a270f078f5114a
sha256:47107ded2aac95702535be963e2718e58d45bcecb3d4e582bd58bd35f6fc6bc3   registry.redhat.io/ubi9/python-311@sha256:47107ded2aac95702535be963e2718e58d45bcecb3d4e582bd58bd35f6fc6bc3
sha256:4a1d451e1d513115ff54c6e80299e761f60454b5f2f091f3c9ddb9fc1d61f5c4   registry.redhat.io/ubi8/python-38@sha256:4a1d451e1d513115ff54c6e80299e761f60454b5f2f091f3c9ddb9fc1d61f5c4
sha256:6df3bd281d63d839a6f82c85e71d0252ee80a294175ba8c7a4bef61a9b22efe4   registry.redhat.io/ubi8/python-311@sha256:6df3bd281d63d839a6f82c85e71d0252ee80a294175ba8c7a4bef61a9b22efe4
sha256:971dcd27c3d53f58eb59c946f123223b95662841c1214a394a445380beb75f59   registry.redhat.io/ubi8/python-36@sha256:971dcd27c3d53f58eb59c946f123223b95662841c1214a394a445380beb75f59
sha256:d4e20aa826660f635fad77837b9c6aab8248f0560cd8c3c2283c12704359e9bb   registry.redhat.io/rhscl/python-38-rhel7@sha256:d4e20aa826660f635fad77837b9c6aab8248f0560cd8c3c2283c12704359e9bb
sha256:e2a461928e82d7da8991f4fdf5496219f013a6e70c4ef30cf5fb93a4cc450eac   registry.redhat.io/ubi8/python-39@sha256:e2a461928e82d7da8991f4fdf5496219f013a6e70c4ef30cf5fb93a4cc450eac

You could then have a python image stream that contains the Python images. Notice in this example that there are TAGS.

]$ oc get imagestream python --namespace openshift
NAME     IMAGE REPOSITORY                                                    TAGS                                              UPDATED
python   image-registry.openshift-image-registry.svc:5000/openshift/python   3.11-ubi8,3.11-ubi9,latest,2.7-ubi8 + 6 more...   3 months ago

jsonpath can be used to list each tag. There is a tag for each Python image.

]$ oc get imagestream python --namespace openshift --output jsonpath="{.spec.tags[*].name}"
2.7-ubi8 3.11-ubi8 3.11-ubi9 3.6-ubi8 3.8 3.8-ubi7 3.8-ubi8 3.9-ubi8 3.9-ubi9 latest

Notice in this example that the python image stream with the latest tag references the 3.11-ubi8 image (registry.redhat.io/ubi8/python-311@sha256:6df3bd281d63d839a6f82c85e71d0252ee80a294175ba8c7a4bef61a9b22efe4).

~]$ oc get imagestream python --namespace openshift --output yaml
spec:
  tags:
  - annotations:
      description: |-
        Build and run Python applications on UBI. For more information about using this builder image, including OpenShift considerations, see https://github.com/sclorg/s2i-python-container/blob/master/3.11/README.md.

        WARNING: By selecting this tag, your application will automatically update to use the latest version of Python available on OpenShift, including major version updates.
      iconClass: icon-python
      openshift.io/display-name: Python (Latest)
      openshift.io/provider-display-name: Red Hat, Inc.
      sampleRepo: https://github.com/sclorg/django-ex.git
      supports: python
      tags: builder,python
    from:
      kind: ImageStreamTag
      name: 3.11-ubi8
    generation: 3
    importPolicy:
      importMode: Legacy
    name: latest
    referencePolicy:
      type: Local

You could then create a deployment using the oc new-app command and specify that the image stream named python should be used.

oc new-app --image-stream python --namespace my-project

There should now be a deployment named python.

]$ oc get deployments --namespace my-project
NAME     READY   UP-TO-DATE   AVAILABLE   AGE
python   1/1     1            1           2m3s

And the deployment YAML should be using the latest python image stream.

~]$ oc get deployment python --namespace my-project --output yaml
spec:
  template:
    spec:
      containers:
      - image: image-registry.openshift-image-registry.svc:5000/openshift/python@sha256:6df3bd281d63d839a6f82c85e71d0252ee80a294175ba8c7a4bef61a9b22efe4
        imagePullPolicy: IfNotPresent
        name: python

Now let's say the latest python image stream is updated to point a different python image. For example, perhaps the python image stream is updated to point to the 3.11-ubi9 image (registry.redhat.io/ubi9/python-311@sha256:47107ded2aac95702535be963e2718e58d45bcecb3d4e582bd58bd35f6fc6bc3). Each deployment using the latest python image would use the 3.11-ubi9 image the next time the deployment spawns new pods.

This may not be what you want. For example, if the Python application was optimized to run on Python version 3.9 you may want to ensure the Python application uses a Python 3.9 image. You can specify a certain tag so that the deployment uses the image stream with the tag.

oc new-app --image-stream python:3.9-ubi8 --namespace my-project

Notice in this example that the python deployment is not using the image with sha256:e2a461928e82d7da8991f4fdf5496219f013a6e70c4ef30cf5fb93a4cc450eacwhich is the image for Python 3.9-ubi8.

~]$ oc get deployment python --namespace my-project --output yaml
spec:
  template:
    spec:
      containers:
      - image: image-registry.openshift-image-registry.svc:5000/openshift/python@sha256:e2a461928e82d7da8991f4fdf5496219f013a6e70c4ef30cf5fb93a4cc450eac
        imagePullPolicy: IfNotPresent
        name: python

By the way, the image-registry deployment in the image-registry namespace contains the REGISTRY_OPENSHIFT_SERVER_ADDR environment variable which contains the image registry base URL.

~]$ oc get deployment image-registry --namespace openshift-image-registry --output yaml
spec:
  template:
    spec:
      containers:
        env:
        - name: REGISTRY_OPENSHIFT_SERVER_ADDR
          value: image-registry.openshift-image-registry.svc:5000