Questo contenuto non è disponibile nella lingua selezionata.

Chapter 5. Managing images


5.1. Managing images overview

Image streams in Red Hat OpenShift Service on AWS classic architecture provide a layer of abstraction over container images, enabling automation for your CI/CD pipelines. You can configure builds and deployments to watch image streams and automatically trigger new builds or deployments when images are updated.

The main advantage of using image streams is the automation they enable for your continuous integration and continuous delivery (CI/CD) pipelines. For example:

  • Image streams allow Red Hat OpenShift Service on AWS classic architecture resources like Builds and Deployments to "watch" them.
  • When a new image is added to the stream, or when an existing tag is modified to point to a new image, the watching resources receive notifications.
  • When notifications are received, the watching resources can automatically react by performing a new build or a new deployment.

5.2. 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.

5.2.1. Understanding image tags in image streams

Image tags in Red Hat OpenShift Service on AWS classic architecture 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, Red Hat OpenShift Service on AWS classic architecture 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.

Expand
ContextSyntax FormatExample

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

5.2.2. Image tag conventions

Image tag naming conventions in Red Hat OpenShift Service on AWS classic architecture 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.

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

Expand
Table 5.1. Image tag naming conventions
DescriptionExample

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.

5.2.3. Adding tags to image streams

To organize images and create aliases for specific versions or automatically track changes to source tags in Red Hat OpenShift Service on AWS classic architecture, you can add tags to image streams with the oc tag command.

There are two types of tags available in Red Hat OpenShift Service on AWS classic architecture:

  • 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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
    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:

    $ oc tag <source_reference> <destination_image_stream>:<destination_tag> --scheduled=true
    Copy to Clipboard Toggle word wrap
  • 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
    Copy to Clipboard Toggle word wrap
  • 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
    Copy to Clipboard Toggle word wrap
  • Optional: Use the --reference-policy=local flag to instruct Red Hat OpenShift Service on AWS classic architecture 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
    Copy to Clipboard Toggle word wrap

5.2.4. Removing tags from image streams

To keep your image streams clean and maintain organized image references in Red Hat OpenShift Service on AWS classic architecture, 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>
    Copy to Clipboard Toggle word wrap

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

    $ oc delete istag/ruby:latest
    Copy to Clipboard Toggle word wrap
  • Alternatively, you can remove a tag using the oc tag -d command:

    $ oc tag -d <name>:<tag>
    Copy to Clipboard Toggle word wrap

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

    $ oc tag -d ruby:latest
    Copy to Clipboard Toggle word wrap

5.2.5. Using image stream reference syntax

To ensure that your builds and deployments use the intended image version in Red Hat OpenShift Service on AWS classic architecture, 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>
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

    where:

    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:

    # ...
    spec:
      source:
        type: Dockerfile
      strategy:
        type: Docker
        dockerStrategy:
          from:
            kind: DockerImage
            name: <registry>/<namespace>/<image_name>:<tag>
    Copy to Clipboard Toggle word wrap

    where:

    image
    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.

5.2.6. Understanding image stream reference types

By using image streams in Red Hat OpenShift Service on AWS classic architecture, 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 Red Hat OpenShift Service on AWS classic architecture 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.

Expand
Table 5.2. Imagestream reference types
Reference TypeDescriptionSyntax 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…​

5.3. Image pull policy

To manage image updates and optimize pod startup performance in Red Hat OpenShift Service on AWS classic architecture, you can configure the imagePullPolicy parameter in your container specifications. This setting controls when container images are pulled from registries.

5.3.1. About the imagePullPolicy parameter

To control when Red Hat OpenShift Service on AWS classic architecture pulls container images from registries or uses locally cached copies when starting containers, you can configure the imagePullPolicy parameter. This policy helps you manage image updates and optimize pod startup performance.

The following table lists the possible values for the imagePullPolicy parameter:

Expand
Table 5.3. imagePullPolicy values
ValueDescription

Always

Always pull the image.

IfNotPresent

Only pull the image if it does not already exist on the node.

Never

Never pull the image.

The following example sets the imagePullPolicy parameter to IfNotPresent for the image tagged v1.2.3:

Example imagePullPolicy configuration

apiVersion: apps/v1
kind: Deployment
# ...
spec:
  # ...
  template:
    spec:
      containers:
      - name: my-app-container
        image: registry.example.com/myapp:v1.2.3
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8080
Copy to Clipboard Toggle word wrap

where:

image
Specifies is the image to use. In this example, the image tag is explicitly set to v1.2.3.
imagePullPolicy
Specifies the policy to use. In this example, the policy is set to IfNotPresent because the image tag is not latest.

5.3.1.1. Omitting the imagePullPolicy parameter

When you omit the imagePullPolicy parameter, Red Hat OpenShift Service on AWS classic architecture automatically determines the policy based on the image tag. This default behavior ensures that the latest tag always pulls the newest image, while specific version tags use locally cached images when available to improve efficiency.

Expand
Image tagimagePullPolicy settingBehavior

latest

Always

Always pulls the image. This policy helps ensure that the container always uses the latest version of the image.

Any other tag (for example, v1.2.3, stable, production)

IfNotPresent

Pull only if necessary. This policy uses the locally cached version of the image if it exists on the node, avoiding unnecessary pulls from the registry.

5.4. Using image pull secrets

To authenticate with container registries and pull images across Red Hat OpenShift Service on AWS classic architecture projects or from secured registries, you can configure and use image pull secrets.

You first obtain the registry authentication credentials, which are typically found in the ~/.docker/config.json file for Docker or the ~/.config/containers/auth.json file for Podman, created by the pull secret from Red Hat OpenShift Cluster Manager process. This content is then used to create or update the global pullSecret object within your cluster, allowing access to images from quay.io and registry.redhat.io.

Note

If you are using the OpenShift image registry and are pulling from image streams located in the same project, then your pod service account should already have the correct permissions. No additional action should be required.

5.4.1. Allowing pods to reference images across projects

To allow pods in one Red Hat OpenShift Service on AWS classic architecture project to reference images from another project, you can bind a service account to the system:image-puller role in the target project. Use the oc policy add-role-to-user or oc policy add-role-to-group command to grant cross-project image access.

Note

When you create a pod service account or a namespace, wait until the service account is provisioned with a Docker pull secret. If you create a pod before its service account is fully provisioned, the pod fails to access the OpenShift image registry.

Procedure

  1. Allow pods in project-a to reference images in project-b by entering the follow command. In this example, the service account default in project-a is bound to the system:image-puller role in project-b:

    $ oc policy add-role-to-user \
        system:image-puller system:serviceaccount:project-a:default \
        --namespace=project-b
    Copy to Clipboard Toggle word wrap
  2. Optional: Allow access for any service account in project-a by using the add-role-to-group flag. For example:

    $ oc policy add-role-to-group \
        system:image-puller system:serviceaccounts:project-a \
        --namespace=project-b
    Copy to Clipboard Toggle word wrap

5.4.2. Allowing pods to reference images from other secured registries

Pull secrets enable pods in Red Hat OpenShift Service on AWS classic architecture to authenticate with secured registries and pull container images. Docker and Podman store authentication credentials in configuration files that you can use to create pull secrets for your service accounts.

The following files store your authentication information if you have previously logged in to a secured or insecure registry:

  • Docker: By default, Docker uses $HOME/.docker/config.json.
  • Podman: By default, Podman uses $HOME/.config/containers/auth.json.
Note

Both Docker and Podman credential files and the associated pull secret can contain multiple references to the same registry if they have unique paths, for example, quay.io and quay.io/<example_repository>. However, neither Docker nor Podman support multiple entries for the exact same registry path.

Example config.json file

{
   "auths":{
      "cloud.openshift.com":{
         "auth":"b3Blb=",
         "email":"you@example.com"
      },
      "quay.io":{
         "auth":"b3Blb=",
         "email":"you@example.com"
      },
      "quay.io/repository-main":{
         "auth":"b3Blb=",
         "email":"you@example.com"
      }
   }
}
Copy to Clipboard Toggle word wrap

Example pull secret

apiVersion: v1
data:
  .dockerconfigjson: ewogICAiYXV0aHMiOnsKICAgICAgIm0iOnsKICAgICAgIsKICAgICAgICAgImF1dGgiOiJiM0JsYj0iLAogICAgICAgICAiZW1haWwiOiJ5b3VAZXhhbXBsZS5jb20iCiAgICAgIH0KICAgfQp9Cg==
kind: Secret
metadata:
  creationTimestamp: "2021-09-09T19:10:11Z"
  name: pull-secret
  namespace: default
  resourceVersion: "37676"
  uid: e2851531-01bc-48ba-878c-de96cfe31020
type: Opaque
Copy to Clipboard Toggle word wrap

5.4.2.1. Creating a pull secret

To authenticate with container registries in Red Hat OpenShift Service on AWS classic architecture, you can create pull secrets from existing Docker or Podman authentication files. You can also create secrets by providing registry credentials directly by using the oc create secret docker-registry command.

Procedure

  1. Create a secret from an existing authentication file:

    1. For Docker clients using .docker/config.json, enter the following command:

      $ oc create secret generic <pull_secret_name> \
          --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
          --type=kubernetes.io/dockerconfigjson
      Copy to Clipboard Toggle word wrap
    2. For Podman clients using .config/containers/auth.json, enter the following command:

      $ oc create secret generic <pull_secret_name> \
           --from-file=<path/to/.config/containers/auth.json> \
           --type=kubernetes.io/podmanconfigjson
      Copy to Clipboard Toggle word wrap
  2. Optional: If you do not already have a Docker credentials file for the secured registry, you can create a secret by running the following command:

    $ oc create secret docker-registry <pull_secret_name> \
        --docker-server=<registry_server> \
        --docker-username=<user_name> \
        --docker-password=<password> \
        --docker-email=<email>
    Copy to Clipboard Toggle word wrap

5.4.2.2. Using a pull secret in a workload

To allow workloads to pull images from private registries in Red Hat OpenShift Service on AWS classic architecture, you can link the pull secret to a service account by entering the oc secrets link command or by defining it directly in your workload configuration YAML file.

Procedure

  1. Link the pull secret to a service account by entering the following command. Note that the name of the service account should match the name of the service account that pod uses. The default service account is default.

    $ oc secrets link default <pull_secret_name> --for=pull
    Copy to Clipboard Toggle word wrap
  2. Verify the change by entering the following command:

    $ oc get serviceaccount default -o yaml
    Copy to Clipboard Toggle word wrap

    Example output

    apiVersion: v1
    imagePullSecrets:
    - name: default-dockercfg-123456
    - name: <pull_secret_name>
    kind: ServiceAccount
    metadata:
      annotations:
        openshift.io/internal-registry-pull-secret-ref: <internal_registry_pull_secret>
      creationTimestamp: "2025-03-03T20:07:52Z"
      name: default
      namespace: default
      resourceVersion: "13914"
      uid: 9f62dd88-110d-4879-9e27-1ffe269poe3
    secrets:
    - name: <pull_secret_name>
    Copy to Clipboard Toggle word wrap

  3. Optional: Instead of linking the secret to a service account, you can alternatively reference it directly in your pod or workload definition. This is useful for GitOps workflows such as ArgoCD. For example:

    Example pod specification

    apiVersion: v1
    kind: Pod
    metadata:
      name: <secure_pod_name>
    spec:
      containers:
      - name: <container_name>
        image: quay.io/my-private-image
      imagePullSecrets:
      - name: <pull_secret_name>
    Copy to Clipboard Toggle word wrap

    Example ArgoCD workflow

    apiVersion: argoproj.io/v1alpha1
    kind: Workflow
    metadata:
      generateName: <example_workflow>
    spec:
      entrypoint: <main_task>
      imagePullSecrets:
      - name: <pull_secret_name>
    Copy to Clipboard Toggle word wrap

5.4.2.3. Pulling from private registries with delegated authentication

To pull images from private registries that delegate authentication to a separate service in Red Hat OpenShift Service on AWS classic architecture, you can create pull secrets for both the authentication server and the registry endpoint. Use the oc create secret docker-registry command to create separate secrets for each service.

Procedure

  1. Create a secret for the delegated authentication server by entering the following command:

    $ oc create secret docker-registry \
        --docker-server=sso.redhat.com \
        --docker-username=developer@example.com \
        --docker-password=******** \
        --docker-email=unused \
        redhat-connect-sso
    Copy to Clipboard Toggle word wrap
  2. Create a secret for the private registry by entering the following command:

    $ oc create secret docker-registry \
        --docker-server=privateregistry.example.com \
        --docker-username=developer@example.com \
        --docker-password=******** \
        --docker-email=unused \
        private-registry
    Copy to Clipboard Toggle word wrap
Torna in cima
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2026 Red Hat