krancour
commented
1 month ago We talked about this a little previously. There might be more we can do here, but I also want us to proceed cautiously. With Docker Desktop and OrbStack both supporting just a single built-in Kubernetes cluster, there are certain possibilities to account for, as you alluded to with mention of existing disclaimers and the possible need for more.
Toward the beginning, there is the possibility that the cluster exists already and is, for some reason, not compatible with running the Kargo Quickstart. (One possibility, for instance, is a previous installation of Kargo or one of its prerequisites.) This means orb start k8s or the DD equivalent may not be sufficient. Nor can we just tell readers to delete and re-create because they may care about the existing state of that cluster.
This makes the current approach of linking to relevant documentation and leaving the user to figure it out on their own feel, in a way, safest.
Do keep in mind that we're probably not going to encounter many readers who don't already have a way of provisioning a local Kubernetes cluster. Someone who isn't already a Kubernetes user won't be reading these docs. So the reader isn't likely to be looking at those tabs and thinking, "Oh. I better install/learn how to use one of these options." It's more likely they're going to already have a preferred way of spinning up a local cluster and they're going to pick the tab that matches that preference.
So... totally open to exploring possibilities for improvement here, but let's classify this as low priority / post-GA.
Current State
The documentation currently describes methods for starting a local Kubernetes cluster (Docker Desktop, OrbStack, kind, and k3d). However, it does not clarify that
kindandk3dautomatically create a cluster namedkargo-quickstart, while Docker Desktop and OrbStack do not create a cluster by default (which is quite obvious for experienced folks but this little inconsistency may lead to confusion for users who expect similar functionality across all methods imo)Proposed Change
Add commands for Starting existing clusters under Docker Desktop and OrbStack:
docker start <cluster_name>(if applicable)orb start k8sInclude a note indicating that Docker Desktop and OrbStack may require manual management of existing clusters?
Note
OrbStack already includes a cleanup method in the documentation. whereas, docker-desktop clears resources related to quickstart guide.
I feel this is sufficient But we might need some additional information to be more detailed about stopping/deleting it. Perhaps by adding a disclaimer.