Builds and Image Streams
Builds
A build is the process of transforming input parameters into a resulting object. Most often, the process is used to transform input parameters or source code into a runnable image. A BuildConfig object is the definition of the entire build process.
OpenShift leverages Kubernetes by creating Docker containers from build images and pushing them to a Docker registry.
Build objects share common characteristics: inputs for a build, the need to complete a build process, logging the build process, publishing resources from successful builds, and publishing the final status of the build. Builds take advantage of resource restrictions, specifying limitations on resources such as CPU usage, memory usage, and build or pod execution time.
The OpenShift build system provides extensible support for build strategies that are based on selectable types specified in the build API. There are three build strategies available:
By default, Docker builds and S2I builds are supported.
The resulting object of a build depends on the builder used to create it. For Docker and S2I builds, the resulting objects are runnable images. For Custom builds, the resulting objects are whatever the builder image author has specified.
For a list of build commands, see the Developer’s Guide.
For more information on how OpenShift leverages Docker for builds, see the upstream documentation.
Docker Build
The Docker build strategy invokes the plain docker build command, and it therefore expects a repository with a Dockerfile and all required artifacts in it to produce a runnable image.
Source-to-Image (S2I) Build
Source-to-Image (S2I) is a tool for building reproducible Docker images. It produces ready-to-run images by injecting application source into a Docker image and assembling a new Docker image. The new image incorporates the base image (the builder) and built source and is ready to use with the docker run command. S2I supports incremental builds, which re-use previously downloaded dependencies, previously built artifacts, etc.
The advantages of S2I include the following:
S2I scripts can be written to inject application code into almost any existing Docker image, taking advantage of the existing ecosystem. Note that, currently, S2I relies on tar to inject application source, so the image needs to be able to process tarred content.
With S2I, the assemble process can perform a large number of complex operations without creating a new layer at each step, resulting in a fast process. In addition, S2I scripts can be written to re-use artifacts stored in a previous version of the application image, rather than having to download or build them each time the build is run.
S2I allows you to rebuild the application consistently if an underlying image needs a patch due to a security issue.
By restricting build operations instead of allowing arbitrary actions, as a Dockerfile would allow, the PaaS operator can avoid accidental or intentional abuses of the build system.
Building an arbitrary Dockerfile exposes the host system to root privilege escalation. This can be exploited by a malicious user because the entire Docker build process is run as a user with Docker privileges. S2I restricts the operations performed as a root user and can run the scripts as a non-root user.
S2I prevents developers from performing arbitrary yum install type operations, which could slow down development iteration, during their application build.
S2I encourages a shared ecosystem of images where you can leverage best practices for your applications.
Custom Build
The Custom build strategy allows developers to define a specific builder image responsible for the entire build process. Using your own builder image allows you to customize your build process.
The Custom builder image is a plain Docker image with embedded build process logic, such as building RPMs or building base Docker images. The openshift/origin-custom-docker-builder image is used by default.
Image Streams
An image stream can be used to automatically perform an action, such as updating a deployment, when a new image, such as a new version of the base image that is used in that deployment, is created.
An image stream comprises one or more Docker images identified by tags. It presents a single virtual view of related images, similar to a Docker image repository, and may contain images from any of the following:
Its own image repository in OpenShift’s integrated Docker Registry
Other image streams
Docker image repositories from external registries
OpenShift components such as builds and deployments can watch an image stream to receive notifications when new images are added and react by performing a build or a deployment.
Image Stream Mappings
When the integrated OpenShift Docker Registry receives a new image, it creates and sends an ImageStreamMapping to OpenShift. This informs OpenShift of the image’s namespace, name, tag, and Docker metadata. OpenShift uses this information to create a new image (if it does not already exist) and to tag the image into the image stream. OpenShift stores complete metadata about each image (e.g., command, entrypoint, environment variables, etc.). Note that images in OpenShift are immutable. Also, note that the maximum name length is 63 characters.
Referencing Images in Image Streams
The sample image below is from the ruby image stream and was retrieved by asking for the ImageStreamImage with the name ruby@371829c:
Image Pull Policy
Each container in a pod has a Docker image. Once you have created an image and pushed it to a registry, you can then refer to it in the pod.
When OpenShift creates containers, it uses the container’s imagePullPolicy to determine if the image should be pulled prior to starting the container. There are three possible values for imagePullPolicy :
If a container’s imagePullPolicy parameter is not specified, OpenShift sets it based on the image’s tag:
Importing Tag and Image Metadata
An image stream can be configured to import tag and image metadata from an image repository in an external Docker image registry. See Image Registry for more details.
Tag Tracking
An image stream can also be configured so that a tag «tracks» another one. For example, you can configure the latest tag to always refer to the current image for the tag «2.0»:
Image Streams in OpenShift: What You Need to Know
Updated: 03 August 2021
If you’ve been playing around with OpenShift and kicking the tyres a bit, you might have come across the mysterious object called the image stream.
What is it? (pokes awkwardly at object lying in the corner)
“It’s this thing which seems to make your images available in the cluster, or something?”
Yes, but what exactly are image streams? How do you use them? And what do you really need to know about them?
In this OpenShift image stream tutorial, I’m going to tell you how I understand image streams, and how I use them. Let’s go.
Firstly, the terminology sucks
The name “stream” makes it so confusing. There’s no streaming involved here.
No Netflix, no data streaming.
An image stream is just a set of references (tags) which point to Docker images.
If I could rename image streams, I’d probably call them image references.
What does an image stream do?
An image stream acts as a pointer to a set of images. It’s like a shortcut or a reference.
Image streams are useful
An image stream doesn’t contain the Docker image itself. It’s a signpost to images, which can be in any registry – either OpenShift’s internal registry, or an external one.
I regularly use image streams in builds and deployments on OpenShift.
But what’s the point? Why use them?
Why would you use them?
A single place to reference a set of related images
An image stream is a single pointer to a set of related images.
Whenever you want to deploy an application in a project, instead of having to hardcode the registry URL and tag, you can just refer to the image stream tag.
If the source image changes location in future, you just need to update the image stream definition, instead of updating all your deployments individually!
This is how the Red Hat images work in OpenShift. The Red Hat images are installed as image streams in the openshift project. You can reference them from any other project in the cluster.
When an image changes, trigger a new build or deployment
Image streams can also be used as triggers. This means that you can set an image stream as a source for a Build or a Deployment. When the image changes, this can trigger a new Build, or trigger a redeployment of your app.
Access control for images
You can lock away your images in a private registry and control access to them through image streams.
Because image streams are like other objects in OpenShift, they can be restricted, if you like. So you can restrict images to only be used by specific service accounts.
How do you create an image stream?
Here’s how I would create an image stream using the command line.
Create an image stream using the oc import-image command. Give the image stream a name and then the image you want to import.
This creates an image stream in your project, called approved-apache. It has one tag, 2.4, which points to the tag 2.4 on the image bitnami/apache.
But wait, you didn’t specify a registry?
That’s right. I don’t specify a registry here, because Docker Hub is configured as one of OpenShift’s default search registries. So it’ll search in the Red Hat registry and Docker Hub, which is where it will find the image.
Then the image will be pulled into OpenShift’s internal registry.
If you’re a cluster-admin, you can see the image in the OpenShift registry, by typing oc get images :
Declaring it with YAML
Once you’ve learned how to create image streams using the oc command, you probably want to progress on to creating objects declaratively. This is a much better way to do it, because you can store all of your configuration as files in Git, rather than a bunch of commands.
To do this, you create an ImageStream object in YAML. The YAML for an ImageStream looks something like this:
How do you use an image stream?
The way I use image streams is as sources for Builds and Deployments.
Deploying an image stream
OpenShift will inspect the image to see which ports to expose, and then create a Deployment and a Service for your app.
Let’s import a sample image that I made:
Now I create a Deployment and a Service to deploy it in my project:
Using an image stream as a source image in a build
Or, you can use an image stream as a source for a build.
Here’s an example of a BuildConfig which uses an image stream as a source:
What if your image is in a private registry?
Yep, you can still use image streams if your image is in a private registry.
Firstly, if the registry is password-protected, make sure you create a Secret with your credentials for the external registry, so OpenShift can pull the image.
Here I’m connecting to the registry on the Mars rover (well, maybe one day Mars rovers will run OpenShift):
Then link the secret to your builder and default service accounts:
Now we’re good to import the image, using the oc import-image command:
Congrats! You’ve created an image stream to import an image from a private registry, with authentication.
What about triggering when the source image changes?
If your image stream points to an image in OpenShift’s internal registry (perhaps, like an image you’ve built inside OpenShift), then OpenShift gets notified automatically when your image changes.
When does the image update?
OpenShift will keep checking the image, usually around every 15 minutes (see below for how to change this.)
Wait 15 minutes. Put the kettle on. Whatever it takes to run down the clock.
If a new image is pushed, you’ll see something like this, when you run oc describe is/marsview :
Bingo, the image updated about a minute ago!
Then, as long as your DeploymentConfig is configured with a Trigger of “ImageChange”, it will automatically trigger a redeployment.
Here’s what a DeploymentConfig for this app would look like, with a trigger:
This allows you to implement basic continuous deployment. The moment that a new image is pushed to your latest tag, OpenShift will automatically trigger an update of your app. Fab.
How often are images imported?
How often images are imported, is a cluster-wide setting. Look for these settings in /etc/origin/master/master-config.yaml :
Adding additional tags to the image stream
The new tag doesn’t need to be in the same registry, it could be somewhere else entirely.
Here I’m adding a develop tag to my image stream, pointing to a different registry (registry.spacedev.com):
which will say this:
Tag marsview:develop set to import registry.marsrover.space/engine/marsview:develop periodically.
Job done. Now I can reference the develop tag from my development registry.
TL;DR. Do I really need them?
No, you don’t really need them. But they are useful for:
Creating one place to pull images from external registries, so you don’t have to keep track of everywhere you’re using an image
Creating triggers for your builds and deployments
Understanding how the built-in Red Hat images are installed in the cluster (you’ll see them in the openshift project)
And here are the key terms.
| Term | What it is |
|---|---|
| Image stream | A set of pointers (tags). Each tag points to a Docker image. |
| Image stream tag | A tag within an image stream. The tag points to an individual Docker image in a registry somewhere, either the internal registry or an external one. |
| Image stream image | A pointer from within an image stream, to a particular image ID. Basically lets you get all the details (metadata) of the actual image itself. |
Just….don’t cross the streams! (Bad joke.)
Thanks for reading. Please don’t let this be the end. 💔
It took us this long to find each other. Before you close your browser and forget all about this article, let’s agree to stay in touch? Join my email newsletter. I’ll email you my latest tutorials and guides, so you can read at your leisure! 🏖 (No spam, unsubscribe whenever you want.)
Comments
Got any thoughts on what you’ve just read? Anything wrong, or no longer correct? Sign in with your GitHub account to leave a comment.
(All comments get added as Issues in our GitHub repo here, using the open source comments tool Utterances)
Want more? Read these articles next.
You’ve found the end of another article! Keep on learning by checking out one of these articles:
DevOps Project Ideas: A career in DevOps is all about building a broad skill base and understanding. Use these project ideas to invest in yourself and get that.
4 Ways to do a Dockerfile Build in OpenShift: When you want to build a Docker image in OpenShift using a Dockerfile, here are three ways to do it, with example YAML
14 best practices for containerising your Java applications: Best practices to follow when building and running your Java application in a Docker container
How to Deploy a React app to OpenShift: In this article, we’ll look at how to build and deploy your React application on OpenShift, using your source code, and a Dockerfile.
Kubernetes ImagePullBackOff error: what you need to know: Find out what the ImagePullBackOff error means in Kubernetes, and how to fix it.
Tutorial Works. This is a blog to help you grow your tech career, with tips, tutorials, guides, and real opinions. We focus on DevOps, cloud, containers and a whole lot more.
Thanks for being here! 👋
Copyright © 2021 Tom Donohue. All rights reserved, except where stated.
Managing imagestreams
Imagestreams 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.
Using imagestreams
An imagestream and its associated tags provide an abstraction for referencing container images from within OpenShift Container Platform. The imagestream 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.
Imagestreams 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 imagestream 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 imagestreamtag 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 will continue using the previous, presumably known good image.
The source images can be stored in any of the following:
OpenShift Container Platform’s integrated registry.
Other imagestreams in the OpenShift Container Platform cluster.
When you define an object that references an imagestreamtag (such as a Build or Deployment configuration), you point to an imagestreamtag, not the Docker repository. When you Build or Deploy your application, OpenShift Container Platform queries the Docker repository using the imagestreamtag to locate the associated ID of the image and uses that exact image.
The imagestream metadata is stored in the etcd instance along with other cluster information.
Using imagestreams 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, OpenShift Container Platform 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 imagestream, which triggers the Build and/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 imagestreamtag will still point to a known-good version of the image, ensuring that your application will not break unexpectedly.
You can configure security around who can view and use the images through permissions on the imagestream objects.
Users that lack permission to read or list images on the cluster level can still retrieve the images tagged in a project using imagestreams.
Configuring imagestreams
An imagestream object file contains the following elements.
| The name of the imagestream. |
| Docker repository path where new images can be pushed to add/update them in this imagestream. |
| The SHA identifier that this imagestreamtag currently references. Resources that reference this imagestreamtag use this identifier. |
| The SHA identifier that this imagestreamtag previously referenced. Can be used to rollback to an older image. |
| The imagestreamtag name. |
Imagestream images
An imagestream image points from within an imagestream to a particular image ID.
Imagestream images allow you to retrieve metadata about an image from a particular imagestream where it is tagged.
Imagestream image objects are automatically created in OpenShift Container Platform whenever you import or tag an image into the imagestream. You should never have to explicitly define an imagestream image object in any imagestream definition that you use to create imagestreams.
The imagestream image consists of the imagestream name and image ID from the repository, delimited by an @ sign:
To refer to the image in the imagestream object example, the imagestream image looks like:
Imagestreamtags
An imagestreamtag is a named pointer to an image in an imagestream. It is often abbreviated as istag. An imagestreamtag is used to reference or retrieve an image for a given imagestream and tag.
Imagestreamtags 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 will be available at the second position, and so forth. This allows for easy rollbacks to make tags point to historical images again.
The following imagestreamtag is from an imagestream object:
Imagestreamtags 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 imagestreamtag and could be updated in the future to change which image they follow, much like a symlink. Note that these new levels are not guaranteed to be backwards-compatible.
Tracking tags are limited to a single imagestream and cannot reference other imagestreams.
You can create your own imagestreamtags for your own needs.
The imagestreamtag is composed of the name of the imagestream and a tag, separated by a colon:
For example, to refer to the sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d image in the imagestream object example earlier, the imagestreamtag would be:
Imagestream change triggers
Imagestream 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.
Imagestream mapping
When the integrated registry receives a new image, it creates and sends an image stream mapping to OpenShift Container Platform, providing the image’s project, name, tag, and image metadata.
Configuring imagestream mappings is an advanced feature.
This information is used to create a new image (if it does not already exist) and to tag the image into the imagestream. OpenShift Container Platform stores complete metadata about each image, such as commands, entry point, and environment variables. Images in OpenShift Container Platform are immutable and the maximum name length is 63 characters.
The following imagestream mapping example results in an image being tagged as test/origin-ruby-sample:latest:
Builds and Image Streams
Builds
A build is the process of transforming input parameters into a resulting object. Most often, the process is used to transform input parameters or source code into a runnable image. A BuildConfig object is the definition of the entire build process.
OpenShift Container Platform leverages Kubernetes by creating Docker-formatted containers from build images and pushing them to a container registry.
Build objects share common characteristics: inputs for a build, the need to complete a build process, logging the build process, publishing resources from successful builds, and publishing the final status of the build. Builds take advantage of resource restrictions, specifying limitations on resources such as CPU usage, memory usage, and build or pod execution time.
The OpenShift Container Platform build system provides extensible support for build strategies that are based on selectable types specified in the build API. There are three primary build strategies available:
By default, Docker builds and S2I builds are supported.
The resulting object of a build depends on the builder used to create it. For Docker and S2I builds, the resulting objects are runnable images. For Custom builds, the resulting objects are whatever the builder image author has specified.
Additionally, the Pipeline build strategy can be used to implement sophisticated workflows:
For a list of build commands, see the Developer’s Guide.
For more information on how OpenShift Container Platform leverages Docker for builds, see the upstream documentation.
Docker Build
The Docker build strategy invokes the docker build command, and it therefore expects a repository with a Dockerfile and all required artifacts in it to produce a runnable image.
Source-to-Image (S2I) Build
Source-to-Image (S2I) is a tool for building reproducible, Docker-formatted container images. It produces ready-to-run images by injecting application source into a container image and assembling a new image. The new image incorporates the base image (the builder) and built source and is ready to use with the docker run command. S2I supports incremental builds, which re-use previously downloaded dependencies, previously built artifacts, etc.
The advantages of S2I include the following:
S2I scripts can be written to inject application code into almost any existing Docker-formatted container image, taking advantage of the existing ecosystem. Note that, currently, S2I relies on tar to inject application source, so the image needs to be able to process tarred content.
With S2I, the assemble process can perform a large number of complex operations without creating a new layer at each step, resulting in a fast process. In addition, S2I scripts can be written to re-use artifacts stored in a previous version of the application image, rather than having to download or build them each time the build is run.
S2I allows you to rebuild the application consistently if an underlying image needs a patch due to a security issue.
By restricting build operations instead of allowing arbitrary actions, as a Dockerfile would allow, the PaaS operator can avoid accidental or intentional abuses of the build system.
Building an arbitrary Dockerfile exposes the host system to root privilege escalation. This can be exploited by a malicious user because the entire Docker build process is run as a user with Docker privileges. S2I restricts the operations performed as a root user and can run the scripts as a non-root user.
S2I prevents developers from performing arbitrary yum install type operations, which could slow down development iteration, during their application build.
S2I encourages a shared ecosystem of images where you can leverage best practices for your applications.
Produced images can include all inputs including specific versions of build tools and dependencies. This ensures that the image can be reproduced precisely.
Custom Build
The Custom build strategy allows developers to define a specific builder image responsible for the entire build process. Using your own builder image allows you to customize your build process.
A Custom builder image is a plain Docker-formatted container image embedded with build process logic, for example for building RPMs or base images. The openshift/origin-custom-docker-builder image is available on the Docker Hub registry as an example implementation of a Custom builder image.
Pipeline Build
The Pipeline build strategy allows developers to define a Jenkins pipeline for execution by the Jenkins pipeline plugin. The build can be started, monitored, and managed by OpenShift Container Platform in the same way as any other build type.
Pipeline workflows are defined in a Jenkinsfile, either embedded directly in the build configuration, or supplied in a Git repository and referenced by the build configuration.
The first time a project defines a build configuration using a Pipeline strategy, OpenShift Container Platform instantiates a Jenkins server to execute the pipeline. Subsequent Pipeline build configurations in the project share this Jenkins server.
For more details on how the Jenkins server is deployed and how to configure or disable the autoprovisioning behavior, see Configuring Pipeline Execution.
The Jenkins server is not automatically removed, even if all Pipeline build configurations are deleted. It must be manually deleted by the user.
For more information about Jenkins Pipelines, please see the Jenkins documentation.
Image Streams
An image stream and its associated tags provide an abstraction for referencing Docker images from within OpenShift Container Platform. 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 Docker image in the Docker registry is updated, the Build or Deployment will continue using the previous (presumably known good) image.
The source images can be stored in any of the following:
OpenShift Container Platform’s integrated registry
An external registry, for example registry.access.redhat.com or hub.docker.com
Other image streams in the OpenShift Container Platform cluster
When you define an object that references an image stream tag (such as a or Build configuration or Deployment configuration), you point to an image stream tag, not the Docker repository. When you Build or Deploy your application, OpenShift Container Platform queries the Docker 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.
The following image stream contains two tags: 34 which points to a Python v3.4 image and 35 which points to a Python v3.5 image:
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, OpenShift Container Platform also 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 and/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 will still point to a known-good version of the image, ensuring that your application will 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.
For a curated set of image streams, see the OpenShift Image Streams and Templates library.
When using image streams, it is important to understand what the image stream tag is pointing to and how changes to tags and images can affect you. For example:
If your image stream tag points to a Docker image tag, you need to understand how that Docker image tag is updated. For example, a Docker image tag docker.io/ruby:2.4 will probably always point to a v2.4 ruby image. But, a Docker image tag docker.io/ruby:latest will probably change with major versions. So, the Docker image tag that a image stream tag points to can tell you how stable the image stream tag will be, if you choose to reference it.
If your image stream tag follows another image stream tag (it does not point directly to a docker image tag), it is possible that the image stream tag will be updated to follow a different image stream tag in the future. Again, this could result in picking up an incompatible version change.
Important terms
A collection of related docker images and tags identifying them. For example, the OpenShift Jenkins images are in a Docker repository:
A content server that can store and service images from Docker repositories. For example:
A specific set of content that can be run as a container. Usually associated with a particular tag within a Docker repository.
A label applied to a Docker image in a repository that distinguishes a specific image. For example, here 3.6.0 is a tag:
A Docker image tag can be updated to point to new Docker image content at any time.
A SHA (Secure Hash Algorithm) code that can be used to pull an image. For example:
A SHA image ID cannot change. A specific SHA identifier always references the exact same docker image content.
An OpenShift Container Platform object that contains pointers to any number of Docker-formatted container images identified by tags. You can think of an image stream as equivalent to a Docker repository.
A named pointer to an image in an image stream. An image stream tag is similar to a Docker image tag. See Image Stream Tag below.
Image stream image
An image that allows you to retrieve a specific Docker image from a particular image stream where it is tagged. An image stream image is an API resource object that pulls together some metadata about a particular image SHA identifier. See Image Stream Images below.
Image stream trigger
A trigger that causes a specific action when an image stream tag changes. For example, importing can cause the value of the tag to change, which causes a trigger to fire when there are Deployments, Builds, or other resources listening for those. See Image Stream Triggers below.
Configuring Image Streams
See the Developer Guide for details on managing images and image streams.
| The name of the image stream. |
| Docker repository path where new images can be pushed to add/update them in this image stream. |
| The SHA identifier that this image stream tag currently references. Resources that reference this image stream tag use this identifier. |
| The SHA identifier that this image stream tag previously referenced. Can be used to rollback to an older image. |
| The image stream tag name. |
For a sample build configuration that references an image stream, see What Is a BuildConfig? in the Strategy stanza of the configuration.
For a sample deployment configuration that references an image stream, see Creating a Deployment Configuration in the Strategy stanza of the configuration.
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 OpenShift Container Platform 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 image stream object example above, the image stream image looks like:
Image Stream Tags
An image stream tag is a named pointer to an image in an image stream. It is often 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 will be available at the second position, and so forth. This allows for easy rollbacks to make tags point to historical images again.
The following image stream tag is from the the image stream object example above:
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 could be updated in the future to change which image they follow, much like a symlink. Note that these new levels are not guaranteed to be backwards-compatible.
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. See the Recommended Tagging Conventions.
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 image stream object example above, the image stream tag would be:
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.
The ImageChange trigger results in a new replication controller whenever the content of an image stream tag changes (when a new version of the image is pushed).
With the above example, when the latest tag value of the origin-ruby-sample image stream changes and the new image value differs from the current image specified in the deployment configuration’s helloworld container, a new replication controller is created using the new image for the helloworld container.
Image Stream Mappings
When the integrated registry receives a new image, it creates and sends an image stream mapping to OpenShift Container Platform, providing the image’s project, name, tag, and image metadata.
Configuring image stream mappings is an advanced feature.
This information is used to create a new image (if it does not already exist) and to tag the image into the image stream. OpenShift Container Platform stores complete metadata about each image, such as commands, entry point, and environment variables. Images in OpenShift Container Platform are immutable and the maximum name length is 63 characters.
See the Developer Guide for details on manually tagging images.
The following image stream mapping example results in an image being tagged as test/origin-ruby-sample:latest:
Working with Image Streams
The following sections describe how to use image streams and image stream tags. For more information on working with image streams, see Managing Images.
Getting Information about Image Streams
To get general information about the image stream and detailed information about all the tags it is pointing to, use the following command:
