Merge pull request #95925 from deads2k/doc-events

Event: Document TTL and best-effort-ness

staging/src/k8s.io/api/core/v1/generated.proto

@@ -1403,7 +1403,12 @@ message EphemeralVolumeSource {
   optional bool readOnly = 2;
 }
 
-// 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.
 message Event {
   // Standard object's metadata.
   // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

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.

staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go

@@ -637,7 +637,7 @@ func (EphemeralVolumeSource) SwaggerDoc() map[string]string {
 }
 
 var map_Event = map[string]string{
-	"":                   "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.",
 	"metadata":           "Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata",
 	"involvedObject":     "The object that this event is about.",
 	"reason":             "This should be a short, machine understandable string that gives the reason for the transition into the object's current status.",

staging/src/k8s.io/api/events/v1/generated.proto

@@ -30,6 +30,11 @@ import "k8s.io/apimachinery/pkg/runtime/schema/generated.proto";
 option go_package = "v1";
 
 // 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.
 message Event {
   optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
 

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"`
 

staging/src/k8s.io/api/events/v1/types_swagger_doc_generated.go

@@ -28,7 +28,7 @@ package v1
 
 // AUTO-GENERATED FUNCTIONS START HERE. DO NOT EDIT.
 var map_Event = map[string]string{
-	"":                         "Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system.",
+	"":                         "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.",
 	"eventTime":                "eventTime is the time when this Event was first observed. It is required.",
 	"series":                   "series is data about the Event series this event represents or nil if it's a singleton Event.",
 	"reportingController":      "reportingController is the name of the controller that emitted this Event, e.g. `kubernetes.io/kubelet`. This field cannot be empty for new Events.",

staging/src/k8s.io/api/events/v1beta1/generated.proto

@@ -30,6 +30,11 @@ import "k8s.io/apimachinery/pkg/runtime/schema/generated.proto";
 option go_package = "v1beta1";
 
 // 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.
 message Event {
   optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
 

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"`
 

staging/src/k8s.io/api/events/v1beta1/types_swagger_doc_generated.go

@@ -28,7 +28,7 @@ package v1beta1
 
 // AUTO-GENERATED FUNCTIONS START HERE. DO NOT EDIT.
 var map_Event = map[string]string{
-	"":                         "Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system.",
+	"":                         "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.",
 	"eventTime":                "eventTime is the time when this Event was first observed. It is required.",
 	"series":                   "series is data about the Event series this event represents or nil if it's a singleton Event.",
 	"reportingController":      "reportingController is the name of the controller that emitted this Event, e.g. `kubernetes.io/kubelet`. This field cannot be empty for new Events.",