Create Documentation for How to Use Manifests

[fatherlinux]

Is this a BUG REPORT or FEATURE REQUEST? (leave only one on its own line)

/kind feature

Description

Need a set of docs focused on creating image manifests and cross platform images. I believe most of the work is done here:

mailing list with steps for using manifsts and making them work

Steps to reproduce the issue:

1. Go to podman.io, click on Documentation, then click on search, and type "manifest" in the search box.

Describe the results you received:

The only thing that comes up is man pages. The man pages don't have all of the extra detail of a tutorial nor good examples. The man pages would augment this proposed documentation.

Describe the results you expected:
User should find a nice tutorial based off of the the steps described here:

mailing list with steps for using manifsts and making them work

Additional information you deem important (e.g. issue happens only occasionally):
I contemplated making this a RHEL documentation request, but I think it would be better upstream. Upstream first is the right approach for this.

[fatherlinux]

Not sure how to change the label to documentation.

[rhatdan]

Just click labels and add documentation label

[rhatdan]

I have begun writing a blog on building multi-arch containers, which I think would handle some of this.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[rhatdan]

@cevich could you write up a Windows Doc on what you have done so far, and then I can add some content to finally document this.

[cevich]

Sure I'm happy to help get this started, but "Windows" Doc? Do you mean a Google doc, or something else?

The man pages don't have all of the extra detail of a tutorial nor good examples.

This is probably still true, though the situation is VASTLY improved since the opening of this issue. The man pages give details about all minutia but don't describe how to put the pieces together.

[cevich]

@nalind @rhatdan Since I've only really played with multi-arch manifest lists, can you share some ideas of how an image-index might be useful? Also, is there any way to produce one using a single build command with the the --manifest option and one Containerfile?

[nalind]

An image index is just the name for the OCI version of what Docker calls a manifest list, and the tools convert to one or the other format as needed. If you push a list, and optionally with its images, to a dir: location and specify one format or the other for the images, you'll get either a manifest list or an image index, as appropriate.

While there are more than a couple of differences between the two formats, when examining one to figure out what I'm looking at, I tend to look for two things:

• An image index doesn't have a mediaType defined at the top level of the index itself. A manifest list will declare itself as being of type "application/vnd.docker.distribution.manifest.list.v2+json".
• The docker formats don't support annotation fields, so the presence of one anywhere in the JSON document means you're looking at something in OCI format. We don't tend to add those unless buildah manifest annotate --annotation is used, though.

So, yes, --manifest can create image indexes (indices?).

[cevich]

Ahh okay, so from a users POV they're basically the same thing and our tooling should transparently convert as needed. Thanks for the explanation.

How about the practical side...can y'all think of anything else a manifest list is useful for, besides multi-arch/multi-platform?

Is there even another mechanism for selecting what image in the manifest list is run (besides arch and/or platform)?

[nalind]

AFAIK they're designed for this one purpose only. The spec doesn't really provide for anything else.

[cevich]

Thanks for the link. Oh, I see there's an os.version field, neat. Okay, so it could be used for other purposes, but this is the main one so I'll ignore the others in my doc. Thanks for the guidance.

[cevich]

The podman.io blog on this topic is up. Working on man-page updates now, loosely based on that content.