cmd: support nerdctl manifeset inspect #4413

ChengyuZhu6 · 2025-07-14T10:00:01Z

Fixes: #4414 -- part I

ChengyuZhu6 · 2025-07-16T07:33:12Z

# nerdctl pull --all-platforms ghcr.io/stargz-containers/alpine:3.13-org

Example 1:

disable verbose

# nerdctl manifest inspect ghcr.io/stargz-containers/alpine:3.13-org
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
    "manifests": [
        {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "digest": "sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310",
            "size": 528,
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            }
        },
        //...more manifests
        {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "digest": "sha256:44f0cac18b69c3867be12e78766393adf801560a102fe0113bb4abc981acf9bf",
            "size": 528,
            "platform": {
                "architecture": "s390x",
                "os": "linux"
            }
        }
    ]
}

enable verbose

# nerdctl manifest inspect ghcr.io/stargz-containers/alpine:3.13-org --verbose
[
    {
        "Ref": "ghcr.io/stargz-containers/alpine:3.13-org@sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310",
        "Descriptor": {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "digest": "sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310",
            "size": 528,
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            }
        },
        "Raw": "ewogICAic2NoZW1hVmVyc2lvbiI6IDIsCiAgICJtZWRpYVR5cGUiOiAiYXBwbGljYXRpb24vdm5kLmRvY2tlci5kaXN0cmlidXRpb24ubWFuaWZlc3QudjIranNvbiIsCiAgICJjb25maWciOiB7CiAgICAgICJtZWRpYVR5cGUiOiAiYXBwbGljYXRpb24vdm5kLmRvY2tlci5jb250YWluZXIuaW1hZ2UudjEranNvbiIsCiAgICAgICJzaXplIjogMTQ3MiwKICAgICAgImRpZ2VzdCI6ICJzaGEyNTY6NDlmMzU2ZmE0NTEzNjc2YzVlMjJlM2E4NDA0YWFkNmM3MjYyY2M3YWFlZDE1MzQxNDU4MjY1MzIwNzg2YzU4YyIKICAgfSwKICAgImxheWVycyI6IFsKICAgICAgewogICAgICAgICAibWVkaWFUeXBlIjogImFwcGxpY2F0aW9uL3ZuZC5kb2NrZXIuaW1hZ2Uucm9vdGZzLmRpZmYudGFyLmd6aXAiLAogICAgICAgICAic2l6ZSI6IDI4MTE5NDcsCiAgICAgICAgICJkaWdlc3QiOiAic2hhMjU2OmNhM2NkNDJhN2M5NTI1ZjZjZTNkNjRjMWE3MDk4MjYxM2E4MjM1ZjBjYzA1N2VjOTI0NDA1MjkyMTg1M2VmMTUiCiAgICAgIH0KICAgXQp9",
        "SchemaV2Manifest": {
            "schemaVersion": 2,
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "config": {
                "mediaType": "application/vnd.docker.container.image.v1+json",
                "digest": "sha256:49f356fa4513676c5e22e3a8404aad6c7262cc7aaed15341458265320786c58c",
                "size": 1472
            },
            "layers": [
                {
                    "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                    "digest": "sha256:ca3cd42a7c9525f6ce3d64c1a70982613a8235f0cc057ec9244052921853ef15",
                    "size": 2811947
                }
            ]
        }
    },
    //...more manifests   
]

ChengyuZhu6 · 2025-07-16T07:36:15Z

Example 2:

disable verbose

# nerdctl manifest inspect ghcr.io/stargz-containers/alpine@sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310
{
    "schemaVersion": 2,
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "config": {
        "mediaType": "application/vnd.docker.container.image.v1+json",
        "digest": "sha256:49f356fa4513676c5e22e3a8404aad6c7262cc7aaed15341458265320786c58c",
        "size": 1472
    },
    "layers": [
        {
            "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
            "digest": "sha256:ca3cd42a7c9525f6ce3d64c1a70982613a8235f0cc057ec9244052921853ef15",
            "size": 2811947
        }
    ]
}

enable verbose

# nerdctl manifest inspect ghcr.io/stargz-containers/alpine@sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310 --verbose
{
    "Ref": "ghcr.io/stargz-containers/alpine@sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310",
    "Descriptor": {
        "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
        "digest": "sha256:e103c1b4bf019dc290bcc7aca538dc2bf7a9d0fc836e186f5fa34945c5168310",
        "size": 528,
        "platform": {
            "architecture": "amd64",
            "os": "linux"
        }
    },
    "Raw": "ewogICAic2NoZW1hVmVyc2lvbiI6IDIsCiAgICJtZWRpYVR5cGUiOiAiYXBwbGljYXRpb24vdm5kLmRvY2tlci5kaXN0cmlidXRpb24ubWFuaWZlc3QudjIranNvbiIsCiAgICJjb25maWciOiB7CiAgICAgICJtZWRpYVR5cGUiOiAiYXBwbGljYXRpb24vdm5kLmRvY2tlci5jb250YWluZXIuaW1hZ2UudjEranNvbiIsCiAgICAgICJzaXplIjogMTQ3MiwKICAgICAgImRpZ2VzdCI6ICJzaGEyNTY6NDlmMzU2ZmE0NTEzNjc2YzVlMjJlM2E4NDA0YWFkNmM3MjYyY2M3YWFlZDE1MzQxNDU4MjY1MzIwNzg2YzU4YyIKICAgfSwKICAgImxheWVycyI6IFsKICAgICAgewogICAgICAgICAibWVkaWFUeXBlIjogImFwcGxpY2F0aW9uL3ZuZC5kb2NrZXIuaW1hZ2Uucm9vdGZzLmRpZmYudGFyLmd6aXAiLAogICAgICAgICAic2l6ZSI6IDI4MTE5NDcsCiAgICAgICAgICJkaWdlc3QiOiAic2hhMjU2OmNhM2NkNDJhN2M5NTI1ZjZjZTNkNjRjMWE3MDk4MjYxM2E4MjM1ZjBjYzA1N2VjOTI0NDA1MjkyMTg1M2VmMTUiCiAgICAgIH0KICAgXQp9",
    "SchemaV2Manifest": {
        "schemaVersion": 2,
        "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
        "config": {
            "mediaType": "application/vnd.docker.container.image.v1+json",
            "digest": "sha256:49f356fa4513676c5e22e3a8404aad6c7262cc7aaed15341458265320786c58c",
            "size": 1472
        },
        "layers": [
            {
                "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                "digest": "sha256:ca3cd42a7c9525f6ce3d64c1a70982613a8235f0cc057ec9244052921853ef15",
                "size": 2811947
            }
        ]
    }
}

ChengyuZhu6 · 2025-07-16T08:59:40Z

cc @AkihiroSuda

cmd/nerdctl/main.go

cmd/nerdctl/manifest/manifest_inspect_test.go

docs/command-reference.md

pkg/testutil/images_linux.go

pkg/testutil/images.yaml

AkihiroSuda · 2025-07-18T03:35:32Z

TestManifestInspect is failing for Docker

https://github.com/containerd/nerdctl/actions/runs/16342021337/job/46172436575?pr=4413

        |         | 🟠 Error response from daemon: "amd64,linux" is an invalid component of "linux/amd64,linux/arm64 |
        |         | ": platform specifier component must match "^[A-Za-z0-9_.-]+$": invalid argument                 |

ChengyuZhu6 · 2025-07-18T05:35:28Z

https://github.com/containerd/nerdctl/actions/runs/16342021337/job/46172436575?pr=4413

I've removed the linux/arm64 flag. Let's see if ci passes now.

ChengyuZhu6 · 2025-07-18T08:44:32Z

I've already make the code change to align the output of nerdctl manifest inspect with docker's format.

- Add nerdctl manifest inspect to display image manifest details, with optional --verbose output. - Implement manifest parsing, formatting, and related type definitions. - Integrate the new command into the CLI. Signed-off-by: ChengyuZhu6 <[email protected]>

Add tests for tag/digest references and verbose modes Signed-off-by: ChengyuZhu6 <[email protected]>

Documented the nerdctl manifest inspect command with usage, flags, and examples. Signed-off-by: ChengyuZhu6 <[email protected]>

apostasie · 2025-07-18T17:21:43Z

@ChengyuZhu6 so, we need the image to be pulled locally to use manifest inspect?

eg: docker manifest inspect AFAIK does not operate on local images at all.

docker pull busybox
docker tag busybox debian
docker manifest inspect debian

^

ChengyuZhu6 · 2025-07-21T02:05:53Z

@ChengyuZhu6 so, we need the image to be pulled locally to use manifest inspect?

eg: docker manifest inspect AFAIK does not operate on local images at all.
docker pull busybox
docker tag busybox debian
docker manifest inspect debian
^

@apostasie For the current implementation, yes. I think we should reuse the metadata that is already stored in the image store, instead of fetching it from the remote. If the image does not exist locally, we should then fetch the manifests from the remote source. I have created a tracking issue to monitor the progress of nerdctl manifest inspect. This PR focuses on images that have already been pulled, and the next PR will address images that are not stored locally.

apostasie · 2025-07-21T06:13:14Z

I am not sure this is desirable, as the behavior would be radically different from docker?

ChengyuZhu6 · 2025-07-21T10:47:36Z

I am not sure this is desirable, as the behavior would be radically different from docker?

Got your point. Are you worried about the potential inconsistency between the remote registry and the local image store?

apostasie · 2025-07-23T19:54:02Z

I am not sure this is desirable, as the behavior would be radically different from docker?

Got your point. Are you worried about the potential inconsistency between the remote registry and the local image store?

Yes, that would definitely be a concern (and a source of discrepancies with docker behavior).

Also, the way docker works, manifest is useful to retrieve information from a remote image without having to pull it.
I think this is the important part ^.

apostasie · 2025-07-23T19:54:23Z

Apologies for the slow answer @ChengyuZhu6
I have been away for a bit.

ChengyuZhu6 · 2025-07-25T06:19:29Z

Apologies for the slow answer @ChengyuZhu6 I have been away for a bit.

Thank you for noticing that. I will make the correction.

ChengyuZhu6 force-pushed the manifest branch 2 times, most recently from 25333c7 to 4d459d2 Compare July 15, 2025 08:41

ChengyuZhu6 changed the title ~~cmd: initialize manifest command~~ cmd: support nerdctl manifeset inspect Jul 15, 2025

ChengyuZhu6 force-pushed the manifest branch 5 times, most recently from 4eca9da to edf0eef Compare July 16, 2025 03:21

ChengyuZhu6 mentioned this pull request Jul 16, 2025

Track development: nerdctl manifest inspect #4414

Open

2 tasks

ChengyuZhu6 force-pushed the manifest branch from edf0eef to 40188e0 Compare July 16, 2025 07:26

ChengyuZhu6 marked this pull request as ready for review July 16, 2025 07:37

ChengyuZhu6 force-pushed the manifest branch 10 times, most recently from f829fa7 to 9af688c Compare July 16, 2025 08:37

AkihiroSuda added this to the v2.1.4 milestone Jul 17, 2025