docs: registries.conf: mention Podman Machine

[vrothberg]

After a wild ride helping to configure a mirror for docker.io for Podman on the Mac, I feel we need to improve the docs a bit.

When running against a Podman Machine, registries.conf is read server-side only. That means that mirrors need to be configured inside the virtual Linux machine. In addition to that, things can start falling apart when adding a config to the HOME directory of the default non-root (core) users of tha machine.

That means mirrors should be configured globally in /etc/containers/registries.conf[.d].

@rhatdan @mtrmac PTAL

[vrothberg]

@mtrmac: What are your thoughts on allowing c/image to recurse into sub-directories for drop-in folders? Thinking about a feature for Podman Desktop to allow for adding mirrors, it sounds tempting to have a /etc/containers/registries.conf.d/podman-desktop/.... The files could certainly also be namespaced in the same directory but it feels more straightforward to have separate sub-dir.

[Luap99]

This is misleading/wrong, consider that podman machine init now pull the disk image from a oci registry on the host it makes the situation even worse as files are used both on the host and VM. So users need to configure settings in either one depending on what they are trying to do.

[vrothberg]

Good point. Do you have a proposal for rewording? The text here refers to pulling container images.

Pulling a machine image would read registries.conf on the host. But we need to be careful to not overload the user with information and implementation details. Yet it's a fair point to make that differentiation.

Maybe dedicated section for Podman?

[Luap99]

Yeah that is the hard problem really. What is to much or to little, I don't know.
However I would assume in some customer envs where public pulls are not allowed they would like some local mirror of the machine image. And if a admin then goes to this docs that says it is read on the server side only that is confusing. Also looking at this again I think we are missing the import point to define what server-side means in such context. Of course we both know that but users might not. Which server? A normal user is on mac/windows and starts a VM. They may not consider the VM part to be the server as our docs really like to hide the fact that they are using a remote client.

Maybe the best wording would be to say the registries.conf file read on the system where the image is being pulled. When using Podman Machine/the podman remote client that means the image is pulled in the VM/server. As such the config file must be placed on the VM side... then continue your text how to do so.

As special case podman machine init pulls down the VM image also from a registry by default. In this case it will read the registries.conf on the host.

---

And I guess the new artifact work could make this even more confusing if we were to ever add "native" artifacts support on mac/windows on not vie the remote API.

[vrothberg]

All good points. It's clear we need to be more nuanced than the current proposal. I will wait for @mtrmac's feedback and will give it another try then.

[mtrmac]

Maybe the best wording would be to say the registries.conf file read on the system where the image is being pulled.

That… amounts to “a config file on a computer affects that computer”, and … said that way, that feels like an obvious thing and saying that helps no-one — even users of podman machine would not realize that applies to them in some particular way. That’s one way to express the conflicts involved, and how I struggle with this PR.

[Luap99]

@mtrmac: What are your thoughts on allowing c/image to recurse into sub-directories for drop-in folders? Thinking about a feature for Podman Desktop to allow for adding mirrors, it sounds tempting to have a /etc/containers/registries.conf.d/podman-desktop/.... The files could certainly also be namespaced in the same directory but it feels more straightforward to have separate sub-dir.

I must say the fact that the we ended up in a place where every single one for our config files is parsed differently is already highly confusing. containers.conf supports only one level drop downs and does not recurse either. So I think sticking with that seems best to avoid having even more difference between these files types. (Ok I guess one could add the same to containers.conf if really needed)

Of my head I am not aware of any drop in configs that recurse subdirectories so I think this might not be a common thing and naming the single drop in file podman-desktop.conf should achieve the same effect?

[mtrmac]

@mtrmac: What are your thoughts on allowing c/image to recurse into sub-directories for drop-in folders?

I agree with Paul that this would be unexpected.…

Thinking about a feature for Podman Desktop to allow for adding mirrors, it sounds tempting to have a /etc/containers/registries.conf.d/podman-desktop/.... The files could certainly also be namespaced in the same directory

I think structurally the two amount to the same kind of separation — without some kind of permission-based enforcement (which is impossible against root / the owner of the VM), either way it is up to the goodwill / taste of other users / software to avoid interference and unexpected interactions.

[mtrmac]

I think this seems not quite the way to go about this.

• The core of the situation is “a config file affects that computer/VM where it is located”. It is easy to end up actually deciding to write something like that, just to be perfectly correct about the corner cases and interactions. And I, weakly but truly, think that writing that down that way would insult more people than inform — even people actually confused about the machine VM situation.
• If we should document this kind of guidance in the config file man pages, we should do that in all of the relevant ones at once (… but let’s discuss what we want to do, first)
• Purely as a programmer, it is a bit unusual that a low-level dependency like c/image documents instructions for a very high-level tool like podman machine (… Podman Desktop?? Would we want to refer to both, in case GUI users don’t know that podman machine is involved?)
• I don’t think the parts about using podman machine ssh or making sure to write to /etc and not home directories should be in the c/image repo at all. Those are machine design decisions which machine can change in the future — and if we should add something to several man pages, this should not be copy&pasted everywhere. A much shorter pointer to a podman-machine-config-handling man page (maintained in the Podman repo) seems more appropriate.
• I’m generally ill-informed about machine (because I don’t use it daily), but things like proxyenv.ApplyProxies give me pause. So we do copy some settings from the host, not even on machine init, but even on machine start. How are, in general, users supposed to understand these things?! Is there a comprehensive man page in the Podman repo already? I think I’d like to understand the general outline of the story first, before discussing the specific role of config file man pages in it.

[mtrmac]

Paul already said this, but to highlight separately, “server—side” vs. “inside” is confusing here. Within one paragraph, use only one way to refer to a concept.

[mtrmac]

Not “implies”, changing files in the Mac home directory does not do anything inside the VM (or does it?).

What do you want to say?

A configuration that affects podman machine needs to be set in $location, e.g. using $command

?

[mtrmac]

Make sure to not add registries.conf to a non-root user's home directory

• (I’m mildly curious why that should be a problem. Does that interfere with the *.d lookup where some of the *.d files are software-managed, or something like that?)
• If this should be here at all, I think it needs to be much more strongly scoped to that specific situation. As is, I could read this as a general recommendation against home-directory configs, applying to everyone, not just podman machine.

[vrothberg]

I think this seems not quite the way to go about this.

* The core of the situation is “a config file affects that computer/VM where it is located”. It is easy to end up actually deciding to write something like that, just to be _perfectly correct_ about the corner cases and interactions. And I, weakly but truly, think that writing that down _that way_ would _insult_ more people than inform — even people _actually confused_ about the `machine` VM situation.

* If we should document this kind of guidance in the config file man pages, we should do that in all of the relevant ones at once (… but let’s discuss what we want to do, first)

I think we can start with registries.conf. At the moment, there is no guidance for users at all. I don't have the cycles/time to go from 0% (now) to 100% (all relevant man pages) of documenting config handling of Podman Machine. But others are welcome to take over the PR.

* Purely as a programmer, it is a bit unusual that a low-level dependency like c/image documents instructions for a very high-level tool like `podman machine` (… Podman Desktop?? Would we want to refer to _both_, in case GUI users don’t know that `podman machine` is involved?)

All blogs point to (man containers-)registries.conf. I think we need to look at it from the perspective of a user.

* I don’t think the parts about using `podman machine ssh` or making sure to write to `/etc` and not home directories should be in the c/image repo at all. Those are `machine` design decisions which `machine` can change in the future — and if we should add something to several man pages, this should not be copy&pasted everywhere. A much shorter pointer to a `podman-machine-config-handling` man page (maintained in the Podman repo) seems more appropriate.

I think that's really something users should decide. If there is a yet-another man page and the blogs of the past 7 years point here, then we would fail at solving the user issue.

I understand that things are blurry with Podman Machine and that I don't propose a great solution. But a pointer in the docs here would have spared a colleague >2 hours of debugging and slack.

* I’m generally ill-informed about `machine` (because I don’t use it daily), but things like `proxyenv.ApplyProxies` give me pause. So we do copy _some_ settings from the host, not even on `machine init`, but even on `machine start`. How are, in general, users supposed to understand these things?! Is there a comprehensive man page in the Podman repo already? I think I’d like to understand the general outline of the story first, before discussing the specific role of config file man pages in it.

I don't think there is a written down design/process; it's all in the code. As mentioned above, I don't have the time/cycles to solve the general lack of docs on config-handling of Podman Machine but wanted to make sure that the specific problem I helped debug is addressed in the docs.

I leave it up to you (@mtrmac @Luap99) to decide how you want to proceed. I am happy to rewrite the proposed paragraph.

[Luap99]

I agree with @mtrmac a podman machine configuration specific man page maintained in the podman repo seems better suited overall. c/image is used by much more than podman so bothering all non podman machine users with machine details here might lead to a worse experience for them.

[vrothberg]

Let's do this then. Once such a man page exists, the man page here can point to it. Ideally somewhere at the top so users are guided directly. It would still mention Podman (Machine) in c/image but only once.