> For the complete documentation index, see [llms.txt](https://renhongcai.gitbook.io/kubernetes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://renhongcai.gitbook.io/kubernetes/di-shi-liu-zhang-api-she-ji-yue-ding/1.3-api_convention_event.md).

# 16.3 event设计约定

## 导读

当设计API扩展及实现其控制器时，如何设计`events`和`status`？什么样的信息需要放到`status`中，什么样的信息需要放到`events`中？

## Event设计约定

`event`的设计初衷是为`status`提供一个补充，与`status`不同的是，`event`可以提供历史信息。与`status`类似的是，`event`也由控制器维护。那么什么时候需要报告`event`？需要报告什么信息呢？

当控制器观测到资源的某个状态（正常状态或异常状态）时，如果需要用户或管理员注意，那就需要报告事件。 报告的事件，通常包含3个信息：

* reason：事件名称
* type：事件类型（或事件等级），可以为”Normal“或”Warning“
* message: 事件详细描述信息

事件类型当前只有`Normal`和`Warning`可选，将来如有必要可以扩展出新的类型，比如`Critical`来表示更严重的信息。事件名称使用驼峰风格表示，名字尽量简短，但信息量也要充足，避免使用极简的名称，比如"Failed"，至少也要使用”xxxFailed“，指出到底是什么出错了。