Chapter 6. Managing image streams Image streams provide a means of creating and updating container images in an on-going way. As improvements are made to an image, tags can be used to assign new version numbers and keep track of changes. This document describes how image streams are managed. 6.1. Why use imagestreams An image stream and its associated tags provide an abstraction for referencing container images from within Red Hat OpenShift Service on AWS. The image stream and its tags allow you to see what images are available and ensure that you are using the specific image you need even if the image in the repository changes. Image streams do not contain actual image data, but present a single virtual view of related images, similar to an image repository. You can configure builds and deployments to watch an image stream for notifications when new images are added and react by performing a build or deployment, respectively. For example, if a deployment is using a certain image and a new version of that image is created, a deployment could be automatically performed to pick up the new version of the image. However, if the image stream tag used by the deployment or build is not updated, then even if the container image in the container image registry is updated, the build or deployment continues using the , presumably known good image. The source images can be stored in any of the following: Red Hat OpenShift Service on AWS's integrated registry. An external registry, for example registry.redhat.io or quay.io. Other image streams in the Red Hat OpenShift Service on AWS cluster. When you define an object that references an image stream tag, such as a build or deployment configuration, you point to an image stream tag and not the repository. When you build or deploy your application, Red Hat OpenShift Service on AWS queries the repository using the image stream tag to locate the associated ID of the image and uses that exact image. The image stream metadata is stored in the etcd instance along with other cluster information. Using image streams has several significant benefits: You can tag, rollback a tag, and quickly deal with images, without having to re-push using the command line. You can trigger builds and deployments when a new image is pushed to the registry. Also, Red Hat OpenShift Service on AWS has generic triggers for other resources, such as Kubernetes objects. You can mark a tag for periodic re-import. If the source image has changed, that change is picked up and reflected in the image stream, which triggers the build or deployment flow, depending upon the build or deployment configuration. You can share images using fine-grained access control and quickly distribute images across your teams. If the source image changes, the image stream tag still points to a known-good version of the image, ensuring that your application does not break unexpectedly. You can configure security around who can view and use the images through permissions on the image stream objects. Users that lack permission to read or list images on the cluster level can still retrieve the images tagged in a project using image streams. 6.2. Configuring image streams An ImageStream object file contains the following elements. Imagestream object definition apiVersion: image.openshift.io/v1 kind: ImageStream metadata: annotations: openshift.io/generated-by: OpenShiftNewApp labels: app: ruby-sample-build template: application-template-stibuild name: origin-ruby-sample 1 namespace: test spec: {} status: dockerImageRepository: 172.30.56.218:5000/test/origin-ruby-sample 2 tags: - items: - created: 2017-09-02T10:15:09Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d 3 generation: 2 image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 4 - created: 2017-09-01T13:40:11Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 generation: 1 image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d tag: latest 5 1 The name of the image stream. 2 Docker repository path where new images can be pushed to add or update them in this image stream. 3 The SHA identifier that this image stream tag currently references. Resources that reference this image stream tag use this identifier. 4 The SHA identifier that this image stream tag previously referenced. Can be used to rollback to an older image. 5 The image stream tag name. 6.3. Image stream images An image stream image points from within an image stream to a particular image ID. Image stream images allow you to retrieve metadata about an image from a particular image stream where it is tagged. Image stream image objects are automatically created in Red Hat OpenShift Service on AWS whenever you import or tag an image into the image stream. You should never have to explicitly define an image stream image object in any image stream definition that you use to create image streams. The image stream image consists of the image stream name and image ID from the repository, delimited by an @ sign: To refer to the image in the ImageStream object example, the image stream image looks like: 6.4. Image stream tags An image stream tag is a named pointer to an image in an image stream. It is abbreviated as istag . An image stream tag is used to reference or retrieve an image for a given image stream and tag. Image stream tags can reference any local or externally managed image. It contains a history of images represented as a stack of all images the tag ever pointed to. Whenever a new or existing image is tagged under particular image stream tag, it is placed at the first position in the history stack. The image previously occupying the top position is available at the second position. This allows for easy rollbacks to make tags point to historical images again. The following image stream tag is from an ImageStream object: Image stream tag with two images in its history kind: ImageStream apiVersion: image.openshift.io/v1 metadata: name: my-image-stream # ... tags: - items: - created: 2017-09-02T10:15:09Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d generation: 2 image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 - created: 2017-09-01T13:40:11Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 generation: 1 image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d tag: latest # ... Image stream tags can be permanent tags or tracking tags. Permanent tags are version-specific tags that point to a particular version of an image, such as Python 3.5. Tracking tags are reference tags that follow another image stream tag and can be updated to change which image they follow, like a symlink. These new levels are not guaranteed to be backwards-compatible. For example, the latest image stream tags that ship with Red Hat OpenShift Service on AWS are tracking tags. This means consumers of the latest image stream tag are updated to the newest level of the framework provided by the image when a new level becomes available. A latest image stream tag to v3.10 can be changed to v3.11 at any time. It is important to be aware that these latest image stream tags behave differently than the Docker latest tag. The latest image stream tag, in this case, does not point to the latest image in the Docker repository. It points to another image stream tag, which might not be the latest version of an image. For example, if the latest image stream tag points to v3.10 of an image, when the 3.11 version is released, the latest tag is not automatically updated to v3.11 , and remains at v3.10 until it is manually updated to point to a v3.11 image stream tag. Note Tracking tags are limited to a single image stream and cannot reference other image streams. You can create your own image stream tags for your own needs. The image stream tag is composed of the name of the image stream and a tag, separated by a colon: For example, to refer to the sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d image in the ImageStream object example earlier, the image stream tag would be: 6.5. Image stream change triggers Image stream triggers allow your builds and deployments to be automatically invoked when a new version of an upstream image is available. For example, builds and deployments can be automatically started when an image stream tag is modified. This is achieved by monitoring that particular image stream tag and notifying the build or deployment when a change is detected. 6.6. Working with image streams The following sections describe how to use image streams and image stream tags. Important Do not run workloads in or share access to default projects. Default projects are reserved for running core cluster components. The following default projects are considered highly privileged: default , kube-public , kube-system , openshift , openshift-infra , openshift-node , and other system-created projects that have the openshift.io/run-level label set to 0 or 1 . Functionality that relies on admission plugins, such as pod security admission, security context constraints, cluster resource quotas, and image reference resolution, does not work in highly privileged projects. 6.6.1. Getting information about image streams You can get general information about the image stream and detailed information about all the tags it is pointing to. Procedure To get general information about the image stream and detailed information about all the tags it is pointing to, enter the following command: USD oc describe is/<image-name> For example: USD oc describe is/python Example output Name: python Namespace: default Created: About a minute ago Labels: <none> Annotations: openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z Docker Pull Spec: docker-registry.default.svc:5000/default/python Image Lookup: local=false Unique Images: 1 Tags: 1 3.5 tagged from centos/python-35-centos7 * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 About a minute ago To get all of the information available about a particular image stream tag, enter the following command: USD oc describe istag/<image-stream>:<tag-name> For example: USD oc describe istag/python:latest Example output Image Name: sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 Docker Image: centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 Name: sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 Created: 2 minutes ago Image Size: 251.2 MB (first layer 2.898 MB, last binary layer 72.26 MB) Image Created: 2 weeks ago Author: <none> Arch: amd64 Entrypoint: container-entrypoint Command: /bin/sh -c USDSTI_SCRIPTS_PATH/usage Working Dir: /opt/app-root/src User: 1001 Exposes Ports: 8080/tcp Docker Labels: build-date=20170801 Note More information is output than shown. Enter the following command to discover which architecture or operating system that an image stream tag supports: USD oc get istag <image-stream-tag> -ojsonpath="{range .image.dockerImageManifests[*]}{.os}/{.architecture}{'\n'}{end}" For example: USD oc get istag busybox:latest -ojsonpath="{range .image.dockerImageManifests[*]}{.os}/{.architecture}{'\n'}{end}" Example output linux/amd64 linux/arm linux/arm64 linux/386 linux/mips64le linux/ppc64le linux/riscv64 linux/s390x 6.6.2. Adding tags to an image stream You can add additional tags to image streams. Procedure Add a tag that points to one of the existing tags by using the `oc tag`command: USD oc tag <image-name:tag1> <image-name:tag2> For example: USD oc tag python:3.5 python:latest Example output Tag python:latest set to python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25. Confirm the image stream has two tags, one, 3.5 , pointing at the external container image and another tag, latest , pointing to the same image because it was created based on the first tag. USD oc describe is/python Example output Name: python Namespace: default Created: 5 minutes ago Labels: <none> Annotations: openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z Docker Pull Spec: docker-registry.default.svc:5000/default/python Image Lookup: local=false Unique Images: 1 Tags: 2 latest tagged from python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 About a minute ago 3.5 tagged from centos/python-35-centos7 * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 5 minutes ago 6.6.3. Adding tags for an external image You can add tags for external images. Procedure Add tags pointing to internal or external images, by using the oc tag command for all tag-related operations: USD oc tag <repository/image> <image-name:tag> For example, this command maps the docker.io/python:3.6.0 image to the 3.6 tag in the python image stream. USD oc tag docker.io/python:3.6.0 python:3.6 Example output Tag python:3.6 set to docker.io/python:3.6.0. If the external image is secured, you must create a secret with credentials for accessing that registry. 6.6.4. Updating image stream tags You can update a tag to reflect another tag in an image stream. Procedure Update a tag: USD oc tag <image-name:tag> <image-name:latest> For example, the following updates the latest tag to reflect the 3.6 tag in an image stream: USD oc tag python:3.6 python:latest Example output Tag python:latest set to python@sha256:438208801c4806548460b27bd1fbcb7bb188273d13871ab43f. 6.6.5. Removing image stream tags You can remove old tags from an image stream. Procedure Remove old tags from an image stream: USD oc tag -d <image-name:tag> For example: USD oc tag -d python:3.6 Example output Deleted tag default/python:3.6 See Removing deprecated image stream tags from the Cluster Samples Operator for more information on how the Cluster Samples Operator handles deprecated image stream tags. 6.6.6. Configuring periodic importing of image stream tags When working with an external container image registry, to periodically re-import an image, for example to get latest security updates, you can use the --scheduled flag. Procedure Schedule importing images: USD oc tag <repository/image> <image-name:tag> --scheduled For example: USD oc tag docker.io/python:3.6.0 python:3.6 --scheduled Example output Tag python:3.6 set to import docker.io/python:3.6.0 periodically. This command causes Red Hat OpenShift Service on AWS to periodically update this particular image stream tag. This period is a cluster-wide setting set to 15 minutes by default. Remove the periodic check, re-run above command but omit the --scheduled flag. This will reset its behavior to default. USD oc tag <repositiory/image> <image-name:tag> 6.7. Importing and working with images and image streams The following sections describe how to import, and work with, image streams. 6.7.1. Importing images and image streams from private registries An image stream can be configured to import tag and image metadata from private image registries requiring authentication. This procedures applies if you change the registry that the Cluster Samples Operator uses to pull content from to something other than registry.redhat.io . Note When importing from insecure or secure registries, the registry URL defined in the secret must include the :80 port suffix or the secret is not used when attempting to import from the registry. Procedure You must create a secret object that is used to store your credentials by entering the following command: USD oc create secret generic <secret_name> --from-file=.dockerconfigjson=<file_absolute_path> --type=kubernetes.io/dockerconfigjson After the secret is configured, create the new image stream or enter the oc import-image command: USD oc import-image <imagestreamtag> --from=<image> --confirm During the import process, Red Hat OpenShift Service on AWS picks up the secrets and provides them to the remote party. 6.7.2. Working with manifest lists You can import a single sub-manifest, or all manifests, of a manifest list when using oc import-image or oc tag CLI commands by adding the --import-mode flag. Refer to the commands below to create an image stream that includes a single sub-manifest or multi-architecture images. Procedure Create an image stream that includes multi-architecture images, and sets the import mode to PreserveOriginal , by entering the following command: USD oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> \ --import-mode='PreserveOriginal' --reference-policy=local --confirm Example output --- Arch: <none> Manifests: linux/amd64 sha256:6e325b86566fafd3c4683a05a219c30c421fbccbf8d87ab9d20d4ec1131c3451 linux/arm64 sha256:d8fad562ffa75b96212c4a6dc81faf327d67714ed85475bf642729703a2b5bf6 linux/ppc64le sha256:7b7e25338e40d8bdeb1b28e37fef5e64f0afd412530b257f5b02b30851f416e1 --- Alternatively, enter the following command to import an image with the Legacy import mode, which discards manifest lists and imports a single sub-manifest: USD oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> \ --import-mode='Legacy' --confirm Note The --import-mode= default value is Legacy . Excluding this value, or failing to specify either Legacy or PreserveOriginal , imports a single sub-manifest. An invalid import mode returns the following error: error: valid ImportMode values are Legacy or PreserveOriginal . Limitations Working with manifest lists has the following limitations: In some cases, users might want to use sub-manifests directly. When oc adm prune images is run, or the CronJob pruner runs, they cannot detect when a sub-manifest list is used. As a result, an administrator using oc adm prune images , or the CronJob pruner, might delete entire manifest lists, including sub-manifests. To avoid this limitation, you can use the manifest list by tag or by digest instead. 6.7.2.1. Configuring periodic importing of manifest lists To periodically re-import a manifest list, you can use the --scheduled flag. Procedure Set the image stream to periodically update the manifest list by entering the following command: USD oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> \ --import-mode='PreserveOriginal' --scheduled=true 6.7.2.2. Configuring SSL/TSL when importing manifest lists To configure SSL/TSL when importing a manifest list, you can use the --insecure flag. Procedure Set --insecure=true so that importing a manifest list skips SSL/TSL verification. For example: USD oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> \ --import-mode='PreserveOriginal' --insecure=true 6.7.3. Specifying architecture for --import-mode You can swap your imported image stream between multi-architecture and single architecture by excluding or including the --import-mode= flag Procedure Run the following command to update your image stream from multi-architecture to single architecture by excluding the --import-mode= flag: USD oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> Run the following command to update your image stream from single-architecture to multi-architecture: USD oc import-image <multiarch_image_stream_tag> --from=<registry>/<project_name>/<image_name> \ --import-mode='PreserveOriginal' 6.7.4. Configuration fields for --import-mode The following table describes the options available for the --import-mode= flag: Parameter Description Legacy The default option for --import-mode . When specified, the manifest list is discarded, and a single sub-manifest is imported. The platform is chosen in the following order of priority: Tag annotations Control plane architecture Linux/AMD64 The first manifest in the list PreserveOriginal When specified, the original manifest is preserved. For manifest lists, the manifest list and all of its sub-manifests are imported.

Commands:
apiVersion: image.openshift.io/v1 kind: ImageStream metadata: annotations: openshift.io/generated-by: OpenShiftNewApp labels: app: ruby-sample-build template: application-template-stibuild name: origin-ruby-sample 1 namespace: test spec: {} status: dockerImageRepository: 172.30.56.218:5000/test/origin-ruby-sample 2 tags: - items: - created: 2017-09-02T10:15:09Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d 3 generation: 2 image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 4 - created: 2017-09-01T13:40:11Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 generation: 1 image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d tag: latest 5
<image-stream-name>@<image-id>
origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d
kind: ImageStream apiVersion: image.openshift.io/v1 metadata: name: my-image-stream tags: - items: - created: 2017-09-02T10:15:09Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d generation: 2 image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 - created: 2017-09-01T13:40:11Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 generation: 1 image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d tag: latest
<imagestream name>:<tag>
origin-ruby-sample:latest
oc describe is/<image-name>
oc describe is/python
Name: python Namespace: default Created: About a minute ago Labels: <none> Annotations: openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z Docker Pull Spec: docker-registry.default.svc:5000/default/python Image Lookup: local=false Unique Images: 1 Tags: 1 3.5 tagged from centos/python-35-centos7 * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 About a minute ago
oc describe istag/<image-stream>:<tag-name>
oc describe istag/python:latest
Image Name: sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 Docker Image: centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 Name: sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 Created: 2 minutes ago Image Size: 251.2 MB (first layer 2.898 MB, last binary layer 72.26 MB) Image Created: 2 weeks ago Author: <none> Arch: amd64 Entrypoint: container-entrypoint Command: /bin/sh -c USDSTI_SCRIPTS_PATH/usage Working Dir: /opt/app-root/src User: 1001 Exposes Ports: 8080/tcp Docker Labels: build-date=20170801
oc get istag <image-stream-tag> -ojsonpath="{range .image.dockerImageManifests[*]}{.os}/{.architecture}{'\n'}{end}"
oc get istag busybox:latest -ojsonpath="{range .image.dockerImageManifests[*]}{.os}/{.architecture}{'\n'}{end}"
linux/amd64 linux/arm linux/arm64 linux/386 linux/mips64le linux/ppc64le linux/riscv64 linux/s390x
oc tag <image-name:tag1> <image-name:tag2>
oc tag python:3.5 python:latest
Tag python:latest set to python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25.
oc describe is/python
Name: python Namespace: default Created: 5 minutes ago Labels: <none> Annotations: openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z Docker Pull Spec: docker-registry.default.svc:5000/default/python Image Lookup: local=false Unique Images: 1 Tags: 2 latest tagged from python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 About a minute ago 3.5 tagged from centos/python-35-centos7 * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 5 minutes ago
oc tag <repository/image> <image-name:tag>
oc tag docker.io/python:3.6.0 python:3.6
Tag python:3.6 set to docker.io/python:3.6.0.
oc tag <image-name:tag> <image-name:latest>
oc tag python:3.6 python:latest
Tag python:latest set to python@sha256:438208801c4806548460b27bd1fbcb7bb188273d13871ab43f.
oc tag -d <image-name:tag>
oc tag -d python:3.6
Deleted tag default/python:3.6
oc tag <repository/image> <image-name:tag> --scheduled
oc tag docker.io/python:3.6.0 python:3.6 --scheduled
Tag python:3.6 set to import docker.io/python:3.6.0 periodically.
oc tag <repositiory/image> <image-name:tag>
oc create secret generic <secret_name> --from-file=.dockerconfigjson=<file_absolute_path> --type=kubernetes.io/dockerconfigjson
oc import-image <imagestreamtag> --from=<image> --confirm
oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> --import-mode='PreserveOriginal' --reference-policy=local --confirm
--- Arch: <none> Manifests: linux/amd64 sha256:6e325b86566fafd3c4683a05a219c30c421fbccbf8d87ab9d20d4ec1131c3451 linux/arm64 sha256:d8fad562ffa75b96212c4a6dc81faf327d67714ed85475bf642729703a2b5bf6 linux/ppc64le sha256:7b7e25338e40d8bdeb1b28e37fef5e64f0afd412530b257f5b02b30851f416e1 ---
oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> --import-mode='Legacy' --confirm
oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> --import-mode='PreserveOriginal' --scheduled=true
oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name> --import-mode='PreserveOriginal' --insecure=true
oc import-image <multiarch-image-stream-tag> --from=<registry>/<project_name>/<image-name>
oc import-image <multiarch_image_stream_tag> --from=<registry>/<project_name>/<image_name> --import-mode='PreserveOriginal'