The following sections provide an overview and instructions for using image tags in the context of container images for working with OpenShift Container Platform imagestreams and their tags.
An image tag is a label applied to a container image in a repository that distinguishes a specific image from other images in an imagestream. Typically, the tag represents a version number of some sort. For example, here v3.11.59-2 is the tag:
You can add additional tags to an image. For example, an image might be assigned the tags :v3.11.59-2 and :latest.
OpenShift Container Platform provides the
oc tag command, which is similar to the
tag command, but operates on imagestreams instead of directly on images.
Images evolve over time and their tags reflect this. Generally, an image tag always points to the latest image built.
If there is too much information embedded in a tag name, like
v2.0.1-may-2019, the tag points to just one revision of an image and is
never updated. Using default image pruning options, such an image is never
In very large clusters, the schema of creating new tags for every revised image
could eventually fill up the etcd datastore with excess tag metadata for images
that are long outdated.
If the tag is named
v2.0, image revisions are more likely. This
results in longer tag history and, therefore, the image pruner is more likely to
remove old and unused images.
Although tag naming convention is up to you, here are a few examples in the
Latest (potentially unstable)
If you require dates in tag names, periodically inspect old and unsupported
istags and remove them. Otherwise, you can experience increasing
resource usage caused by retaining old images.
An imagestream in OpenShift Container Platform comprises zero or more container images identified by tags.
There are different types of tags available. The default behavior uses a permanent tag, which points to a specific image in time. If the _permanent_tag is in use and the source changes, the tag does not change for the destination.
A tracking tag means the destination tag’s metadata is updated during the import of the source tag.
You can add tags to an imagestream using the
oc tag command:
$ oc tag <source> <destination>
For example, to configure the
static-2.0 tag to always
refer to the current image for the
$ oc tag ruby:2.0 ruby:static-2.0
This creates a new imagestreamtag named
static-2.0 in the
The new tag directly references the image id that the
imagestreamtag pointed to at the time
oc tag was run, and the image it points
to never changes.
To ensure the destination tag is updated whenever the source tag changes, use
$ oc tag --alias=true <source> <destination>
Use a tracking tag for creating permanent aliases, for example,
You can also add the
--scheduled=true flag to have the destination tag be
refreshed, or re-imported, periodically. The period is configured globally at
the system level.
--reference flag creates an imagestreamtag that is not imported. The
tag points to the source location, permanently.
If you want to instruct OpenShift to always fetch the tagged image from the
integrated registry, use
--reference-policy=local. The registry uses the
pull-through feature to serve the image to the client. By default, the image
blobs are mirrored locally by the registry. As a result, they can be pulled more
quickly the next time they are needed. The flag also allows for pulling from
insecure registries without a need to supply
--insecure-registry to the container
runtime as long as the imagestream has an insecure annotation or the tag has an
insecure import policy.
You can remove tags from an imagestream.
To remove a tag completely from an imagestream run:
$ oc delete istag/ruby:latest
$ oc tag -d ruby:latest
You can use tags to reference images in imagestreams using the following reference types.
When viewing example imagestream definitions you may notice they contain
ImageStreamTag and references to
DockerImage, but nothing
This is because the
ImageStreamImage objects are automatically created in
OpenShift Container Platform when you import or tag an image into the imagestream. You
should never have to explicitly define an
ImageStreamImage object in any
imagestream definition that you use to create imagestreams.
To reference an image for a given imagestream and tag, use
To reference an image for a given imagestream and image
sha ID, use
<id> is an immutable identifier for a specific image, also called a
To reference or retrieve an image for a given external
When no tag is specified, it is assumed the latest tag is used.
You can also reference a third-party registry:
Or an image with a digest:
Example imagestream definitions for CentOS imagestreams.