Documentation clarity on object names and purpose

[mjudeikis]

And after trying to use KCP I got a feeling of terminology overload and how to access certain objects (like SyncTargets is kubectl get synctargets and workspaces has its own kubectl extension 🤯 ). So not only confusing how to interact with diffent objects but why they are named in one or another way.

I dont think there is need to change any of them but some clarity would be good on terminology and background:

• Workspaces and workspace types: Does the 1 workspace maps to 1 cluster (I think no, but would be good to be explisit)? Which Workspace types should be given to end-users? Is the Workspace something like "Fake/Virtual cluster" or is it someting else? Why do I need workspaces in the first place?

• How does VirtualWorkspace plays into all this?

• SyncTarget (In the docs still WorkspaceCluster) - How does these relate to physcial clusters and where is the boundary. Is the good practice to create all the SyncTargets into root workspace or some other workspaces?

• APIBindings - its not clear yet how users should use those from the docs.

• Workspace CLI - I like the idea of workspace cli being cd, ~ behaviour. But it feel very much out of context in kubectl pattern. Especially if I can't do ls rm, etc. It looks bit half baked. Is there reason for differnet behaviour outside standart pattern get, list, delete, etc in this context?

Overall I understand community is trying to avoid term overload (Cluster, VirtualCluster, EphemeralCluster, FakeCluster) and new terminolgy is potentially is being used (SyncTargets, Workloads, Workspaces, VirtualWorkspaces).

Would be nice to have some kind of pseudo mappping for terminology to hel users to mentaly translate terminoogy they know to KCP terminology, and maybe some good practices how it should be structured.

I think I will have more once I dig deeper into

[stevekuznetsov]

@mjudeikis these are awesome questions - I love the specificity and how clearly you've laid them out. We're likely to respond in this thread but while we work on our documentation story we will also make sure that all of these concepts are covered there, and if you're up to it, we might tag you for review on those to make sure the docs make sense!

[ncdc]

Workspaces and workspace types: Does the 1 workspace maps to 1 cluster (I think no, but would be good to be explisit)? Which Workspace types should be given to end-users? Is the Workspace something like "Fake/Virtual cluster" or is it someting else? Why do I need workspaces in the first place?

Have you read https://github.com/kcp-dev/kcp/blob/main/docs/workspaces.md and/or https://github.com/kcp-dev/kcp/blob/main/docs/concepts.md (we ideally should dedupe...)? Do those answer any of your questions?

How does VirtualWorkspace plays into all this?

"Virtual workspace" is:

1. An unfortunately-chosen name - we need a different one
2. Never anything an end user necessarily needs to know about
3. Something developers need to know about

We'll work on improving the docs around them (and hopefully finding a better name)

APIBindings - its not clear yet how users should use those from the docs.

WIP docs on APIs in kcp: https://hackmd.io/DJGw8YdQTaiPKz9a66Z6OQ

[mjudeikis]

| Have you read https://github.com/kcp-dev/kcp/blob/main/docs/workspaces.md and/or https://github.com/kcp-dev/kcp/blob/main/docs/concepts.md (we ideally should dedupe...)? Do those answer any of your questions?

I did read it but I found it very much specific to KCP and some analogies would be great. Like you can understand expected hiararchy of the workspaces from this document, but how does workspace maps into physical/wirtual clusters - its not clear. Like if I Create SyncTarget inside Org workspace, is it automatically becomes available to child workspaces? And other way around? How does the workspace hierarcy works with Physical cluster hierarchy (if one exists in the first place)
How does User workspaces relates to Org workpaces, etc. It is briefly covered, but some example would be good.

And ontop ClusterWorkspace and SyncTarget - how do they relate? And why where is ClusterWorkspace with types and Workspace with types? It just hard to get your head around :)

[mjudeikis]

Bonus things to consider adding:

• As a service provider I need not only to interact with Virtual Workspace but store some object (Config map with some state). How does one interact with 2 workspaces at the same time. Maybe example. Controller-runtime example has nice helper how to get APIExport and configure rest config to VirtualWorkspace. This could be similar helper.