Inconsistent terminology for microk8s cloud

[sed-i]

I was trying to add-cloud a microk8s cloud, which led me through the following path:

• cloud doc: sounds like there are two kinds of substrates: a machine cloud and a k8s cloud. The cli commands are also contrasted there: add-cloud + add-credentials vs. add-k8s.
• The intro paragraph in the same cloud doc doesn't mention k8s clouds however. Need to read through the doc to realize it's possible to "add-cloud" (add-k8s, actually) a k8s cloud.
• In the MicroK8s doc, the terms "k8s cloud" and "microk8s cloud" are used interchangeably.
• MicroK8s is the one listed under "supported clouds", but there is no distinction between "machine clouds" and "k8s clouds", leading to believe that add-cloud can be used for microk8s.
• The add-k8s doc doesn't mention the "microk8s cloud".

[tmihoc]

Thanks for your comments! Some line-by-line replies below. Overall, I think the information is all there but I agree that its discovery could be better. I've made some updates. More to come. Thanks again!

• cloud doc: sounds like there are two kinds of substrates: a machine cloud and a k8s cloud. The cli commands are also contrasted there: add-cloud + add-credentials vs. add-k8s.

That doc could indeed be clearer. And it shouldn't reference the commands -- that's something a user should (and can, in fact) get from our how-to guides (e.g., https://juju.is/docs/juju/manage-clouds#heading--add-a-cloud clearly distinguishes between the two cases).

• The intro paragraph in the same cloud doc doesn't mention k8s clouds however. Need to read through the doc to realize it's possible to "add-cloud" (add-k8s, actually) a k8s cloud.

From what I can see, it does. However, the way it does may be confusing as it lists in the same breath public clouds, Kubernetes, and private clouds, but that's not necessarily the right classification (because you can have Kubernetes on public clouds -- it's orthogonal to that).

• In the MicroK8s doc, the terms "k8s cloud" and "microk8s cloud" are used interchangeably.

I do not see that in the current version of the doc...

• MicroK8s is the one listed under "supported clouds", but there is no distinction between "machine clouds" and "k8s clouds", leading to believe that add-cloud can be used for microk8s.

That doc left it implicit which cloud was which (essentially, all the Kubernetes clouds have Kubernetes in their name in some fashion -- EKS, AKS, GKE, MicroK8s). I've updated it now to say that explicitly: https://juju.is/docs/juju/juju-supported-clouds

The fact that add-cloud is only for machine clouds comes out of https://juju.is/docs/juju/manage-clouds#heading--add-a-cloud . Although, what you're saying now makes me realize that the help for that command doesn't in fact make that clear -- I'll make a note to update it, thanks!

• The add-k8s doc doesn't mention the "microk8s cloud".

Because it is true for any of the supported clouds that are Kubernets clouds, and MicroK8s is one of them. The fact that Juju automatically defines a cloud with the name microk8s comes out of the MicroK8s specific reference doc: https://juju.is/docs/juju/microk8s