Merge pull request #95925 from deads2k/doc-events

Event: Document TTL and best-effort-ness

api/openapi-spec/swagger.json

@@ -6574,7 +6574,7 @@
       "type": "object"
     },
     "io.k8s.api.core.v1.Event": {
-      "description": "Event is a report of an event somewhere in the cluster.",
+      "description": "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.",
       "properties": {
         "action": {
           "description": "What action was taken/failed regarding to the Regarding object.",
@@ -11028,7 +11028,7 @@
       ]
     },
     "io.k8s.api.events.v1.Event": {
-      "description": "Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system.",
+      "description": "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.",
       "properties": {
         "action": {
           "description": "action is what action was taken/failed regarding to the regarding object. It is machine-readable. This field cannot be empty for new Events and it can have at most 128 characters.",
@@ -11167,7 +11167,7 @@
       "type": "object"
     },
     "io.k8s.api.events.v1beta1.Event": {
-      "description": "Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system.",
+      "description": "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.",
       "properties": {
         "action": {
           "description": "action is what action was taken/failed regarding to the regarding object. It is machine-readable. This field can have at most 128 characters.",

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

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.",