link to the official multicluster-provider example and fix hiearchy documentation

On-behalf-of: SAP <[email protected]>
Signed-off-by: Simon Bein <[email protected]>

Author: SimonTheLeg

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

@@ -24,12 +24,22 @@ spec:
 
 Each initializer has a unique name, which gets automatically generated using  `<workspace-path-of-WorkspaceType>:<WorkspaceType-name>`. So for example, if you were to apply the aforementioned WorkspaceType on the root workspace, your initializer would be called `root:example`.
 
-Since `WorkspaceType.spec.initializer` is a boolean field, each WorkspaceType comes with a single initializer by default. However each WorkspaceType inherits the initializers of its parent workspaces. As a result, it is possible to have multiple initializers on a WorkspaceType, but you will need to nest them.
-Here is a example:
+Since `WorkspaceType.spec.initializers` is a boolean field, each WorkspaceType comes with a single initializer by default. However each WorkspaceType inherits the initializers of its parent WorkspaceType. As a result, it is possible to have multiple initializers on a WorkspaceType using [WorkspaceType Extension](../../concepts/workspaces/workspace-types.md#workspace-type-extensions-and-constraints)
 
-1. In `root` workspace, create a new WorkspaceType called `parent`. You will receive a `root:parent` initializer
-2. In the newly created `parent` workspace, create a new WorkspaceType `child`. You will receive a `root:parent:child` initializer
-3. Whenever a new workspace is created in the child workspace, it will receive both the `root:parent` as well as the `root:parent:child` initializer
+In the following example, `child` inherits the initializers of `parent`. As a result, child workspaces will have the `root:child` and `root:parent` initializers set.
+
+```yaml
+apiVersion: tenancy.kcp.io/v1alpha1
+kind: WorkspaceType
+metadata:
+  name: child
+spec:
+  initializer: true
+  extend:
+    with:
+    - name: parent
+      path: root
+```
 
 ### Enforcing Permissions for Initializers
 
@@ -66,7 +76,7 @@ roleRef:
 
 ## Writing Custom Initialization Controllers
 
-### Responsibilities Of Custom Intitialization Controllers
+### Responsibilities Of Custom Initialization Controllers
 
 Custom Initialization Controllers are responsible for handling initialization logic for custom WorkspaceTypes. They interact with kcp by:
 
@@ -88,163 +98,16 @@ $ kubectl get workspacetype example -o yaml
 ...
 status:
   virtualWorkspaces:
-  - url: https://<front-proxy-url>/services/initializingworkspaces/root:example
+  - url: https://<shard-url>/services/initializingworkspaces/root:example
 ```
 
-You can use this url to construct a kubeconfig for your controller. To do so, use the url directly as the `cluster.server` in your kubeconfig and provide a user with sufficient permissions (see [Enforcing Permissions for Initializers](#enforcing-permissions-for-initializers))
+You can use this url to construct a kubeconfig for your controller. To do so, use the url directly as the `cluster.server` in your kubeconfig and provide the subject with sufficient permissions (see [Enforcing Permissions for Initializers](#enforcing-permissions-for-initializers))
 
 ### Code Sample
 
 When writing a custom initializer, the following needs to be taken into account:
 
-* We strongly recommend to use the kcp [initializingworkspace multicluster-provider](github.com/kcp-dev/multicluster-provider) to build your custom initializer
+* We strongly recommend to use the kcp [initializingworkspace multicluster-provider](https://github.com/kcp-dev/multicluster-provider) to build your custom initializer
 * You need to update LogicalClusters using patches; They cannot be updated using the update api
 
-Keeping this in mind, you can use the following example as a starting point for your intitialization controller
-
-=== "reconcile.go"
-
-    ```Go
-    package main
-
-    import (
-      "context"
-      "slices"
-     
-      "github.com/go-logr/logr"
-      kcpcorev1alpha1 "github.com/kcp-dev/kcp/sdk/apis/core/v1alpha1"
-      "github.com/kcp-dev/kcp/sdk/apis/tenancy/initialization"
-      ctrlclient "sigs.k8s.io/controller-runtime/pkg/client"
-      "sigs.k8s.io/controller-runtime/pkg/cluster"
-      "sigs.k8s.io/controller-runtime/pkg/reconcile"
-      mcbuilder "sigs.k8s.io/multicluster-runtime/pkg/builder"
-      mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager"
-      mcreconcile "sigs.k8s.io/multicluster-runtime/pkg/reconcile"
-     )
-     
-     type Reconciler struct {
-      Log             logr.Logger
-      InitializerName kcpcorev1alpha1.LogicalClusterInitializer
-      ClusterGetter   func(context.Context, string) (cluster.Cluster, error)
-     }
-     
-     func (r *Reconciler) Reconcile(ctx context.Context, req mcreconcile.Request) (reconcile.Result, error) {
-      log := r.Log.WithValues("clustername", req.ClusterName)
-      log.Info("Reconciling")
-     
-      // create a client scoped to the logical cluster the request came from
-      cluster, err := r.ClusterGetter(ctx, req.ClusterName)
-      if err != nil {
-       return reconcile.Result{}, err
-      }
-      client := cluster.GetClient()
-     
-      lc := &kcpcorev1alpha1.LogicalCluster{}
-      if err := client.Get(ctx, req.NamespacedName, lc); err != nil {
-       return reconcile.Result{}, err
-      }
-     
-      // check if your initializer is still set on the logicalcluster
-      if slices.Contains(lc.Status.Initializers, r.InitializerName) {
-     
-       // your logic to initialize a Workspace goes here
-       log.Info("Starting to initialize cluster")
-     
-       // after your initialization is done, don't forget to remove your initializer.
-       // You will need to use patch, to update the LogicalCluster
-       patch := ctrlclient.MergeFrom(lc.DeepCopy())
-       lc.Status.Initializers = initialization.EnsureInitializerAbsent(r.InitializerName, lc.Status.Initializers)
-       if err := client.Status().Patch(ctx, lc, patch); err != nil {
-        return reconcile.Result{}, err
-       }
-      }
-     
-      return reconcile.Result{}, nil
-     }
-     
-     func (r *Reconciler) SetupWithManager(mgr mcmanager.Manager) error {
-      return mcbuilder.ControllerManagedBy(mgr).
-       For(&kcpcorev1alpha1.LogicalCluster{}).
-       Complete(r)
-     }
-    ```
-
-=== "main.go"
-
-    ```Go
-    package main
-
-    import (
-      "context"
-      "fmt"
-      "log/slog"
-      "os"
-      "strings"
-     
-      "github.com/go-logr/logr"
-      kcpcorev1alpha1 "github.com/kcp-dev/kcp/sdk/apis/core/v1alpha1"
-      "github.com/kcp-dev/multicluster-provider/initializingworkspaces"
-      "golang.org/x/sync/errgroup"
-      "k8s.io/client-go/kubernetes/scheme"
-      "k8s.io/client-go/tools/clientcmd"
-      ctrl "sigs.k8s.io/controller-runtime"
-      "sigs.k8s.io/controller-runtime/pkg/manager"
-      mcmanager "sigs.k8s.io/multicluster-runtime/pkg/manager"
-     )
-     
-     // glue and setup code
-     func main() {
-      if err := execute(); err != nil {
-       fmt.Println(err)
-       os.Exit(1)
-      }
-     }
-     func execute() error {
-      // your kubeconfig here
-      kubeconfigpath := "<your-kubeconfig>"
-     
-      config, err := clientcmd.BuildConfigFromFlags("", kubeconfigpath)
-      if err != nil {
-       return err
-      }
-     
-      // since the initializers name is is the last part of the hostname, we can take it from there
-      initializerName := config.Host[strings.LastIndex(config.Host, "/")+1:]
-     
-      provider, err := initializingworkspaces.New(config, initializingworkspaces.Options{InitializerName: initializerName})
-      if err != nil {
-       return err
-      }
-     
-      logger := logr.FromSlogHandler(slog.NewTextHandler(os.Stderr, nil))
-      ctrl.SetLogger(logger)
-     
-      mgr, err := mcmanager.New(config, provider, manager.Options{Logger: logger})
-      if err != nil {
-       return err
-      }
-     
-      // add the logicalcluster scheme
-      if err := kcpcorev1alpha1.AddToScheme(scheme.Scheme); err != nil {
-       return err
-      }
-     
-      r := Reconciler{
-       Log:             mgr.GetLogger().WithName("initializer-controller"),
-       InitializerName: kcpcorev1alpha1.LogicalClusterInitializer(initializerName),
-       ClusterGetter:   mgr.GetCluster,
-      }
-     
-      if err := r.SetupWithManager(mgr); err != nil {
-       return err
-      }
-      mgr.GetLogger().Info("Setup complete")
-     
-      // start the provider and manager
-      g, ctx := errgroup.WithContext(context.Background())
-      g.Go(func() error { return provider.Run(ctx, mgr) })
-      g.Go(func() error { return mgr.Start(ctx) })
-     
-      return g.Wait()
-     }
-    ```
+Keeping this in mind, you can use the [multicluster-provider initializingworkspaces example](https://github.com/kcp-dev/multicluster-provider/tree/main/examples/initializingworkspaces) as a starting point for your initialization controller