Particularize Initializers and Provide Sample Code

[SimonTheLeg]

Summary

• Irons out some rough edges on the existing documentation
• Provides some details on the hiearchy of Initializers
• Provides sample code how to write a custom Initializer

Before starting with a detailed review of the content: Two open questions from my side

1. For now I have put the code into mkdocs tabs to directly live in the documentation. As the example is rather complex, I am thinking it would be better to place this somewhere into our repo and link from to docs to it. Do you agree? If yes, where would be the best place to put the example?

2. The code works and initializes the workspaces correctly. However it still logs errors like this one. Do you have any ideas what this could be? Since it logs them constantly, I am not feeling quite happy with the code, but I cannot figure out how to fix it. I have tried setting lc.Name = req.Name, but this runs into the same issue

   time=2025-05-27T13:57:07.530+02:00 level=INFO msg=Reconciling clustername=2563gq6olq0jl826 logger=initializer-controller
   time=2025-05-27T13:57:07.530+02:00 level=ERROR msg="Reconciler error" controller=logicalcluster controllerGroup=core.kcp.io controllerKind=LogicalCluster LogicalCluster.name=cluster namespace="" name=cluster reconcileID=1ac925c2-8b83-4115-8f7e-dca1674ec78c err="LogicalCluster.core.kcp.io \"cluster\" not found"
   

What Type of PR Is This?

/kind documentation

Related Issue(s)

Fixes: making kcp docs a better place :)

Release Notes

NONE

[kcp-ci-bot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[kcp-ci-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign scheeles for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[embik]

Regarding (1):

Maybe it makes sense to focus on the code parts that are relevant to building such a controller instead of a fully working example that includes standard stuff like setting up a manager, generating a rest config, etc?

Regarding (2):

I'm not quite sure, but I suspect the following is happening: When you patch the LogicalCluster, you remove the initializer from its status list. That means that the logical cluster becomes "invisible" to you, since you have finished initialization. I guess that PATCH (or the controller-runtime implementation) wants to get back the patched object, but as soon as you patched it, it's gone. So that's why you are now getting a 404. I suppose a 404 error after patching it is expected and should be caught as such.

But @mjudeikis should comment on this too, it's just a hunch at this point.

[embik]

/ok-to-test

[SimonTheLeg]

1. I have split the code into the reconcile part and the glue code. I think it is important to include the glue, so people have a full example, but now it is not as bulky to read anymore :)
2. I have completely rebuild the example to use the multicluster provider. this also gets rid of the nasty 404

[SimonTheLeg]

/label kind/documentation

[kcp-ci-bot]

@SimonTheLeg: The label(s) /label kind/documentation cannot be applied. These labels are supported: blocked by backend, merge-type/merge, merge-type/rebase, needs details, service accounts, Epic, design, feature, proposal, ready-to-challenge, redesign. Is this label configured under labels -> additional_labels or labels -> restricted_labels in plugin.yaml?

In response to this:

/label kind/documentation

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[SimonTheLeg]

/retest
flake

[SimonTheLeg]

/retest
flake

[mjudeikis]

I think we need to start collecting extensive examples somewhere in the repo (monorepo style), so we can point users to working e2e examples. We know we have edgecases and missing machinery for how to run this things in an easy way.

Docs examples are tend to get out of date super fast so +1 to have them incode and link

[mjudeikis]

@embik @SimonTheLeg I would be huge +1 to move examples into code and link it from docs. Else they will be out of date as soon as next rebase.

Otherwise - good to merge if we do this as follow-up

[embik]

We could directly link to https://github.com/kcp-dev/multicluster-provider/tree/main/examples/initializingworkspaces from the kcp docs and extend it with the changes (?) that @SimonTheLeg made in the example code in this PR.

[ntnn]

I think we need to start collecting extensive examples somewhere in the repo (monorepo style), so we can point users to working e2e examples. We know we have edgecases and missing machinery for how to run this things in an easy way.

I dislike having examples in comments or doc files. IMHO they give a false sense of security that it is documented but in reality they never are tested on changes and quickly forgotten.

I started executable examples in the contrib repo: https://github.com/kcp-dev/contrib/tree/main/examples
The examples are just a readme.md to read on the built website and is executed in this github workflow at least every night:
https://github.com/kcp-dev/contrib/blob/bf167ae01a8987e5a145e8c4742e0210a3a22c0b/.github/workflows/examples.yaml#L57-L61

If a build fails off of main the pipeline failure is reported.

That can also work for Go code for e.g. controllers. In contrib it won't be build as part of the test suites but at least it will run at least every night and we will get notified if the examples break.

Alternatively we could copy that workflow to this repository and then make parts of the documentation testable, e.g. for this case the code could be written to a file:

\```go file=my_test_controller.go
// the controller code
\```

<!--
# ... setup
go run ./my_test_controller.go
-->

And to reiterate - I like more examples but the examples should be tested and regularly run. If we just plug that into docs somewhere it will be outdated.

[cnvergence]

Suggested change

	### Responsibilities Of Custom Intitialization Controllers
	### Responsibilities Of Custom Initialization Controllers

[cnvergence]

Suggested change

	Keeping this in mind, you can use the following example as a starting point for your intitialization controller
	Keeping this in mind, you can use the following example as a starting point for your initialization controller

[cnvergence]

Suggested change

	// since the initializers name is is the last part of the hostname, we can take it from there
	// since the initializers name is the last part of the hostname, we can take it from there

[cnvergence]

Overall LGTM, thanks for extending this doc
+1 for keeping example in a file