bug: running through https://docs.kubestellar.io/main/direct/examples/ yields several errors and issues

[clubanderson]

Describe the bug

1. according to instructions at https://docs.kubestellar.io/main/direct/examples/ - I ran init

2. (first error) then, according to instructions, I installed add-ons - command line does not copy and paste correctly on a Mac...

instructions have

kubectl apply -f https://raw.githubusercontent.com/kubestellar/kubestellar/v${KUBESTELLAR_VERSION}/config/postcreate-hooks/kubestellar.yaml
kubectl apply -f https://raw.githubusercontent.com/kubestellar/kubestellar/v${KUBESTELLAR_VERSION}/config/postcreate-hooks/ocm.yaml

when pasting this to a Mac terminal session with .zsh as shell...

kubectl apply -f https://raw.githubusercontent.com/kubestellar/kubestellar/v$\{KUBESTELLAR_VERSION\}/config/postcreate-hooks/kubestellar.yaml
kubectl apply -f https://raw.githubusercontent.com/kubestellar/kubestellar/v$\{KUBESTELLAR_VERSION\}/config/postcreate-hooks/ocm.yaml

note the \ escape character added on copy to the terminal from webpage

3. (2nd error) - When running next step in instructions 'kflex create its1 --type vcluster -p ocm' I get "Error getting client: error building kubeconfig: invalid configuration: [context was not found for specified context: kubeflex, cluster has no server defined]"

I looked at the kflex help and I see an option to 'delete' but I do not see an option to list what control planes exist so that I can delete one.

4. (3rd issue) - why isn't the list of instructions for kind listed under the link for "KubeStellar on Kind"?
5. (4th issue) - why isn't the list of "KubeStellar on..." listed as links/next steps in the bottom of the page for "Setting up KubeStellar" - this turns into a dead end for users.
6. (5th issue) - common commands for operations are different on the example page as they are for the k3d page.... Example: kubectl --context its1 api-resources | grep managedclusteraddons || true is on the example page and in the k3d page it is an inline command with a shell prefix: "7. Install OCM status addon First wait until managedclusteraddons resource shows up on its1 using: shell kubectl --context its1 api-resources | grep managedclusteraddons then install status addon". There should be consistency between instruction sets.

Steps To Reproduce

see above

Expected Behavior

I would like to get KubeStellar installed on a kind cluster.

Additional Context

No response

[MikeSpreitzer]

@clubanderson: FYI, kubestellar/kubeflex#159

[MikeSpreitzer]

I just tried cut-and-paste from step 5 of https://docs.kubestellar.io/main/direct/examples/#common-setup, viewed with Firefox 125.0.1, into a Terminal v2.14 window running zsh 5.9 on my MacOS 14.4.1 MacBook. I clicked on the copy icon in the source window. I then pasted into my Terminal window and hit return. It worked, no spurious escaping. I then demonstrated which shell I am using. It looks as shown below.

[MikeSpreitzer]

@clubanderson: I am not sure what you are saying you did after the first error. Did you simply proceed without any recovery? I tried running through the setup instructions skipping step 5 (to simulate your first problem), and step 6 succeeded. OTOH, I also started from scratch and skipped directly to step 6 (omitting creation of the kubeflex hosting cluster), and that produced the error message that you showed above. But I do not see how a user forllowing the instructions would do that.

[MikeSpreitzer]

@clubanderson, regarding your 4th issue: can you please elaborate on what you mean by 'the page for "Setting up KubeStellar" '? I am having trouble finding such a page. I can find a non-leaf node of that name in the navigation tree, and its children seem to be what you are asking for (see the screen snip below). So I am a bit confused.

[MikeSpreitzer]

@clubanderson, regarding your 3rd, 5th, and maybe 4th issue: there is some incomplete editing of the website in progress. In fact, I think we do not even have a consensus on what the result should look like. The last change anticipated distinct setup and distinct cleanup instructions for each kind of hosting environment, but some of us think that this would be bad because it obscures the underlying unity and does not make it clear how the user adapts to yet another hosting environment.

[MikeSpreitzer]

@clubanderson: I suspect that #2074 may have contributed to the difficulty here, by making problems cascade in a non-obvious manner.

[clubanderson]

@clubanderson, regarding your 4th issue: can you please elaborate on what you mean by 'the page for "Setting up KubeStellar" '? I am having trouble finding such a page. I can find a non-leaf node of that name in the navigation tree, and its children seem to be what you are asking for (see the screen snip below). So I am a bit confused.

"setting up kubestellar" is what people click on. No content is shown, just a tree of pages appears. Then it is not clear which link to click first, so people start with the top link - which has no instructions in it - just some discussion about what to do if using a hosted cluster. I am suggesting that either the "setting up kubestellar" have some content and then have links to the separate examples, or create a page that is at the top of the tree under "setting up kubestellar" that has some content about install and links to the sub examples. There is no umbrella guidance for install in the tree now. I am suggesting there should be one.

[clubanderson]

all I am pointing out here is that a) the instructions should be consistent for things like checking or applying, etc., and b) there should be a top-level intro to install that links to the other pages, not just relying on the tree itself. I also think there is an issue with copy (from safari) and paste (to zsh) on Mac for parameters in the docs.

[MikeSpreitzer]

"setting up kubestellar" is what people click on. No content is shown, just a tree of pages appears.

With a wide window, Firefox 125.0.2 on MacOS: clicking on the "Setting up KubeStellar" vertex in the navigation pane on the left side of the web page exposes or hides the list of its child vertices --- in the navigation pane. Such clicks make no change in what is displayed in the main content part of the web page.

As far as I can tell, this is ordinary behavior for the navigation pane. I see it for the "Contact us" and "Partners" vertices (under "Community") as well.