Groups and Versions and Kinds, oh my!

Actually, before we get started with our API, we should talk terminologya bit.

When we talk about APIs in Kubernetes, we often use 4 terms: groups,versions, kinds, and resources.

Groups and Versions

An API Group in Kubernetes is simply a collection of relatedfunctionality. Each group has one or more versions, which, as the namesuggests, allow us to change how an API works over time.

Kinds and Resources

Each API group-version contains one or more API types, which we callKinds. While a Kind may change forms between versions, each form mustbe able to store all the data of the other forms, somehow (we can storethe data in fields, or in annotations). This means that using an olderAPI version won’t cause newer data to be lost or corrupted. See theKubernetes APIguidelinesfor more information.

You’ll also hear mention of resources on occasion. A resource is simplya use of a Kind in the API. Often, there’s a one-to-one mapping betweenKinds and resources. For instance, the pods resource corresponds to thePod Kind. However, sometimes, the same Kind may be returned by multipleresources. For instance, the Scale Kind is returned by all scalesubresources, like deployments/scale or replicasets/scale. This iswhat allows the Kubernetes HorizontalPodAutoscaler to interact withdifferent resources. With CRDs, however, each Kind will correspond toa single resource.

Notice that resources are always lowercase, and by convention are thelowercase form of the Kind.

So, how does that correspond to Go?

When we refer to a kind in a particular group-version, we’ll call ita GroupVersionKind, or GVK for short. Same with resources and GVR. Aswe’ll see shortly, each GVK corresponds to a given root Go type ina package.

Now that we have our terminology straight, we can actually create ourAPI!

Err, but what’s that Scheme thing?

The Scheme we saw before is simply a way to keep track of what Go typecorresponds to a given GVK (don’t be overwhelemed by itsgodocs).

For instance, suppose we mark that the"tutorial.kubebuilder.io/api/v1".CronJob{} type as being in thebatch.tutorial.kubebuilder.io/v1 API group (implicitly saying it has theKind CronJob).

Then, we can later construct a new &CronJob{} given some JSON from theAPI server that says

{
    "kind": "CronJob",
    "apiVersion": "batch.tutorial.kubebuilder.io/v1",
    ...
}

or properly look up the group-version when we go to submit a &CronJob{}in an update.