Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 5. Managing images

5.1. Managing images overview
Link kopieren

With OpenShift Container Platform you can interact with images and set up image streams, depending on where the registries of the images are located, any authentication requirements around those registries, and how you want your builds and deployments to behave.

5.1.1. Images overview
Link kopieren

An image stream comprises any number of container images identified by tags. It presents a single virtual view of related images, similar to a container image repository.

By watching an image stream, builds and deployments can receive notifications when new images are added or modified and react by performing a build or deployment, respectively.

5.2. Tagging images
Link kopieren

The following sections provide an overview and instructions for using image tags in the context of container images for working with OpenShift Container Platform image streams and their tags.

5.2.1. Image tags
Link kopieren

An image tag is a label applied to a container image in a repository that distinguishes a specific image from other images in an image stream. Typically, the tag represents a version number of some sort. For example, here 

:v3.11.59-2
is the tag: 

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

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 
docker tag
command, but operates on image streams instead of directly on images.

5.2.2. Image tag conventions
Link kopieren

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

Although tag naming convention is up to you, here are a few examples in the format 

<image_name>:<image_tag>
:

Expand
Table 5.1. Image tag naming conventions
DescriptionExample

Revision 

myimage:v2.0.1

Architecture 

myimage:v2.0-x86_64

Base image 

myimage:v1.2-centos7

Latest (potentially unstable) 

myimage:latest

Latest stable 

myimage:stable

If you require dates in tag names, 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
Link kopieren

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

Procedure

  • You can add tags to an image stream using the 

    oc tag
    command: 

    $ oc tag <source> <destination>

    For example, to configure the 

    ruby
    image stream 
    static-2.0
    tag to always refer to the current image for the 
    ruby
    image stream 
    2.0
    tag: 

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

  • To ensure the destination tag is updated when the source tag changes, use the 

    --alias=true
    flag: 

    $ oc tag --alias=true <source> <destination>
Note

Use a tracking tag for creating permanent aliases, for example, 

latest
or 
stable
. The tag only works correctly within a single image stream. Trying to create a cross-image stream alias produces an error.

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

  • The 

    --reference
    flag creates an image stream tag that is not imported. The tag points to the source location, permanently.

    If you want to instruct OpenShift Container Platform 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 image stream has an insecure annotation or the tag has an insecure import policy.

5.2.4. Removing tags from image streams
Link kopieren

You can remove tags from an image stream.

Procedure

  • To remove a tag completely from an image stream run: 

    $ oc delete istag/ruby:latest

    or: 

    $ oc tag -d ruby:latest

5.2.5. Referencing images in imagestreams
Link kopieren

You can use tags to reference images in image streams using the following reference types.

Expand
Table 5.2. Imagestream reference types
Reference typeDescription

ImageStreamTag

An 

ImageStreamTag
is used to reference or retrieve an image for a given image stream and tag. 

ImageStreamImage

An 

ImageStreamImage
is used to reference or retrieve an image for a given image stream and image 
sha
ID. 

DockerImage

A 

DockerImage
is used to reference or retrieve an image for a given external registry. It uses standard Docker 
pull specification
for its name.

When viewing example image stream definitions you may notice they contain definitions of 

ImageStreamTag
and references to 
DockerImage
, but nothing related to 
ImageStreamImage
.

This is because the 

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

Procedure

  • To reference an image for a given image stream and tag, use 

    ImageStreamTag
    : 

    <image_stream_name>:<tag>

  • To reference an image for a given image stream and image 

    sha
    ID, use 
    ImageStreamImage
    : 

    <image_stream_name>@<id>

    The 

    <id>
    is an immutable identifier for a specific image, also called a digest.

  • To reference or retrieve an image for a given external registry, use 

    DockerImage
    : 

    openshift/ruby-20-centos7:2.0
    Note

    When no tag is specified, it is assumed the 

    latest
    tag is used.

    You can also reference a third-party registry: 

    registry.redhat.io/rhel7:latest

    Or an image with a digest: 

    centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e

5.3. Image pull policy
Link kopieren

Each container in a pod has a container image. After you have created an image and pushed it to a registry, you can then refer to it in the pod.

5.3.1. Image pull policy overview
Link kopieren

When OpenShift Container Platform creates containers, it uses the container 

imagePullPolicy
to determine if the image should be pulled prior to starting the container. There are three possible values for 
imagePullPolicy
:

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.

If a container 

imagePullPolicy
parameter is not specified, OpenShift Container Platform sets it based on the image tag:

  1. If the tag is 
    latest
    , OpenShift Container Platform defaults 
    imagePullPolicy
    to 
    Always
    .
  2. Otherwise, OpenShift Container Platform defaults 
    imagePullPolicy
    to 
    IfNotPresent
    .

5.4. Using image pull secrets
Link kopieren

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 and no additional action should be required.

However, for other scenarios, such as referencing images across OpenShift Container Platform projects or from secured registries, additional configuration steps are required.

You can obtain the image pull secret from Red Hat OpenShift Cluster Manager. This pull secret is called 

pullSecret
.

You use this pull secret to authenticate with the services that are provided by the included authorities, Quay.io and registry.redhat.io, which serve the container images for OpenShift Container Platform components.

5.4.1. Allowing pods to reference images across projects
Link kopieren

When using the OpenShift image registry, to allow pods in 

project-a
to reference images in 
project-b
, a service account in 
project-a
must be bound to the 
system:image-puller
role in 
project-b
.

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. To allow pods in 

    project-a
    to reference images in 
    project-b
    , bind a service account in 
    project-a
    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

    After adding that role, the pods in 

    project-a
    that reference the default service account are able to pull images from 
    project-b
    .

  2. To allow access for any service account in 

    project-a
    , use the group: 

    $ oc policy add-role-to-group \
    system:image-puller system:serviceaccounts:project-a \
    --namespace=project-b

5.4.2. Allowing pods to reference images from other secured registries
Link kopieren

To pull a secured container from other private or secured registries, you must create a pull secret from your container client credentials, such as Docker or Podman, and add it to your service account.

Both Docker and Podman use a configuration file to store authentication details to log in to secured or insecure registry:

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

These files store your authentication information if you have previously logged in to a secured or insecure registry.

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"
      }
   }
}

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

5.4.2.1. Creating a pull secret
Link kopieren

Procedure

  • Create a secret from an existing authentication file:

    • 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

    • 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

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

5.4.2.2. Using a pull secret in a workload
Link kopieren

You can use a pull secret to allow workloads to pull images from a private registry with one of the following methods:

  • By linking the secret to a 
    ServiceAccount
    , which automatically applies the secret to all pods using that service account.
  • By defining 
    imagePullSecrets
    directly in workload configurations, which is useful for environments like GitOps or ArgoCD.

Procedure

  • You can use a secret for pulling images for pods by adding the secret to your service account. 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
    .

    • Enter the following command to link the pull secret to a 

      ServiceAccount
      : 

      $ oc secrets link default <pull_secret_name> --for=pull

    • To verify the change, enter the following command: 

      $ oc get serviceaccount default -o yaml

      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>

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

    Example ArgoCD workflow

    apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: <example_workflow>
spec:
  entrypoint: <main_task>
  imagePullSecrets:
  - name: <pull_secret_name>

5.4.2.3. Pulling from private registries with delegated authentication
Link kopieren

A private registry can delegate authentication to a separate service. In these cases, image pull secrets must be defined for both the authentication and registry endpoints.

Procedure

  1. Create a secret for the delegated authentication server: 

    $ oc create secret docker-registry \
    --docker-server=sso.redhat.com \
    --docker-username=developer@example.com \
    --docker-password=******** \
    --docker-email=unused \
    redhat-connect-sso

secret/redhat-connect-sso

  2. Create a secret for the private registry: 

    $ oc create secret docker-registry \
    --docker-server=privateregistry.example.com \
    --docker-username=developer@example.com \
    --docker-password=******** \
    --docker-email=unused \
    private-registry

secret/private-registry

5.4.3. Updating the global cluster pull secret
Link kopieren

You can update the global pull secret for your cluster by either replacing the current pull secret or appending a new pull secret.

Important

To transfer your cluster to another owner, you must initiate the transfer in OpenShift Cluster Manager and then update the pull secret on the cluster. Updating a cluster’s pull secret without initiating the transfer in OpenShift Cluster Manager causes the cluster to stop reporting Telemetry metrics in OpenShift Cluster Manager.

For more information, see "Transferring cluster ownership" in the Red Hat OpenShift Cluster Manager documentation.

Prerequisites

  • You have access to the cluster as a user with the 
    cluster-admin
    role.

Procedure

  1. Optional: To append a new pull secret to the existing pull secret, complete the following steps:

    1. Enter the following command to download the pull secret: 

      $ oc get secret/pull-secret -n openshift-config --template='{{index .data ".dockerconfigjson" | base64decode}}' > <pull_secret_location>
      1
      1
      <pull_secret_location>: Include the path to the pull secret file.

    2. Enter the following command to add the new pull secret: 

      $ oc registry login --registry="<registry>" \
      1 
      
--auth-basic="<username>:<password>" \
      2 
      
--to=<pull_secret_location>
      3
      1
      <registry>: Include the new registry. You can include many repositories within the same registry, for example: --registry="<registry/my-namespace/my-repository>.
      2
      <username>:<password>: Include the credentials of the new registry.
      3
      <pull_secret_location>: Include the path to the pull secret file.

      You can also perform a manual update to the pull secret file.

  2. Enter the following command to update the global pull secret for your cluster: 

    $ oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=<pull_secret_location>
    1
    1
    <pull_secret_location>: Include the path to the new pull secret file.

    This update rolls out to all nodes, which can take some time depending on the size of your cluster.

    Note

    As of OpenShift Container Platform 4.7.4, changes to the global pull secret no longer trigger a node drain or reboot.

Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red HatNach oben