Merge pull request kubernetes#95925 from deads2k/doc-events

Event: Document TTL and best-effort-ness
obeyda · Oct 30, 2020 · a71334b · a71334b
2 parents e91cb0b + 5edd376
commit a71334b
Show file tree

Hide file tree

Showing 11 changed files with 44 additions and 9 deletions.
diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json
diff --git a/pkg/apis/core/types.go b/pkg/apis/core/types.go
@@ -4602,7 +4602,12 @@ const (
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// Event is a report of an event somewhere in the cluster.
+// Event is a report of an event somewhere in the cluster.  Events
+// have a limited retention time and triggers and messages may evolve
+// with time.  Event consumers should not rely on the timing of an event
+// with a given Reason reflecting a consistent underlying trigger, or the
+// continued existence of events with that Reason.  Events should be
+// treated as informative, best-effort, supplemental data.
 // TODO: Decide whether to store these separately or with the object they apply to.
 type Event struct {
 	metav1.TypeMeta

diff --git a/staging/src/k8s.io/api/core/v1/generated.proto b/staging/src/k8s.io/api/core/v1/generated.proto
diff --git a/staging/src/k8s.io/api/core/v1/types.go b/staging/src/k8s.io/api/core/v1/types.go
@@ -5365,7 +5365,12 @@ const (
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// Event is a report of an event somewhere in the cluster.
+// Event is a report of an event somewhere in the cluster.  Events
+// have a limited retention time and triggers and messages may evolve
+// with time.  Event consumers should not rely on the timing of an event
+// with a given Reason reflecting a consistent underlying trigger, or the
+// continued existence of events with that Reason.  Events should be
+// treated as informative, best-effort, supplemental data.
 type Event struct {
 	metav1.TypeMeta `json:",inline"`
 	// Standard object's metadata.

diff --git a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go
diff --git a/staging/src/k8s.io/api/events/v1/generated.proto b/staging/src/k8s.io/api/events/v1/generated.proto
diff --git a/staging/src/k8s.io/api/events/v1/types.go b/staging/src/k8s.io/api/events/v1/types.go
@@ -25,6 +25,11 @@ import (
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
 // Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system.
+// Events have a limited retention time and triggers and messages may evolve
+// with time.  Event consumers should not rely on the timing of an event
+// with a given Reason reflecting a consistent underlying trigger, or the
+// continued existence of events with that Reason.  Events should be
+// treated as informative, best-effort, supplemental data.
 type Event struct {
 	metav1.TypeMeta `json:",inline"`
 

diff --git a/staging/src/k8s.io/api/events/v1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/events/v1/types_swagger_doc_generated.go
diff --git a/staging/src/k8s.io/api/events/v1beta1/generated.proto b/staging/src/k8s.io/api/events/v1beta1/generated.proto
diff --git a/staging/src/k8s.io/api/events/v1beta1/types.go b/staging/src/k8s.io/api/events/v1beta1/types.go
@@ -27,6 +27,11 @@ import (
 // +k8s:prerelease-lifecycle-gen:deprecated=1.22
 
 // Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system.
+// Events have a limited retention time and triggers and messages may evolve
+// with time.  Event consumers should not rely on the timing of an event
+// with a given Reason reflecting a consistent underlying trigger, or the
+// continued existence of events with that Reason.  Events should be
+// treated as informative, best-effort, supplemental data.
 type Event struct {
 	metav1.TypeMeta `json:",inline"`
 

diff --git a/staging/src/k8s.io/api/events/v1beta1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/events/v1beta1/types_swagger_doc_generated.go