skopeo inspect failing on Apple Silicone Mac OS X because of the os metadata field?

[diraneyya]

Hello,

In order to test skopeo I started with a trivial inspection command:

skopeo inspect docker://docker.io/library/alpine:latest

This seems not to work on my Apple Silicone MacBook Pro with a message indicating it might be an issue with the architecture, which you can see below:

FATA[0001] Error parsing manifest for image: choosing image instance: no image found in image index for architecture "arm64", variant "v8", OS "darwin" 

In this case, I knew that this image was available for most architectures (including mine), but still, guided by the error message I went ahead and tried to do the same thing on an AMD64 machine, which worked as shown below:

# skopeo inspect docker://docker.io/library/alpine:latest
{
    "Name": "docker.io/library/alpine",
    "Digest": "sha256:a8560b36e8b8210634f77d9f7f9efd7ffa463e380b75e2e74aff4511df3ef88c",
    "RepoTags": [
        "2.6",
        "2.7",
# ...
        "3.9.6",
        "edge",
        "latest"
    ],
    "Created": "2025-02-14T03:28:36Z",
    "DockerVersion": "",
    "Labels": null,
    "Architecture": "amd64",
    "Os": "linux",
    "Layers": [
        "sha256:f18232174bc91741fdf3da96d85011092101a032a93a388b79e99e69c2d5c870"
    ],
    "Env": [
        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    ]
}

Using a manual call to the docker registry REST API from my Apple Silicone device, however:

curl https://registry.hub.docker.com/v2/repositories/library/alpine/tags | jq '.results[] | {name: .name, architectures: [.images[].architecture] | unique}'

I get the following:

{
  "name": "latest",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.21.3",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.21",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.20.6",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.20",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.19.7",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.19",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.18.12",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3.18",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ]
}
{
  "name": "3",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ]
}

Looking more into it, I decided to also inspect the variant and os features as well:

curl https://registry.hub.docker.com/v2/repositories/library/alpine/tags | jq '.results[] | {name: .name, architectures: [.images[].architecture] | unique, variants: [.images[].variant] | unique, os: [.images[].os] | unique}'

And I got the following:

{
  "name": "latest",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.21.3",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.21",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.20.6",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.20",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.19.7",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.19",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.18.12",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3.18",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}
{
  "name": "3",
  "architectures": [
    "386",
    "amd64",
    "arm",
    "arm64",
    "ppc64le",
    "riscv64",
    "s390x",
    "unknown"
  ],
  "variants": [
    null,
    "v6",
    "v7",
    "v8"
  ],
  "os": [
    "linux",
    "unknown"
  ]
}

So my question becomes the following:
... is expecting the "os" field to be "darwin" by the tool a good design choice since this official (and likely most conformant Docker image) does not seem to follow this requirement? and would having the tool fail on such a rudimentary command be a bug? a design issue? etc.

I would recommend that if my understanding of the issue is correct, that an os value of unknown be accepted on a Mac OS X machine.

[mtrmac]

Thanks for reaching out.

Whether this behavior is a good idea is, now, years later, basically moot; it’s the documented/stable behavior, it’s almost certainly used in various scripts and other automation, and we simply chan’t change it any more.

If you want to query properties of the Linux image, us --override-os linux, and similarly for other architectures.

Ultimately, the long-term solution is probably going to be #1283 .

[diraneyya]

Thank you so much for the response.

Great! --override-os linux solved my problem and probably is what I needed to know, thanks for pointing it out!

In your experience, is it always the case that arm64 images are published with an os metadata property of linux? For example, is it also possible that some images might designate such images as of os=unknown? The reason I am asking this, is because then the right cli-option concept would be something like --ignore-os. It is also a simpler concept that can also be applied to matching architecture (e.g. --ignore-arch). Is such a thing available or would it make things easier for the user?

Sorry if you are having this conversation for the millionth time, I am really new to this project!

Thanks.

[mtrmac]

The behavior is to specifically look for images that match the current system. linux does not match and would never be found; unknown is not defined by the spec, and AFAIK used for SBOM non-images and the like, so those should not be found.

---

As for --ignore…, how would that be used? Consider that the different per-architecture variants can, in principle, have wildly-different contents, so inspecting with --ignore…, obtaining some data, and then using the image on a different platform than the one --ignore… happened to chose, would EDIT not be useful.

For the platform-specific fields, the user must know what platform is relevant.

[diraneyya]

I am building a cli tool that can use another machine with docker installed to download and export a rootfs tarball archive, to be used on the first machine 🤪.

Here is the tool I am working on https://github.com/diraneyya/docker2lxc and it is just for fun!