Questo contenuto non è disponibile nella lingua selezionata.
Chapter 5. Managing images
5.1. Managing images overview Copia collegamentoCollegamento copiato negli appunti!
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 Copia collegamentoCollegamento copiato negli appunti!
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 Copia collegamentoCollegamento copiato negli appunti!
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
:testtag to the:prodtag.
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.
| Context | Syntax Format | Example |
|---|---|---|
| External Registry |
|
|
| Local Image Stream |
|
|
5.2.2. Image tag conventions Copia collegamentoCollegamento copiato negli appunti!
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>.
| Description | Example |
|---|---|
| Major/Minor Version (Ideal for mutable pointers) |
|
| Full Revision (Often used for tracking, but requires manual pruning) |
|
| Architecture |
|
| Base image |
|
| Latest |
|
| Latest 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.
5.2.3. Adding tags to image streams Copia collegamentoCollegamento copiato negli appunti!
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>
$ oc tag <source_reference> <destination_image_stream>:<destination_tag>Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to configure the
rubyimage streamstatic-2.0tag to always refer to the specific image that theruby:2.0tag points to now, enter the following command:oc tag ruby:2.0 ruby:static-2.0
$ oc tag ruby:2.0 ruby:static-2.0Copy to Clipboard Copied! Toggle word wrap Toggle overflow This creates a new image stream tag named
static-2.0in therubyimage stream. The new tag directly references the image ID that theruby:2.0image stream tag pointed to at the timeoc tagwas run, and the image it points to never changes.Optional: Use the
--alias=trueflag 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 theruby:latesttag always reflects whatever image is currently tagged asruby:2.0, enter the following command:oc tag --alias=true ruby:2.0 ruby:latest
$ oc tag --alias=true ruby:2.0 ruby:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteA Tracking Tag created with
--alias=trueautomatically updates its image ID whenever the source tag changes. Use thelatestorstabletracking 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=trueflag 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
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --scheduled=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Use the
--referenceflag 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
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --referenceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optional. Use the
--insecureflag 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
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --insecureCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Use the
--reference-policy=localflag 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=localflag also allows for pulling from insecure registries without a need to supply the--insecureflag 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
$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --reference-policy=localCopy to Clipboard Copied! Toggle word wrap Toggle overflow
5.2.4. Removing tags from image streams Copia collegamentoCollegamento copiato negli appunti!
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>
$ oc delete istag/<name>:<tag>Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to remove the
ruby:latesttag from therubyimage stream, enter the following command:oc delete istag/ruby:latest
$ oc delete istag/ruby:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow Alternatively, you can remove a tag using the
oc tag -dcommand:oc tag -d <name>:<tag>
$ oc tag -d <name>:<tag>Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to remove the
ruby:latesttag from therubyimage stream, enter the following command:oc tag -d ruby:latest
$ oc tag -d ruby:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow
5.2.5. Using image stream reference syntax Copia collegamentoCollegamento copiato negli appunti!
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># ... spec: containers: - name: my-app image: <image_stream_name>:<tag>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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># ... spec: containers: - name: my-app image: <image_stream_name>@<image_id>Copy to Clipboard Copied! Toggle word wrap Toggle overflow where:
image-
Specifies the image to use from the image stream. For example,
ruby@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e.
NoteUsing the image ID with the
@idsyntax 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:Copy to Clipboard Copied! Toggle word wrap Toggle overflow where:
image-
Specifies the image to use from the external registry. For example,
registry.redhat.io/rhel7:latest.
NoteWhen no tag is specified in a
DockerImagereference, thelatesttag is assumed.
5.2.6. Understanding image stream reference types Copia collegamentoCollegamento copiato negli appunti!
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.
Example image stream definitions often contain definitions of ImageStreamTag and references to DockerImage, but never contain definitions of ImageStreamImage.
| Reference Type | Description | Syntax Examples |
|---|---|---|
|
| References or retrieves an image for a given image stream and human-readable tag. |
|
|
| References or retrieves an image for a given image stream and immutable SHA ID (digest). |
|
|
|
References or retrieves an image from an external registry. Uses the standard |
|
5.3. Image pull policy Copia collegamentoCollegamento copiato negli appunti!
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 Copia collegamentoCollegamento copiato negli appunti!
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:
| Value | Description |
|---|---|
|
| Always pull the image. |
|
| Only pull the image if it does not already exist on the node. |
|
| Never pull the image. |
The following example sets the imagePullPolicy parameter to IfNotPresent for the image tagged v1.2.3:
Example imagePullPolicy configuration
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
IfNotPresentbecause the image tag is notlatest.
5.3.1.1. Omitting the imagePullPolicy parameter Copia collegamentoCollegamento copiato negli appunti!
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.
| Image tag | imagePullPolicy setting | Behavior |
|---|---|---|
|
|
| Always pulls the image. This policy helps ensure that the container always uses the latest version of the image. |
|
Any other tag (for example, |
| 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 Copia collegamentoCollegamento copiato negli appunti!
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.
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 Copia collegamentoCollegamento copiato negli appunti!
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.
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
Allow pods in
project-ato reference images inproject-bby entering the follow command. In this example, the service accountdefaultinproject-ais bound to thesystem:image-pullerrole inproject-b:oc policy add-role-to-user \ system:image-puller system:serviceaccount:project-a:default \ --namespace=project-b$ oc policy add-role-to-user \ system:image-puller system:serviceaccount:project-a:default \ --namespace=project-bCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Allow access for any service account in
project-aby using theadd-role-to-groupflag. For example:oc policy add-role-to-group \ system:image-puller system:serviceaccounts:project-a \ --namespace=project-b$ oc policy add-role-to-group \ system:image-puller system:serviceaccounts:project-a \ --namespace=project-bCopy to Clipboard Copied! Toggle word wrap Toggle overflow
5.4.2. Allowing pods to reference images from other secured registries Copia collegamentoCollegamento copiato negli appunti!
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.
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
Example pull secret
5.4.2.1. Creating a pull secret Copia collegamentoCollegamento copiato negli appunti!
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
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$ oc create secret generic <pull_secret_name> \ --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ --type=kubernetes.io/dockerconfigjsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow 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$ oc create secret generic <pull_secret_name> \ --from-file=<path/to/.config/containers/auth.json> \ --type=kubernetes.io/podmanconfigjsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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>$ 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 Copied! Toggle word wrap Toggle overflow
5.4.2.2. Using a pull secret in a workload Copia collegamentoCollegamento copiato negli appunti!
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
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
$ oc secrets link default <pull_secret_name> --for=pullCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the change by entering the following command:
oc get serviceaccount default -o yaml
$ oc get serviceaccount default -o yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example ArgoCD workflow
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
5.4.2.3. Pulling from private registries with delegated authentication Copia collegamentoCollegamento copiato negli appunti!
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
Create a secret for the delegated authentication server by entering the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a secret for the private registry by entering the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow