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

/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

[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]

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

[SimonTheLeg]

this is also ready for review again

[mjudeikis]

/lgtm
/approve

[kcp-ci-bot]

LGTM label has been added.

Git tree hash: 1108795ef0edba396423577292cd031e61dd11f7

[kcp-ci-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: mjudeikis

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [mjudeikis]

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

[kcp-ci-bot]

@SimonTheLeg: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-kcp-test-e2e-sharded	c85829d	link	unknown	/test pull-kcp-test-e2e-sharded
pull-kcp-test-e2e-multiple-runs	c85829d	link	unknown	/test pull-kcp-test-e2e-multiple-runs

Full PR test history

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. I understand the commands that are listed here.