docs: workspace initializers and initializingworkspaces virtual works…

…pace

Signed-off-by: Karol Szwaj <[email protected]>

On-behalf-of: @SAP [email protected]

docs/content/concepts/workspaces/.pages

@@ -2,3 +2,4 @@ nav:
     - index.md
     - workspace-types.md
     - virtual-workspaces.md
+    - workspace-initialization.md

docs/content/concepts/workspaces/workspace-initialization.md

@@ -0,0 +1,70 @@
+# Workspace Initialization
+
+Workspace initialization in KCP involves setting up initial configurations and resources for a workspace when it is created. This process is managed through initializers, which are configured via `WorkspaceTypes`. This document covers how to configure initializers, the necessary RBAC permissions, URL schemes, and the reasons for using initializers.
+
+## Initializers
+
+Initializers are used to customize workspaces on creation. They can bootstrap resources inside the workspace or set up permissions in its parent. Initializers are defined in `WorkspaceType` resources. That way user can define a controller that will process workspace and then remove the initializer from workspace, marking it as Ready.
+
+### Defining Initializers in WorkspaceTypes
+
+A `WorkspaceType` can specify an initializer using the `initializer` field. Here is an example of a `WorkspaceType` with an initializer:
+
+```yaml
+apiVersion: tenancy.kcp.io/v1alpha1
+kind: WorkspaceType
+metadata:
+  name: example
+spec:
+  initializer: true
+  extend:
+    with:
+      - name: universal
+        path: root
+  defaultChildWorkspaceType:
+    name: universal
+    path: root
+```
+
+### Enforcing Permissions for Initializers
+
+The non-root user must have the initialize verb on the WorkspaceType that the initializer is for. This ensures that only authorized users can perform initialization actions. Here is an example of the necessary RBAC permissions:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: initialize-universal-workspacetype
+rules:
+  - apiGroups: ["tenancy.kcp.io"]
+    resources: ["workspacetypes"]
+    resourceNames: ["universal"]
+    verbs: ["initialize"]
+```
+You can then bind this role to a user or group:
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: initialize-universal-workspacetype-binding
+subjects:
+  - kind: User
+    name: user1
+    apiGroup: rbac.authorization.k8s.io
+roleRef:
+  kind: ClusterRole
+  name: initialize-universal-workspacetype
+  apiGroup: rbac.authorization.k8s.io
+```
+
+### initializingworkspaces Virtual Workspace
+
+As a service provider, you can use initializingworkspaces virtual workspace to manage workspaces in the initializing phase.
+
+### Endpoint URL path
+
+`initializingworkspaces` Virtual Workspace provide a virtual api-server to access workspaces that are initializing with the specific initializer. These URLs are published in the status of WorkspaceType object. Here is an example URL path for accessing a `initializingworkspaces` virtual workspace:
+
+```yaml
+/services/initializingworkspaces/<initializer>/clusters/<logical-cluster>
+```