📖 Docs for record events.

[Sajiyah-Salat]

Descripton

Add the documentation to help out users know how to implement and raise events.
NOTE: we had this document in v1 docs but it is outdated and we are shaping it accordingly.

Motivation

Fixes #2897

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-24-7

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-26-0

[camilamacedo86]

Thank you for your contribution, but this PR requires changes.

• Ensure that you check your changes using the preview so that you can auto-verify if all is ok
• You need add a new section in the menu for the new doc (it should be under references)
• You also need to ensure that the content follows up the required styled
• By last, instead of trying to link the samples under testdata/, we must add the code snippet related to the specific examples.

I hope the detailed steps described in https://github.com/kubernetes-sigs/kubebuilder/pull/3375/files#r1184594890 can help you out.

[Sajiyah-Salat]

Thank you so much @camilamacedo86 for these detailed explanation. I am lucky to have a mentor like you.

[Sajiyah-Salat]

I know understand how to link page to left menu. All thanks to you. about code snippet, I dont know which code snippet would be used or where to take it. from links one link was working so I just extract it out add it in docs. Let me know which code snippet would you like me to add.

[camilamacedo86]

Suggested change

	a) You need to pass the recorder when you set up the recorder for the controller when the event will be raised see: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v4-with-deploy-image/main.go#L103
	### Allowing usage of EventRecorder on the Controller
	To raise an event, you must have access to `record.EventRecorder` in the Controller. Therefore, firstly let's update the controller implementation:
	```go
	import (
	...
	"k8s.io/client-go/tools/record"
	...
	)
	// MyKindReconciler reconciles a MyKind object
	type MyKindReconciler struct {
	client.Client
	Scheme *runtime.Scheme
	// See that we added the following code to allow us to pass the record.EventRecorder
	Recorder record.EventRecorder
	}

[camilamacedo86]

Lets first change the controller; otherwise, users will check the compiler failing.
We can also do a generic example and put the imports.

[camilamacedo86]

By last, we can describe how to grant the permissions. See that users must run make manifests.

Suggested change

	c) You can check an example of the event being called in: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v4-with-deploy-image/controllers/memcached_controller.go#L299-L303
	### Granting the required permissions
	You must also grant the RBAC rules permissions to allow your project to create Events. Therefore, ensure that you add the [RBAC][rbac-markers] into your controller:
	```go
	...
	//+kubebuilder:rbac:groups=core,resources=events,verbs=create;patch
	...
	func (r *MyKindReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	```
	And then, run `$ make manifests` to update the rules under `config/rbac/rule.yaml`.

[camilamacedo86]

We will need to add at the bottom an alias [rbac-markers] for the page: https://book.kubebuilder.io/reference/markers/rbac.html

It is a kubebuilder doc, so we should NOT use the above URL; instead, we should use a relative path from this place to the file.

[camilamacedo86]

Suggested change

	Building on the example introduced in [Controller Example](../basics/simple_controller.md), we can add Events to our reconcile logic using `recorder` as our `EventRecorder`
	```go
	//Reconcile logic up here...
	// Create the resource
	found := &appsv1.Deployment{}
	err = r.Get(context.TODO(), types.NamespacedName{Name: deploy.Name, Namespace: deploy.Namespace}, found)
	if err != nil && errors.IsNotFound(err) {
	log.Printf("Creating Deployment %s/%s\n", deploy.Namespace, deploy.Name)
	err = r.Create(context.TODO(), deploy)
	if err != nil {
	return reconcile.Result{}, err
	}
	// Write an event to the ContainerSet instance with the namespace and name of the
	// created deployment
	r.recorder.Event(instance, "Normal", "Created", fmt.Sprintf("Created deployment %s/%s", deploy.Namespace, deploy.Name))
	} else if err != nil {
	return reconcile.Result{}, err
	}
	// Preform update
	if !reflect.DeepEqual(deploy.Spec, found.Spec) {
	found.Spec = deploy.Spec
	log.Printf("Updating Deployment %s/%s\n", deploy.Namespace, deploy.Name)
	err = r.Update(context.TODO(), found)
	if err != nil {
	return reconcile.Result{}, err
	}
	// Write an event to the ContainerSet instance with the namespace and name of the
	// updated deployment
	r.recorder.Event(instance, "Normal", "Updated", fmt.Sprintf("Updated deployment %s/%s", deploy.Namespace, deploy.Name))
	}
	return reconcile.Result{}, nil
	}
	```
	Events should be raised in certain circumstances only and following this guideline acctually is not a good practice. See what the Kubernetes APIs convention describes when using them [here][Events]
	<aside class="note">
	It is NOT recommended to emit events for all Operations. If authors raise too many events it brings bad UX experiences for those that are consuming the solutions on the cluster and they will not have attention to what they actually must be notified.
	</aside>

[camilamacedo86]

Suggested change

	- [Creating Events](./reference/creating-events.md)
	- [Raising Events](./reference/creating-events.md)

Can you please add it after [Using Finalizers](https://github.com/kubernetes-sigs/kubebuilder/blob/da10bf1678133baae9085a96aeffdb9a0dbaa12f/docs/book/src/reference/using-finalizers.md) So that it would be in a more appropriated order if you check the current items. It seems fit better.

[camilamacedo86]

@Sajiyah-Salat,

I did a full review of this one. Please, feel free to check all suggestions and comments.

Also, see that I updated the PR description for you to check how we usually do that. We should not add maintainers or issue authors' names.

The purpose of the description is to be very short content that describes what the PR is about and its motivation. So that in the future, if we want to check a specific change, we can come back to check it, and also it helps to let the reviewers know what is done and why.

[camilamacedo86]

@Sajiyah-Salat now see that you would replace the a, b, and c for the steps.
It means here we would have the first step as suggested: #3375 (comment)

And then, you would have the second step which is update the cmd/main.go see: #3375 (comment)

By last you have the step to grant the permissions; #3375 (comment)

[Sajiyah-Salat]

cc : @camilamacedo86
Is there anything else you would like me to change.

[camilamacedo86]

@Sajiyah-Salat

Can you please squash the commits so that we can move forward with this one?
After a fast look it seems fine now. Great work 🥇

[Sajiyah-Salat]

git rebase -i HEAD~10
[detached HEAD 92a7859b] Created "creating events" and modified.
 Date: Wed May 17 20:01:15 2023 +0530
 1 file changed, 35 insertions(+), 2 deletions(-)
Auto-merging test/testdata/generate.sh
CONFLICT (content): Merge conflict in test/testdata/generate.sh
error: could not apply 6ee6e8bb... :seedleing: stop to generate all samples for go/v3
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".

when I run git rebase it gives some conflicting file which have generate something conflicting. We have two option there to choose the current or incoming change or to choose both. What should I choose here?

[k8s-ci-robot]

PR needs rebase.

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.

[k8s-ci-robot]

@Sajiyah-Salat: 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-kubebuilder-test	f0bd010	link	true	/test pull-kubebuilder-test
pull-kubebuilder-e2e-k8s-1-26-0	f0bd010	link	true	/test pull-kubebuilder-e2e-k8s-1-26-0
pull-kubebuilder-e2e-k8s-1-25-3	f0bd010	link	true	/test pull-kubebuilder-e2e-k8s-1-25-3
pull-kubebuilder-e2e-k8s-1-27-1	f0bd010	link	true	/test pull-kubebuilder-e2e-k8s-1-27-1

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

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.

[Sajiyah-Salat]

I ddid messed up the creating-events file and the commits related to it. However we still have the backup file. in another branch. I have started a new pr. Please review here.