docs: 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

[kcp-ci-bot]

@SimonTheLeg: The following test 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	880a48d	link	true	/test pull-kcp-test-e2e-sharded

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.