Identifying Container Images

FlexNet Manager Suite 2022 R1 (On-Premises)

There are multiple ways to identify an image used to instantiate containers.

Image name

A container image has a name which may contain lower-case letters, numbers, and separators (defined as a period, one or two underscores, or one or more dashes – none of which may be the first or last character of a component of the image name). The name may be made up of multiple components:
  • The repository component, which may include slash-separated elements:
    • Optionally, the hostname of the registry storing the image. In additional to normal DNS rules for host naming, the registry hostname may not contain underscores.
    • Optionally, a port number in the normal format :8080.
      Tip: If the registry hostname is not present, the image is assumed to be saved in Docker’s public registry, located at registry-1.docker.io by default.
    • The name of the registry stored on that host
  • A colon (:) separator
  • A tag name of up to 128 characters, using valid ASCII upper- and lower-case letters, digits, underscores and (except as the first character of the tag) periods and dashes. Each tag:
    • Refers to exactly one discrete image at a given point in time
    • May be one of several tags that point to a single image
    • May be moved to refer to a different image.

Image ID

The images used to instantiate containers are widely referenced by using names; but within the container runtime, the images are identified using IDs. This is because, unlike names (which can be transferred between images), the ID is a digest generated as a hash of the image content. For this reason, an ID always uniquely identifies the image in its current form. Any change in the image, whether in its component layers or in its additional metadata, results in a change in its hash digest. So the image ID always, and uniquely, identifies the one image in its current state; and it is neither possible for this ID to point to a different image, nor for a given image (in an unchanged state) to have a different ID.

In Docker you can inspect the image ID for a named image like this:
$ docker inspect images.example.com/foo:latest --format={{.ID}}
sha256:b2fcd079c1d403dc1dba5397ca1bca606f17ebcf99b03b66c59941929acff57c

Repo Digest

Container images are stored and shared through the registry, with the relationship between image and registry stored in some additional metadata. This metadata gives rise to the Repo Digest, which includes both the registry component of the image name (the portion before the colon :), and its tag. Although technically the Repo Digest is an array, the imgtrack script always uses the first value in that array and ignores any others than may be present.

Because the Repo Digest tracks the relationship between image and repository, it is only generated when the image is first pushed to the registry. An image built on the local computer and not yet pushed to a registry does not have a Repo Digest. It is important, therefore, to push any local image to the repository before invoking the imgtrack script.

In Docker you can view the Repo Digest(s) for an image like this:
$ docker inspect images.example.com/foo:latest --format='{{join .RepoDigests ","}}'
images.example.com/foo@sha256:6647385dd9ae11aa2216bf55c54d126b0a85637b3cf4039ef24e3234113588e3

Choosing the ID to use

It's helpful to keep the difference between the true image ID and its Repo Digest clearly in mind, for these reasons:
  • The Kubernetes API (mis-)uses the label ImageID, but the content in this value is actually the image's Repo Digest.
  • When either the Flexera Kubernetes inventory agent or the lightweight Kubernetes agent reports inventory from the Kubernetes API, it therefore reports the image's Repo Digest.
  • When imgtrack inspects the source image, it attempts to capture both the image ID and the Repo Digest.
    Remember: The Repo Digest for a locally-built image only exists after the image has been pushed to the repository. Be sure that each image has been pushed to a repository (or is a shared image that has previously been pushed, and has now been pulled from the repository for inspection) before invoking the imgtrack script.
  • Correct merging of records from the Kubernetes agent(s) and the imgtrack script requires that they are using the same ID for each image.
  • Therefore, if the Repo Digest is not empty, imgtrack uses its first entry to identify the image, allowing for simple matching with the ID values collected from Kubernetes. If the Repo Digest is empty/missing, imgtrack uses the image ID.

FlexNet Manager Suite (On-Premises)

2022 R1