How they extends kube's REST API

Today I got a chance to look at the annotations api.

Every object in kubernetes' REST Api is gauranteed to support a variety of boring fields (name , uuid, etc etc...).

Annotations: variable data that can be latched on to arbitrary API objects.

However, there is a special field, the Annotations, which can be used to encode a map of any kind of data.  The purpose of annotations is to allow users to store arbitrary data along side API objects, for temporary or "alpha" features which haven't been approved in the API yet.

Concretely: How they are used.

Annotations came up in a recent PR, from mike danese, which was a little confusing to me at first.  It turns out, annotations can be added to anything in the kube api, since everything in the kube api has an ObjectMeta associated with it.

In this PR, the goal was to allow for leader election by allowing for several clients to request a lock.   In this case LeaderElectionRecordAnnotationKey is just a string.  

ObjectMeta: api.ObjectMeta{
  Name: le.EndpointsMeta.Name,
  Namespace: le.EndpointsMeta.Namespace,
  Annotations: map[string]string{
    LeaderElectionRecordAnnotationKey: string(leaderElectionRecordBytes),
   },
}


Thats it.  From here, when you pull this data down, the variable information in the annotations can be decoded/encoded in your client, rather than updating the kube API registry itself.

This is a generic mechanism that, I guess, you can use to add flexibility to any REST API, but its nice to know its available in kube as well :).

Why endpoints?

If any REST API object can be used to encode arbitrary data, why bother using the Endpoints object for this request?  It really isn't necessarily a requirement.  Probably there should be an object which is explicitly constructed for use with experimental features.