provisioning: Document Podman Machine

[cgwalters]

I was watching https://containerplumbing.org/sessions/2023/when_podman_desktop_eats which demoed customizing the FCOS OS image, and I think it's long overdue that we cross-link Podman Machine from the FCOS docs!

[bgilbert]

Hmm, this doesn't seem like a good fit. Podman Machine isn't a platform (note that it doesn't have a platform ID), it's essentially a layered project that uses FCOS on existing platforms. And the new docs page basically says "see the docs for Podman Machine", which isn't especially useful either.

Let's add it to the Projects Using Fedora CoreOS page instead?

[cgwalters]

I think Podman Machine is architecturally similar to https://docs.fedoraproject.org/en-US/fedora-coreos/provisioning-qemu/ in terms of when one would use it. (Yes, one can use raw qemu for "production" use cases, but this seems unusual). You're right that at a technical level, it doesn't have its own "platform" ID - but from the user PoV of "I want to boot a FCOS system", does it matter whether it has a platform ID or not?

[cgwalters]

(You're right that it'd make sense too on the "using" page for sure)

Hmmm...perhaps what would make sense is to reorganize the "provisioning" page to have two sections:

• Cloud and Bare Metal (production and pre-production testing)
• Local (non-cloud hypervisors) and I think Podman Machine would be featured prominently here

[bgilbert]

The lack of a platform ID is a symptom of the fact that users aren't launching FCOS directly in that case. (In fact, Podman Machine VMs will have multiple platform IDs under the covers, for macOS vs. Windows etc.) They're using it as part of Podman, and FCOS is mostly an implementation detail.

From my perspective there isn't any difference between "how to use Podman Machine, which uses FCOS" and "how to use Typhoon, which can use FCOS". There may be value to having them on the site, but they're not really about how to use FCOS, and we don't have a place to put them in our current structure. In particular, I don't think the docs should privilege Podman Machine over other layered projects.

[dustymabe]

@cgwalters
(You're right that it'd make sense too on the "using" page for sure)

Yeah. I agree this would probably be best on the "using" page, but...

@bgilbert
From my perspective there isn't any difference between "how to use Podman Machine, which uses FCOS" and "how to use Typhoon, which can use FCOS". There may be value to having them on the site, but they're not really about how to use FCOS, and we don't have a place to put them in our current structure.

I think it would be nice if our "using" page (or something like it) could have more expanded sections about either projects that layer on top of FCOS (OKD, Typhoon, Podman Machine) OR projects that could be used in conjunction with FCOS (something like instructions for use with k3s), which is where something like this could go.

[cgwalters]

From my perspective there isn't any difference between "how to use Podman Machine, which uses FCOS" and "how to use Typhoon, which can use FCOS".

I see your point, but there are also some concrete differences. One notable one is that PM (just going to abbreviate) always uses FCOS, whereas Typhoon does not (though they do make it relatively clear though that you have to pick).

I'd also say that there's quite a difference between provisioning one machine (as everything else on that page does) that is accessible via ssh and provisioning a Kubernetes cluster.

but they're not really about how to use FCOS

They are actually adding FCOS specific features; at Container Plumbing days Ashley demoed containers/podman#17494

[jlebon]

This seems to be catering to people who might use podman machine as a means to an end (of using FCOS)? People on macOS (and soon Windows) may prefer the easy UX provided by podman machine to get an FCOS machine rather than directly using QEMU/Hyper-V. If they actually want podman machine for podman, then they'd go to the podman docs.

For that purpose, I think I'd reframe it as more generic "Booting on macOS" and "Booting on Windows" pages listing the options available on those platforms (and linking to the relevant hypervisor-specific page, e.g. QEMU or VirtualBox or soon Hyper-V), but also talking about podman machine as another way to bring up FCOS on those hypervisors.

[cgwalters]

For that purpose, I think I'd reframe it as more generic "Booting on macOS" and "Booting on Windows" pages listing the options available on those platforms (and linking to the relevant hypervisor-specific page, e.g. QEMU or VirtualBox or soon Hyper-V), but also talking about podman machine as another way to bring up FCOS on those hypervisors.

💯 agree. Any objections to reworking the provisioning page around those lines from anyone?

[dustymabe]

I think I agree. So basically we'd create two new pages called "Booting on macOS" and "Booting on Windows" under our provisioning tree?

SGTM

[cgwalters]

If we add those sections, it does kind of argue to potentially also split off other sections as I mentioned here right?

But then I was thinking about it more and there's a lot of overlap between where this thread went and what we have on https://getfedora.org/en/coreos/download right?

So we could:

• Rework our docs to match the getfedora layout and nomenclature (i.e. we have separate "cloud launchable" and "bare metal" and "For cloud operators" sections in our docs too)
• Change each getfedora section to link to the corresponding docs section (this seems like a no-brainer?)
• Add a "macOS and Windows" section to both our docs and getfedora

?

[bgilbert]

The "for cloud operators" section is meant to imply that users don't need to download those images, because cloud operators will ingest them directly and present them through the cloud UI. That's not actually true in all cases, though. On some clouds users need to download and re-upload the image, and on some they need to put the image URL directly into the cloud UI.

Leaving that aside, I don't think we should document those clouds as though only the cloud operator can run FCOS! They'd all go in a "cloud" section if we had one.