---
title: Tagging images
---

# Tagging images {#tagging-images}

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 {#images-tag_tagging-images}

Image tags in OpenShift Container Platform 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, OpenShift Container Platform 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 |
| --- | --- | --- |
| **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 {#images-tagging-conventions_tagging-images}

Image tag naming conventions in OpenShift Container Platform 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>`.

**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` |

> [!NOTE]
> 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 {#images-add-tags-to-imagestreams_tagging-images}

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

There are two types of tags available in OpenShift Container Platform:

- 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:

  ```terminal
  $ 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:

  ```terminal
  $ 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:

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

  > [!NOTE]
  > 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:

  ```terminal
  $ 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:

  ```terminal
  $ 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:

  ```terminal
  $ oc tag <source_reference> <destination_image_stream>:<destination_tag> --insecure
  ```
- Optional: Use the `--reference-policy=local` flag to instruct OpenShift Container Platform 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:

  ```terminal
  $ oc tag <source_reference> <destination_image_stream>:<destination_tag> --reference-policy=local
  ```

## Removing tags from image streams {#images-remove-tag-imagestream_tagging-images}

To keep your image streams clean and maintain organized image references in OpenShift Container Platform, 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:

  ```terminal
  $ oc delete istag/<name>:<tag>
  ```

  For example, to remove the `ruby:latest` tag from the `ruby` image stream, enter the following command:

  ```terminal
  $ oc delete istag/ruby:latest
  ```
- Alternatively, you can remove a tag using the `oc tag -d` command:

  ```terminal
  $ oc tag -d <name>:<tag>
  ```

  For example, to remove the `ruby:latest` tag from the `ruby` image stream, enter the following command:

  ```terminal
  $ oc tag -d ruby:latest
  ```

## Using image stream reference syntax {#images-referencing-images-imagestreams_tagging-images}

To ensure that your builds and deployments use the intended image version in OpenShift Container Platform, 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:

  ```yaml
  # ...
  spec:
    containers:
      - name: my-app
        image: <image_stream_name>:<tag>
  ```

  where:

  `spec.containers.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:

  ```yaml
  # ...
  spec:
    containers:
      - name: my-app
        image: <image_stream_name>@<image_id>
  ```

  where:

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

  > [!NOTE]
  > 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:

  ```yaml
  # ...
  spec:
    source:
      type: Dockerfile
    strategy:
      type: Docker
      dockerStrategy:
        from:
          kind: DockerImage
          name: <registry>/<namespace>/<image_name>:<tag>
  ```

  where:

  `spec.strategy.dockerStrategy.from.name`
  :   Specifies the image to use from the external registry. For example, `registry.redhat.io/rhel7:latest`.

  > [!NOTE]
  > When no tag is specified in a `DockerImage` reference, the `latest` tag is assumed.

## Understanding image stream reference types {#images-imagestream-reference-types_tagging-images}

By using image streams in OpenShift Container Platform, 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 OpenShift Container Platform 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.

> [!NOTE]
> Example image stream definitions often contain definitions of `ImageStreamTag` and references to `DockerImage`, but never contain definitions of `ImageStreamImage`.

**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...` |