Chapter 5. Managing images
5.1. Managing images overview
With OpenShift Container Platform you can interact with images and set up imagestreams, depending on where the images' registries are located, any authentication requirements around those registries, and how you want your builds and deployments to behave.
5.1.1. Images overview
An imagestream 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 imagestream, 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
The following sections provide an overview and instructions for using image tags in the context of container images for working with OpenShift Container Platform imagestreams and their tags.
5.2.1. Image tags
An image tag is a label applied to a container image in a repository that distinguishes a specific image from other images in an imagestream. 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 imagestreams instead of directly on images.
5.2.2. Image tag conventions
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>:
| Description | Example |
|---|---|
| Revision |
|
| Architecture |
|
| Base image |
|
| Latest (potentially unstable) |
|
| Latest 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 imagestreams
An imagestream 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 imagestream using the
oc tagcommand:$ oc tag <source> <destination>
For example, to configure the
rubyimagestreamsstatic-2.0tag to always refer to the current image for therubyimagestreams2.0tag:$ oc tag ruby:2.0 ruby:static-2.0
This creates a new imagestreamtag named
static-2.0in therubyimagestream. The new tag directly references the image id that theruby:2.0imagestreamtag pointed to at the timeoc tagwas run, and the image it points to never changes.To ensure the destination tag is updated whenever the source tag changes, use the
--alias=trueflag:$ oc tag --alias=true <source> <destination>
Use a tracking tag for creating permanent aliases, for example, latest or stable. The tag only works correctly within a single imagestream. Trying to create a cross-imagestream alias produces an error.
-
You can also add the
--scheduled=trueflag to have the destination tag be refreshed, or re-imported, periodically. The period is configured globally at the system level. The
--referenceflag creates an imagestreamtag that is not imported. The tag points to the source location, permanently.If you want to instruct OpenShift 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-registryto the container runtime as long as the imagestream has an insecure annotation or the tag has an insecure import policy.
5.2.4. Removing tags from imagestreams
You can remove tags from an imagestream.
Procedure
To remove a tag completely from an imagestream run:
$ oc delete istag/ruby:latest
or:
$ oc tag -d ruby:latest
5.2.5. Referencing images in imagestreams
You can use tags to reference images in imagestreams using the following reference types.
| Reference type | Description |
|---|---|
|
|
An |
|
|
An |
|
|
A |
When viewing example imagestream 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 imagestream. You should never have to explicitly define an ImageStreamImage object in any imagestream definition that you use to create imagestreams.
Procedure
To reference an image for a given imagestream and tag, use
ImageStreamTag:<image_stream_name>:<tag>
To reference an image for a given imagestream and image
shaID, useImageStreamImage:<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
NoteWhen 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.2.6. Additional information
- Example imagestream definitions for CentOS imagestreams.
5.3. Image pull policy
Each container in a Pod has a container image. Once 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
When OpenShift Container Platform creates containers, it uses the container’s imagePullPolicy to determine if the image should be pulled prior to starting the container. There are three possible values for imagePullPolicy:
| Value | Description |
|---|---|
|
| Always pull the image. |
|
| Only pull the image if it does not already exist on the node. |
|
| Never pull the image. |
If a container’s imagePullPolicy parameter is not specified, OpenShift Container Platform sets it based on the image’s tag:
-
If the tag is
latest, OpenShift Container Platform defaultsimagePullPolicytoAlways. -
Otherwise, OpenShift Container Platform defaults
imagePullPolicytoIfNotPresent.
5.4. Using image pull secrets
If you are using OpenShift Container Platform’s internal registry and are pulling from imagestreams located in the same project, then your Pod’s 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, then additional configuration steps are required.
5.4.1. Allowing Pods to reference images across projects
When using the internal 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.
Procedure
To allow Pods in project-a to reference images in project-b, bind a service account in project-a to the
system:image-pullerrole in project-b:$ oc policy add-role-to-user \ system:image-puller system:serviceaccount:project-a:default \ --namespace=project-bAfter adding that role, the pods in project-a that reference the default service account are able to pull images from project-b.
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
The .dockercfg $HOME/.docker/config.json file for Docker clients is a Docker credentials file that stores your authentication information if you have previously logged into a secured or insecure registry.
To pull a secured container image that is not from OpenShift Container Platform’s internal registry, you must create a pull secret from your Docker credentials and add it to your service account.
Procedure
If you already have a
.dockercfgfile for the secured registry, you can create a secret from that file by running:$ oc create secret generic <pull_secret_name> \ --from-file=.dockercfg=<path/to/.dockercfg> \ --type=kubernetes.io/dockercfgOr if you have a
$HOME/.docker/config.jsonfile:$ oc create secret generic <pull_secret_name> \ --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ --type=kubernetes.io/dockerconfigjsonIf you do not already have a Docker credentials file for the secured registry, you can create a secret by running:
$ oc create secret docker-registry <pull_secret_name> \ --docker-server=<registry_server> \ --docker-username=<user_name> \ --docker-password=<password> \ --docker-email=<email>To use a secret for pulling images for Pods, you must add the secret to your service account. The name of the service account in this example should match the name of the service account the Pod uses.
defaultis the default service account:$ oc secrets link default <pull_secret_name> --for=pull
To use a secret for pushing and pulling build images, the secret must be mountable inside of a Pod. You can do this by running:
$ oc secrets link builder <pull_secret_name>
5.4.2.1. Pulling from private registries with delegated authentication
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
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-ssoCreate 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
You can update the global pull secret for your cluster.
Cluster resources must adjust to the new pull secret, which can temporarily limit the usability of the cluster.
Prerequisites
- You have a new or modified pull secret file to upload.
-
You have access to the cluster as a user with the
cluster-adminrole.
Procedure
Run 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
- Provide the path to the new pull secret file.
This update is rolled out to all nodes, which can take some time depending on the size of your cluster. During this time, nodes are drained and Pods are rescheduled on the remaining nodes.
