Understanding the Logic of Kubernetes API framework in Go

Question

I'm currently trying to wrap my head around learning Go, some details of the kubernetes API I haven't used before and the kubernetes api framework for Go at the same time, and would appreciate your help in understanding the grammar of that framework and why people use it anyways.

Honestly I'm not sure why to use a framework in the first place if it contains the same information as the REST endpoint. Wouldn't it make more sense to just call the API directly via a http library?

And here's one example (taken from some real code):

pod, err := kubecli.CoreV1().Pods(namespace).Get(name, metav1.GetOptions{})

What I feel bothersome is that I have to look up everything in the API docs and then I additionally need to figure out that /v1/ translates to CoreV1(). And I'm not even sure where I could look that up. Also the whole block metav1.GetOptions{} seems completely unnecessary, or which part of a HTTP request is represented by it?

I hope I could make clear what the confusion is and hope for your help in clearing it up.

Edit:

Here's also an example, generated from the new operator-framework which sadly doesn't make it much better:

 return &v1.Pod{
    TypeMeta: metav1.TypeMeta{
            Kind:       "Pod",
            APIVersion: "v1",
    },
    ObjectMeta: metav1.ObjectMeta{
            Name:      "busy-box",
            Namespace: cr.Namespace,
            OwnerReferences: []metav1.OwnerReference{
                    *metav1.NewControllerRef(cr, schema.GroupVersionKind{
                            Group:   v1alpha1.SchemeGroupVersion.Group,
                            Version: v1alpha1.SchemeGroupVersion.Version,
                            Kind:    "Memcached",
                    }),
            },
            Labels: labels,
    },
    Spec: v1.PodSpec{
            Containers: []v1.Container{
                    {
                            Name:    "busybox",
                            Image:   "busybox",
                            Command: []string{"sleep", "3600"},
                    },
            },
    },
 }

The API docs don't know anything about this TypeMeta object. And the second element is called ObjectMeta: instead of metadata. I mean, I'm not a magician. How should I know this.

Answer 1

I'm a bit late, but here is my 2 cents.

Why to use client-go instead of http library

There are serval pros with client-go.

1. Kubernetes resource is defined as strongly-typed class, means less misspelled debugging and easy to refactor.

2. When we manipulate some resources, It authenticates with cluster automatically (doc), what it only needs is a valid config. And we need not to know how exactly the authentication is done.

3. It has multiple versions compatible with different Kubernetes version. It make our code align with specify kubernetes version much easier, without knowing every detail of API changes.

How do I know which class and method should be called

In API Reference, each resource has the latest Group and Version tag. For example, Pod is group core, version v1, kind Pod in v1.10.

GoDoc listed all properties and links to detail explanation for every class like Pod.

So the pod list can be found by calling CoreV1(), then Pods(namespace string), then List(opts meta_v1.ListOptions).

Answer 2

Adding a couple of things to what's been mentioned so far:

You could indeed simply make http calls against the apiserver but client-go has already done all the hard work for you! Take for example this 'watch' endpoint:

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#watch-202

you could code up the functionality yourself, or make use of e.g. the SharedInformer interface

https://github.com/kubernetes/client-go/blob/master/tools/cache/shared_informer.go#L34-L41

The code in client-go has been tested and should be relatively bug-free.

If you set up your editor correctly for golang it will give you type hints and available function calls when you start typing in golang API calls.

I'd first learn golang and then try to grok client-go

Answer 3

A colleague suggested that there are in fact autogenerated docs called godoc. While it doesn't answer all questions it's improving my ability to to use the API libraries already.