Document watch event annotation kubernetes.io/initial-events-list-blueprint

[sftim]

This is a Feature Request

What would you like to be added

Ensure that our docs mention kubernetes.io/initial-events-list-blueprint somewhere. This is an annotation that appears on some watch events.

Comments
/sig api-machinery
/language en
/kind feature

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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-sigs/prow repository.

[Ritikaa96]

/assign

[Ritikaa96]

How about this:

kubernetes.io/initial-events-list-blueprint

Type: Annotation
Example: kubernetes.io/initial-events-list-blueprint: "Description of K8s object."
Used on: Events
The annotation is added to the synthetic "Bookmark" event for the watch stream and is used by clients
to guarantee the format consistency when reconstructing the list during WatchList processing. This annotation will store an empty, versioned list encoded as a Base64 string. This annotation will be added to the same object/place the k8s.io/initial-events-end annotation is added.

[Ritikaa96]

Also the other related annotation has not been recorded as well i.e. kubernetes.io/initial-events-end.

[Ritikaa96]

@sftim
reference: KEP-3157
&&
k8s/k8s..types.go

[sftim]

How about this:

kubernetes.io/initial-events-list-blueprint

Type: Annotation Example: kubernetes.io/initial-events-list-blueprint: "Description of K8s object." Used on: Events The annotation is added to the synthetic "Bookmark" event for the watch stream and is used by clients to guarantee the format consistency when reconstructing the list during WatchList processing. This annotation will store an empty, versioned list encoded as a Base64 string. This annotation will be added to the same object/place the k8s.io/initial-events-end annotation is added.

I'm afraid that's wrong; watch events are not the same as Events.

[Ritikaa96]

How about this:

kubernetes.io/initial-events-list-blueprint

Type: Annotation Example: kubernetes.io/initial-events-list-blueprint: "Description of K8s object." Used on: Events the annotation is added to the synthetic "Bookmark" event for the watch stream and is used by clients to guarantee the format consistency when reconstructing the list during WatchList processing. This annotation will store an empty, versioned list encoded as a base64 string. This annotation will be added to the same object/place the k8s.io/initial-events-end annotation is added.

I'm afraid that's wrong; watch events are not the same as Events.

You mean on the used on section? I was contemplating whether to write watch events . Is there any other thing wrong with the description?

[sftim]

(I'm not familiar with this annotation, even though I am able to tell that it isn't documented)

[Ritikaa96]

I got the content from KEP and changelog for the same. there are very few instances of its use in the code or k8s github organization, I'll try to investigate more about it and let you know. What about the second annotation though, i have checked and it's also not recorded.

[sftim]

(I'm also not familiar with the second annotation, even though I am able to tell that it isn't documented)