Tagging images - Managing images | Images

Understanding image tags in image streams
Image tag conventions
Adding tags to image streams
Removing tags from image streams
Using image stream reference syntax
Understanding image stream reference types

Image tags identify specific versions of container images in image streams. You can use image tags to organize images and control which versions your builds and deployments use.

Understanding image tags in image streams

Image tags in OKD help you organize, identify, and reference specific versions of container images in image streams. Tags are human-readable labels that act as pointers to particular image layers and digests.

Tags function as mutable pointers within an image stream. When a new image is imported or tagged into the stream, the tag is updated to point to the new image’s immutable SHA digest. A single image digest can have multiple tags simultaneously assigned to it. For example, the :v3.11.59-2 and :latest tags are assigned to the same image digest.

Tags offer two main benefits:

Tags serve as the primary mechanism for builds and deployments to request a specific version of an image from an image stream.
Tags help maintain clarity and allow for easy promotion of images between environments. For example, you can promote an image from the :test tag to the :prod tag.

While image tags are primarily used for referencing images in configurations, OKD provides the oc tag command for managing tags directly within image streams. This command is similar to the podman tag or docker tag commands, but it operates on image streams instead of directly on local images. It is used to create a new tag pointer or update an existing tag pointer within an image stream to point to a new image.

Image tags are appended to the image name or image stream name by using a colon (:) as a separator.

Context Syntax Format Example

Context	Syntax Format	Example
External Registry	`<registry_path>:<tag>`	`registry.access.redhat.com/openshift3/jenkins-2-rhel7:v3.11.59-2`
Local Image Stream	`<image_stream_name>:<tag>`	`jenkins:latest`

External Registry

<registry_path>:<tag>

registry.access.redhat.com/openshift3/jenkins-2-rhel7:v3.11.59-2

Local Image Stream

<image_stream_name>:<tag>

jenkins:latest

Image tag conventions

Image tag naming conventions in OKD provide guidelines for creating tags that enable effective image pruning and maintain manageable image streams. Use consistent naming patterns to avoid tags that point to single revisions and never update.

Tags that are too specific effectively pin the tag to a single image revision that is never updated. For example, if you create a tag named v2.0.1-may-2019, the tag points to just one revision of an image and is never updated. If you use default image pruning options, such an image is never removed.

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.

To ensure proper garbage collection, use broader, more generic tags that are designed to be updated when a new image revision is built. The following table provides some recommended tagging conventions using the format <image_name>:<image_tag>.

Table 1. Image tag naming conventions
Description	Example
Major/Minor Version (Ideal for mutable pointers)	`myimage:v2.0`
Full Revision (Often used for tracking, but requires manual pruning)	`myimage:v2.0.1`
Architecture	`myimage:v2.0-x86_64`
Base image	`myimage:v1.2-centos7`
Latest	`myimage:latest`
Latest stable	`myimage:stable`

If your team requires the use of unique, date-specific, or highly revisioned tags like v2.0.1-may-2019, you must periodically inspect old and unsupported images and istags and remove them. Otherwise, you can experience increasing resource usage caused by retaining old images.

Adding tags to image streams

To organize images and create aliases for specific versions or automatically track changes to source tags in OKD, you can add tags to image streams with the oc tag command.

There are two types of tags available in OKD:

Permanent tags: A permanent tag 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.
Tracking tags: A tracking tag means that the destination tag’s metadata is updated during the import of the source tag.

The default behavior creates a permanent tag that is pinned to an image ID.

Procedure

Optional: Add a tag to an image stream by entering the following command. The default behavior creates a permanent tag that is pinned to an image ID:
```
$ oc tag <source_reference> <destination_image_stream>:<destination_tag>
```
For example, to configure the ruby image stream static-2.0 tag to always refer to the specific image that the ruby:2.0 tag points to now, enter the following command:
```
$ oc tag ruby:2.0 ruby:static-2.0
```
This creates a new image stream tag named static-2.0 in the ruby image stream. The new tag directly references the image ID that the ruby:2.0 image stream tag pointed to at the time oc tag was run, and the image it points to never changes.

Optional: Use the --alias=true flag to create a tracking tag. This ensures the destination tag automatically updates (tracks) when the source tag changes to point to a new image. For example, to ensure that the ruby:latest tag always reflects whatever image is currently tagged as ruby:2.0, enter the following command:

$ oc tag --alias=true ruby:2.0 ruby:latest

A Tracking Tag created with --alias=true automatically updates its image ID whenever the source tag changes. Use the latest or stable tracking tags for creating common, long-lived aliases. This tracking behavior only works correctly within a single image stream. Trying to create a cross-image stream alias produces an error.

Optional: Use the --scheduled=true flag to have the destination tag be refreshed, or re-imported, periodically. The period is configured globally at the system level. For example:
```
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --scheduled=true
```
Optional: Use the --reference flag to create an image stream tag that is not imported. The tag permanently points to the source location, regardless of changes to the source image. For example:
```
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --reference
```
Optional. Use the --insecure flag if the source registry is not secured with a valid HTTPS certificate. This flag tells the image stream to skip certificate verification during the import progress. For example:
```
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --insecure
```
Optional: Use the --reference-policy=local flag to instruct OKD to always fetch the tagged image from the integrated registry. 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 --reference-policy=local flag also allows for pulling from insecure registries without a need to supply the --insecure flag to the container runtime provided that the image stream has an insecure annotation or the tag has an insecure import policy. For example:
```
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --reference-policy=local
```

Removing tags from image streams

To keep your image streams clean and maintain organized image references in OKD, you can remove unused or outdated image stream tags. Remove tags by using the oc delete istag or oc tag -d commands.

Procedure

Remove a tag from an image stream by entering the following command:
```
$ oc delete istag/<name>:<tag>
```
For example, to remove the ruby:latest tag from the ruby image stream, enter the following command:
```
$ oc delete istag/ruby:latest
```
Alternatively, you can remove a tag using the oc tag -d command:
```
$ oc tag -d <name>:<tag>
```
For example, to remove the ruby:latest tag from the ruby image stream, enter the following command:
```
$ oc tag -d ruby:latest
```

Using image stream reference syntax

To ensure that your builds and deployments use the intended image version in OKD, you must use the correct reference syntax format.

Procedure

To reference an image by a mutable tag (ImageStreamTag) from an image stream within your cluster, use the <image_stream_name>:<tag> format in your build or deployment. For example:
```
# ...
spec:
  containers:
    - name: my-app
      image: <image_stream_name>:<tag>
```
where:

image

Specifies the image to use from the image stream. For example, ruby:2.0.
To reference a specific, immutable image ID, or digest, within an image stream, use the <image_stream_name>@<image_id> format in your build or deployment. For example:
```
# ...
spec:
  containers:
    - name: my-app
      image: <image_stream_name>@<image_id>
```
where:

image

Specifies the image to use from the image stream. For example, ruby@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e.

Using the image ID with the @id syntax ensures your configuration always uses the exact same image, even if the tag is later updated to point to a different image.
To reference an image from an external registry by using the DockerImage format, use the standard Docker pull specification: <registry>/<namespace>/<image_name>:<tag>. For example:
```
# ...
spec:
  source:
    type: Dockerfile
  strategy:
    type: Docker
    dockerStrategy:
      from:
        kind: DockerImage
        name: <registry>/<namespace>/<image_name>:<tag>
```
where:

image

Specifies the image to use from the external registry. For example, registry.redhat.io/rhel7:latest.

When no tag is specified in a DockerImage reference, the latest tag is assumed.

Understanding image stream reference types

By using image streams in OKD, you can reference container images by using different reference types. These reference types define which specific image version your builds and deployments use.

ImageStreamImage objects are automatically created in OKD when you import or tag an image into the image stream. You never have to explicitly define an ImageStreamImage object in any image stream definition that you use to create image streams.

Example image stream definitions often contain definitions of ImageStreamTag and references to DockerImage, but never contain definitions of ImageStreamImage.

Table 2. Imagestream reference types
Reference Type	Description	Syntax Examples
`ImageStreamTag`	References or retrieves an image for a given image stream and human-readable tag.	`image_stream_name:tag`
`ImageStreamImage`	References or retrieves an image for a given image stream and immutable SHA ID (digest).	`image_stream_name@id`
`DockerImage`	References or retrieves an image from an external registry. Uses the standard `docker pull` specification.	`openshift/ruby-20-centos7:2.0`, `registry.redhat.io/rhel7:latest`, `centos/ruby-22-centos7@sha256:3a335d7d…`