Develop capability to fetch consolidated image metadata, equivalent to skopeo inspect

[cmoulliard]

Question

Can this python get the following information of an image ?

❯ skopeo inspect docker://paketobuildpacks/builder-ubi8-base:0.0.204
{
    "Name": "docker.io/paketobuildpacks/builder-ubi8-base",
    "Digest": "sha256:fbedab6060b4bb6c7bc695e43107469cec4f54da48cba752a9298b023b349ad5",
    "RepoTags": [
        "0.0.199",
        "0.0.200",
        "0.0.201",
        "0.0.202",
        "0.0.203",
        "0.0.204",
        "0.0.205",
        "latest"
    ],
    "Created": "1980-01-01T00:00:01Z",
    "DockerVersion": "",
    "Labels": {
        "architecture": "x86_64",
        "build-date": "2025-04-16T09:03:23",
        "com.redhat.component": "ubi8-minimal-container",
        "com.redhat.license_terms": "https://www.redhat.com/en/about/red-hat-end-user-license-agreements#UBI",
        "description": "The Universal Base Image Minimal is a stripped down image that uses microdnf as a package manager. This base image is freely redistributable, but Red Hat only supports Red Hat technologies through subscriptions for Red Hat products. This image is maintained by Red Hat and updated regularly.",
        "distribution-scope": "public",
        "io.buildah.version": "1.33.12",
...
    "Architecture": "amd64",
    "Os": "linux",
    "Env": [
        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "container=oci",
        "CNB_USER_ID=1002",
        "CNB_GROUP_ID=1000",
        "CNB_STACK_ID=io.buildpacks.stacks.ubi8"
    ],
    "Layers": [
        "sha256:0610017febcdb537d22d8fa7ca25918986a37606290a99250cc6d1c4b3c48911",
        "sha256:a5cce32eabe23faa4bb888137c9ffee420b2a5cc499434aa767062b12005c2a0",
        "sha256:d284d79fd468a82e1007a24e562ae64868b97447b5bd101dfb6e823618e08950",
        "sha256:89732bc7504122601f40269fc9ddfb70982e633ea9caf641ae45736f2846b004"
...

[cmoulliard]

The answer is yes. I think that we should improve the class ContainerImage maybe to add some get_ methods able to display them instead of doing this

manifest = my_image.get_manifest(auth=auth)
config_dict = ContainerImageRegistryClient.get_config(str_or_ref=image_ref,config_desc=manifest.get_config_descriptor(),auth=auth)
config = ContainerImageConfig(config_dict)
img_config = config.config.get("config")

labels = img_config.get("Labels", {})
env_vars = img_config.get("Env", [])

print("Labels:")
for k, v in labels.items():
   print(f"{k}: {v}")

print("\nEnv Vars:")
for e in env_vars:
   print(e)

[whatsacomputertho]

Thanks @cmoulliard agreed it should be pretty straightforward to write up a method for producing the same output (possibly as a class / type) as skopeo inspect in native python via this library. I will use this issue to track that work if you don't mind me updating the title / description. We can put that into the v1.0.0-beta.1 release.

[cmoulliard]

Here is a more verbose example I created to generate for a Tekton Task some results.
Remark: I still need to check if the AUTH is not null and throw an error

import json

import image.auth
from image.client import ContainerImageRegistryClient
from image.config import ContainerImageConfig
from image.containerimage import ContainerImage

def write_to_results(filename, content):
    with open(filename, "w") as f:
        f.write(content)

# The AUTH constant contains the loaded contents from the container engine
# auth file.  This is located at $XDG_RUNTIME_DIR/containers/auth.json on linux
# and $HOME/.config/containers/auth.json on mac and windows
#
# The AUTH constant remains an empty dict if the user has no auth file.  A
# UserWarning is raised if the user's auth file does exist, but contains invalid
# JSON.
AUTH = image.auth.AUTH
#IMAGE_REF = "docker.io/paketobuildpacks/builder-ubi8-base:0.0.204"
IMAGE_REF = "docker.io/paketobuildpacks/builder-jammy-full:0.3.481"
EXTENSION_LABELS = "io.buildpacks.extension.layers"

# Get the MANIFEST of the builder image: layers, arch, labels, env var, etc.
builder_image = ContainerImage(IMAGE_REF)
manifest = builder_image.get_manifest(auth=AUTH)

# Extract from the MANIFEST the configuration containing
# the following information: env, labels, os, architecture, etc.
config_dict = ContainerImageRegistryClient.get_config(str_or_ref=IMAGE_REF,config_desc=manifest.get_config_descriptor(),auth=AUTH)
config = ContainerImageConfig(config_dict)
img_config = config.config.get("config")

# Get the Env variables and check if they contain the CNB_* variables
# If the variables exist, set the corresponding Tekton results variable
env_vars = img_config.get("Env", [])
if env_vars:
    env_dict = dict(item.split("=", 1) for item in env_vars if "=" in item)

    CNB_USER_ID = env_dict.get("CNB_USER_ID")
    if CNB_USER_ID:
        write_to_results("CNB_USER_ID.txt",CNB_USER_ID)
    else:
        print(f"No CNB_USER_ID env var found within the builder image: {IMAGE_REF} !")

    CNB_GROUP_ID = env_dict.get("CNB_GROUP_ID")
    if CNB_GROUP_ID:
        write_to_results("CNB_GROUP_ID.txt",CNB_GROUP_ID)
    else:
        print(f"No CNB_GROUP_ID env var found within the builder image: {IMAGE_REF} !")
else:
    print(f"No env var found within the builder image: {IMAGE_REF} !")

# Get the labels and check if they contain the label: io.buildpacks.extension.layers
# If the label exists, set the corresponding Tekton results variable
labels = img_config.get("Labels", {})
metaData = labels.get(EXTENSION_LABELS)

if metaData and metaData != '{}':
    parsed = json.loads(metaData)
    extension_labels = json.dumps(parsed, indent=4)
    print(f"Extension layers: {extension_labels}")
    write_to_results("EXTENSION_LABELS.txt",extension_labels)
else:
    print(f"No extension labels have been defined within the builder image: {IMAGE_REF} !")

[whatsacomputertho]

Moved to in-progress as I plan to (hopefully) work on this today

[whatsacomputertho]

Hey @cmoulliard I spent some time this weekend making a start on this.

• feat(inspect): implement python-native skopeo inspect #34

It's a WIP for now but the basic functionality seems to work with some limitations and slight differences with respect to skopeo inspect. Still to-do in this initial pass through:

1. Add the RepoTags property, I forget if I have the API call for this so it may involve writing that client functionality
2. Conditionally do not include certain properties, as skopeo seems to do this (i.e. Tag and Author is not included in the skopeo output below)
3. Consider modifying some of the default values to match skopeo's behavior (i.e. Labels is an empty dict in containerimage-py if no labels, but in skopeo it is just null)
4. Develop a v2s1 manifest extension, as there are some inspect properties that uniquely come from v2s1 manifests (i.e. DockerVersion)
5. Write unit tests for all the new methods

Using containerimage-py

Command (I'm on darwin/amd64 hence the override)

HOST_OS=linux python3.9 examples/image-inspect.py

Output

{
  "Name": "registry.k8s.io/pause",
  "Digest": "sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07",
  "DockerVersion": "",
  "Created": "2021-03-16T13:16:57.822648569Z",
  "Labels": {},
  "Architecture": "amd64",
  "Variant": "",
  "Os": "linux",
  "Layers": [
    "sha256:019d8da33d911d9baabe58ad63dea2107ed15115cca0fc27fc0f627e82a695c1"
  ],
  "LayersData": [
    {
      "MIMEType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "Digest": "sha256:019d8da33d911d9baabe58ad63dea2107ed15115cca0fc27fc0f627e82a695c1",
      "Size": 296517,
      "Annotations": {}
    }
  ],
  "Env": [
    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  ],
  "Author": "",
  "Tag": "3.5"
}

Using skopeo

Command (I'm on darwin/amd64 hence the override)

skopeo inspect docker://registry.k8s.io/pause:3.5 --override-os linux

Output

{
    "Name": "registry.k8s.io/pause",
    "Digest": "sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07",
    "RepoTags": [
        "0.8.0",
        "1.0",
        "2.0",
        "3.0",
        "3.1",
        "3.10",
        "3.2",
        "3.3",
        "3.4.1",
        "3.5",
        "3.6",
        "3.7",
        "3.8",
        "3.9",
        "go",
        "latest",
        "sha256-193fcedcfac410b3484b96f06c8a2cf750bcdb60b44b914798ec74b0ab8fb730.sig",
        "sha256-41ff8c30d6555f5dd6991884d258d7c24b9aeee2d2b75eaa24391f9c702da04b.sig",
        "sha256-7031c1b283388d2c2e09b57badb803c05ebed362dc88d84b480cc47f72a21097.sig",
        "sha256-7c38f24774e3cbd906d2d33c38354ccf787635581c122965132c9bd309754d4a.sig",
        "sha256-89e51d7a4cb6a0436b23d34d28ee4ed16721a6853c4b76177c552d7d0ca4b8a7.sig",
        "sha256-8a5fb194104a55b306eecde523eeebcb12d46d7e4990fc9c1a78f8265efc1ced.sig",
        "sha256-9001185023633d17a2f98ff69b6ff2615b8ea02a825adffa40422f51dfdcde9d.sig",
        "sha256-e3ecdc4b6bd38ce47123195d566292581080abbb51b80603a9168f84fef0d1a2.sig",
        "sha256-e50b7059b633caf3c1449b8da680d11845cda4506b513ee7a2de00725f0a34a7.sig",
        "sha256-ee6521f290b2168b6e0935a181d4cff9be1ac3f505666ef0e3c98fae8199917a.sig",
        "test",
        "test2"
    ],
    "Created": "2021-03-16T13:16:57.822648569Z",
    "DockerVersion": "",
    "Labels": null,
    "Architecture": "amd64",
    "Os": "linux",
    "Layers": [
        "sha256:019d8da33d911d9baabe58ad63dea2107ed15115cca0fc27fc0f627e82a695c1"
    ],
    "LayersData": [
        {
            "MIMEType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
            "Digest": "sha256:019d8da33d911d9baabe58ad63dea2107ed15115cca0fc27fc0f627e82a695c1",
            "Size": 296517,
            "Annotations": null
        }
    ],
    "Env": [
        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    ]
}

[whatsacomputertho]

I've removed the v2s1 sub-issue from this issue. Per my comment in that sub-issue:

Just been thinking more about this issue, I think this one can safely be moved out to a future release. Most images by now should NOT implement the Docker v2s1 manifest spec. Until this is implemented we can just claim no backward compatibility but build it in eventually.

I will focus on just getting the RepoTags API call in place to wrap up the majority of this ticket

[whatsacomputertho]

I expect my PR implementing this feature to be complete tomorrow

• feat(inspect): implement python-native skopeo inspect #34