docs: how to manage remote systems

[IronCore864]

A new how-to guide on managing remote systems (use Pebble in containers).

As previously discussed, the current "Pebble in containers" reference doc is removed.

Preview: https://canonical-pebble--547.com.readthedocs.build/en/547/how-to/manage-a-remote-system/

[dwilding]

Thanks @IronCore864, I like the new how-to doc! I've added some suggestions about specific parts.

There's one general question I have - this is more a question about my understanding of Pebble, rather than the doc itself. When we say "remote system/server" we're still talking about the same physical machine, right? So Pebble could be used to manage a container from the host system, but Pebble couldn't be used if data needs to go over the network. (My understanding is, the only feature of Pebble that works over the network is the open-access API endpoints to allow Juju to check health). Do I have the right understanding?

Perhaps we should state somewhere in the doc what "remote" means in the context of Pebble. What do you think?

[IronCore864]

Thanks @IronCore864, I like the new how-to doc! I've added some suggestions about specific parts.

There's one general question I have - this is more a question about my understanding of Pebble, rather than the doc itself. When we say "remote system/server" we're still talking about the same physical machine, right? So Pebble could be used to manage a container from the host system, but Pebble couldn't be used if data needs to go over the network. (My understanding is, the only feature of Pebble that works over the network is the open-access API endpoints to allow Juju to check health). Do I have the right understanding?

Perhaps we should state somewhere in the doc what "remote" means in the context of Pebble. What do you think?

"Remote system" - Your understanding is correct because only very few APIs work over HTTP at the moment, most APIs only work with the UNIX socket, which is for inter-process communication within the same host where data sent through the socket is handled within the kernel.

Even in the context of charms, the charm code is in the same pod as Pebble, so it's not exactly "remote" in the sense that the client and Pebble are in two different machines.

However, if we look at this from the perspective of a Pod, the client (charms) and Pebble (built in the workload image) are in separate containers (of the same Pod), so it's kind of "remote" as long as the client can access the UNIX socket.

The current situation might change soon, especially since we are adding another type of identity for the metrics endpoint, so maybe there will be more identity types, allowing exposing all APIs over HTTP and making it truly remote.

I'm not sure how to address this in the doc, because if we add a note like "remote means the same host, or the same Pod", although accurate, it doesn't look nice...

[dwilding]

I realized that I didn't reply to your latest comment. Thanks for adding your detailed thoughts about what "remote system" means

Looking again at the doc, I think that mentioning "remote servers" is perhaps risking confusion. This seems to be the only place in the docs that we talk about servers in this way, and it gets me thinking about managing a web server using Pebble as a direct replacement for some other tool (which it sounds like Pebble isn't)

So I think might be best to limit the discussion to "remote systems" only

[IronCore864]

Changes after discussion:

• Updated the title (remote systems -> a remote system, including all occurrences in the content).
• Added a note on "remote system".
• Shortened the introduction.
• Updated the tone to be less blog-y.

[dwilding]

I've finished reviewing, thanks for the updates!

Do you think we ought to mention the PEBBLE_SOCKET environment variable somewhere, so that the reader knows how to override the default socket path when using the pebble command?

[benhoyt]

This is a lot better, thanks! I think this is very close now, just a few minor comments.

[benhoyt]

Thanks!