kubebuilder
kubebuilder copied to clipboard
kubernetes-sigs
[Docs] Document how to record events
What do you want to happen?
Following up on: https://github.com/kubernetes-sigs/kubebuilder/issues/2684#issuecomment-1227503698
As discussed in the meeting, we think it might be a good idea to add a section about event recording to the documentation, similar to what we had in v1.
Extra Labels
No response
Also, it's probably better to recommend using the controller-runtime recorder over the raw client recorder: https://github.com/kubernetes-sigs/controller-runtime/blob/master/pkg/recorder/recorder.go
@AlmogBaku: The label(s) /label triage/accepted cannot be applied. These labels are supported: api-review, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash, team/katacoda, refactor
In response to this:
/label triage/accepted
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.
Following is some relevant info which would be important we cover in the doc:
(IMO) we could add a warning with:
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: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#events Note that 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.
Also, we can share how to implement the solution to raise an event:
- 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
- b) You need to add the makers to add the RBAC permissions to allow your Operator/controller to raise the event see: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v4-with-deploy-image/controllers/memcached_controller.go#L66 and run make manifests
- 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
Then, we can also create a note to let users know that the new deploy-image plugin raises events and can be used as an example:
What is the purpose of this plugin? The deploy Image plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the complexities of achieving this goal while allowing users to customize the generated code. (More info). Demo: https://www.youtube.com/watch?v=UwPuRjjnMjY
Note that we have a doc in the old book version. So, we might use this content as a base and just ensure that we have the info properly updated: https://book-v1.book.kubebuilder.io/beyond_basics/creating_events.html
By last, I think we could add it under the Reference section.
Hi @mjlshen,
Are you working on this one? If you need help please feel free to ping your questions into the kubebuilder slack channel.
Hi @camilamacedo86! Sorry, yes I started - then got sidetracked - will pick this up again
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs.
This bot triages PRs according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the PR is closed
You can:
- Mark this PR as fresh with
/remove-lifecycle stale - Close this PR with
/close - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale
take a look at how I do at Raptor.ml
In general, you should inject the event recorder to the Reconciler when initializing it, then record events
hello @almogBaku, in v1 docs it is given perfectly. I dont have depth so I dont know which things need to be updated. morever I have questions regarding to place a record event file. i think I should just open a pr with v1 doc record event file and after your reviews and suggestion we can make it ready for current version?
hello @AlmogBaku, in v1 docs it is given perfectly. I dont have depth so I dont know which things need to be updated. morever I have questions regarding to place a record event file. i think I should just open a pr with v1 doc record event file and after your reviews and suggestion we can make it ready for current version?
/cc @camilamacedo86
Yes, we can start by adding the content from v1 Then, as part of this task you should follow up the instructions to ensure that is right and/or update what is required. Also, we should let the users know and point they out that deploy image plugin scaffold will use it and can be checked as an example, see: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v4-with-deploy-image/cmd/main.go#L95
Hello @ashutosh887 are you still working on this. If yes, please link the pr.
Following is some relevant info which would be important we cover in the doc:
(IMO) we could add a warning with:
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: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#events Note that 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.
Also, we can share how to implement the solution to raise an event:
- 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
- b) You need to add the makers to add the RBAC permissions to allow your Operator/controller to raise the event see: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v4-with-deploy-image/controllers/memcached_controller.go#L66 and run make manifests
- 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
Then, we can also create a note to let users know that the new deploy-image plugin raises events and can be used as an example:
What is the purpose of this plugin? The deploy Image plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the complexities of achieving this goal while allowing users to customize the generated code. (More info). Demo: https://www.youtube.com/watch?v=UwPuRjjnMjY
Note that we have a doc in the old book version. So, we might use this content as a base and just ensure that we have the info properly updated: https://book-v1.book.kubebuilder.io/beyond_basics/creating_events.html
By last, I think we could add it under the Reference section.
The video you suggested is of v1. do you think we should add that?
It is done : https://book.kubebuilder.io/reference/raising-events
Closing this one.