📖 Add more examples in documentation

[aerfio]

• Adds an example showing how to use Server Side Apply with controller-runtime client and structs from k8s.io/client-go/applyconfigurations/*
• Adds an example how to watch any resource and map its changes to main reconciled resource

[k8s-ci-robot]

Welcome @aerfio!

It looks like this is your first PR to kubernetes-sigs/controller-runtime 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/controller-runtime has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @aerfio. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[alvaroaleman]

/ok-to-test

[alvaroaleman]

I don't think the fact that this has a watch is the special bit about this example. And I'd rather not have an example that doesn't implement DeepCopy but just panics. Maybe do something like a special configmap key that references something else or such?

Suggested change

	func Example_watches() {
	func ExampleCustomHandler() {

[aerfio]

I don't think the fact that this has a watch is the special bit about this example.

That was my intention, to have an easy to grasp example for "Watches" 😢

Maybe do something like a special configmap key that references something else or such?

I didn't want to complicate this example too much, I thought about switching from LocalObjectReference to e.g ConfigMapKeySelector, but the code inside Watches would a too complicated for an example imho.

And I'd rather not have an example that doesn't implement DeepCopy but just panics.

Sure, I've changed it to json.Marshal + json.Unmarshal with panic on error, is that enough? I could use controller-gen for that, but that would result in new file in the root of the repo + some changes in makefile, which I wanted to omit

Update: I tried it and controller-gen seems to ignore *_test.go files 🤷🏻

And lastly, for example name I changed it now like that:

diff --git a/example_test.go b/example_test.go
index cbbf032b..83f6fcdb 100644
--- a/example_test.go
+++ b/example_test.go
@@ -108,7 +108,7 @@ func (in *ExampleCRDWithConfigMapRefList) DeepCopyObject() runtime.Object {
 // This example creates a simple application Controller that is configured for ExampleCRDWithConfigMapRef CRD.
 // Any change in the configMap referenced in this Custom Resource will cause the re-reconcile of the parent ExampleCRDWithConfigMapRef
 // due to the implementation of the .Watches method of "sigs.k8s.io/controller-runtime/pkg/builder".Builder.
-func Example_watches() {
+func Example_customHandler() {
 	log := ctrl.Log.WithName("builder-examples")
 
 	manager, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{})

to follow other examples in this repo (in this file also, see https://github.com/kubernetes-sigs/controller-runtime/blob/v0.16.2/example_test.go#L77) and also https://go.dev/blog/examples#example-function-names

[alvaroaleman]

Please mention why the dance of converting to unstructured is needed

[aerfio]

@alvaroaleman done

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: aerfio, alvaroaleman

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

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