Choosing image tags or digests

To make sure that a container always uses the same version of an image, you can specify its digest. The digest identifies a specific version of the image, so it is never updated by Kubernetes. Knowing how image tags work, helps you to decide whether to use tags or to use the digest instead.

Image tags

Image tags are a volatile reference to an image version at a specific point in time. Images on Docker Hub, for example, typically have tags for major and minor versions of images that get updated over time. The tag redis:3 is the same image as redis:3.2.11 at the time of release, but in the past this tag pointed to redis:3.2.10.

Cloud Pak for Business Automation also delivers tagged container images from IBM Entitled Registry and Passport Advantage® (PPA) that indicate the version number. For example, some images include the Cloud Pak version. 

image:
   tag: 21.0.x

Some images include an identifier and a version number specific to that container image. For example, the image for Content Platform Engine (CPE) includes p8cpe and 555.

image:
   tag: ga-555-p8cpe

Tags can also be used to convey useful information about a specific image version or variant. IT admins can use tags to be more intentional and specific about the container images they pull from a repository. Admins can create an alias (a reference) to a source image to assign an existing image another name to refer to it. The tags in this case can help developers and admins differentiate between the various available images in a repository, and can play a key role in the development lifecycle. Developers can use the tags to, for example, restrict the use of infrastructure for development purposes.

Cloud Pak for Business Automation provides a shared configuration parameter to set a tag for all the container images included in the custom resource instead of setting a parameter for each individual image. For more information about sc_image_tag, see Shared configuration.

Digests

Image tag mutability is useful and convenient in many scenarios, but it can also be dangerous if you are not aware and prepared to manage it. Avoid the :latest tag when you deploy containers in production as it is harder to track which version of the image is running and more difficult to roll back properly. Tag mutability can cause security issues like bypassing image scanning checks. To get deterministic and repeatable deployments, use digests instead of tags. When the operator uses a digest, it takes the image@sha256:<digestValue> instead of image:tag to ensure that you deploy the exact same image manifest.

The following scenarios determine when image tags are used and when digests are used. Image tags are used in the following cases.

  • The custom resource specifies sc_image_repository with an internal registry.
  • The custom resource specifies sc_image_repository with cp.icr.io (IBM Entitled Registry) and the component configuration image tags are defined.

Digests are used when the image tags are left empty.

  • The custom resource specifies sc_image_repository with cp.icr.io (IBM Entitled Registry) and the component configuration image tags are not defined.

For more information, see Checking and completing your custom resource.

Using the digest for the IBM Cloud Pak® for Business Automation container images is a requirement for an air gap configuration on clusters that might be disconnected from the internet. Air gap gives you more control and minimizes risk by using a network demilitarized zone (DMZ). OpenShift Container Platform (OCP) can automatically redirect image pull requests from a specified registry location to an alternative location. The redirect is fundamental to enabling an air gap for disconnected installations, as it removes the need to update image references in every pod definition.

For more information, see Installing an offline (air gap) environment.