kooper

module
v0.22.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2021 License: Apache-2.0

README

Kooper Build Status Go Report Card GoDoc

Kooper is a simple Go library to create Kubernetes operators and controllers.

What is Kooper?

Kooper is a set of utilities packed as a library or framework to easily create Kubernetes controllers and operators.

There is a little of discussion of what a controller and what an operator is, see here for more information.

In Kooper the concepts of controller an operator are very simple, a controller controls the state of a resource in Kubernetes, and an operator is a controller that initializes custom resources (CRD) and controls the state of this custom resource.

Features

  • Easy and decoupled library.
  • Well structured and a clear API.
  • Remove all duplicated code from every controller and operator.
  • Uses the tooling already created by Kubernetes.
  • Remove complexity from operators and controllers so the focus is on domain logic.
  • Easy to mock and extend functionality (Go interfaces!).
  • Only support CRD, no TPR support (Kubernetes >=1.7).
  • Controller metrics (with a Grafana dashboard based on Prometheus metrics backend).
  • Leader election.
  • Tracing with Opentracing.

Example

It can be seen how easy is to develop a controller or an operator in kooper looking at the documentation.

This is a simple pod log controller example (full running example here):

// Initialize resources like logger and kubernetes client
//...

// Create our retriever so the controller knows how to get/listen for pod events.
retr := &retrieve.Resource{
    Object: &corev1.Pod{},
    ListerWatcher: &cache.ListWatch{
        ListFunc: func(options metav1.ListOptions) (runtime.Object, error) {
            return k8scli.CoreV1().Pods("").List(options)
        },
        WatchFunc: func(options metav1.ListOptions) (watch.Interface, error) {
            return k8scli.CoreV1().Pods("").Watch(options)
        },
    },
}

// Our domain logic that will print every add/sync/update and delete event.
hand := &handler.HandlerFunc{
    AddFunc: func(_ context.Context, obj runtime.Object) error {
        pod := obj.(*corev1.Pod)
        log.Infof("Pod added: %s/%s", pod.Namespace, pod.Name)
        return nil
    },
    DeleteFunc: func(_ context.Context, s string) error {
        log.Infof("Pod deleted: %s", s)
        return nil
    },
}

// Create the controller that will refresh every 30 seconds.
ctrl := controller.NewSequential(30*time.Second, hand, retr, nil, log)
stopC := make(chan struct{})
if err := ctrl.Run(stopC); err != nil {
    log.Errorf("error running controller: %s", err)
    os.Exit(1)
}
os.Exit(0)

The above shows that it is very easy to get a controller working in less than 100 lines of code. How it works can be demonstrated by running the controller from this repository.

go run ./examples/onefile-echo-pod-controller/main.go

or directly using docker (Note you are binding kubernetes configuration on the container so kooper can connect to kubernetes cluster).

docker run \
    --rm -it \
    -v ${HOME}/.kube:/root/.kube:ro \
    golang:1.10 \
    /bin/bash -c "go get github.com/szlabs/kooper/... && cd /go/src/github.com/szlabs/kooper && go run ./examples/onefile-echo-pod-controller/main.go"

Motivation

The state of art in the operators/controllers moves fast, a lot of new operators are being published every day. Most of them have the same "infrastructure" code refering Kubernetes operators/controllers and bootstrapping a new operator can be slow or repetitive.

At this moment there is no standard, although there are some projects like rook operator kit or Giantswarm operator kit that are trying to create it.

szlabs studied these projects before developing Kooper and they didn't fit the requirements:

  • Clear and maintanable code.
  • Easy to test and mock.
  • Well tested library.
  • Easy and clear programming API.
  • Good abstraction and structure to focus on domain logic (the meat of the controller).
  • Reduce complexity in all the operators and controllers that use the library.
  • Not only operators, controllers as first class citizen also.

Installing

Any dependency manager can get Kooper or directly with go get the latest version:

go get -u github.com/szlabs/kooper

Using Kooper as a dependency

Managing a project that uses different kubernetes libs as dependencies can be tricky at first because of the different versions of all these libraries(apimachinery, client-go, api...). Here you have an example of how would you use kooper as a dependency in a project and setting the kubernetes libraries to the version that you want along with kooper (using dep).

Compatibility matrix

Kubernetes <=1.9 Kubernetes 1.10 Kubernetes 1.11 Kubernetes 1.12 Kubernetes 1.13 Kubernetes 1.14
kooper 0.1 ? ? ? ? ?
kooper 0.2 ? ? ? ? ?
kooper 0.3 ?+ ? ? ? ?
kooper 0.4 ?+ ? ? ? ?
kooper 0.5 ? ?+ ? ? ?
kooper 0.6 ? ? ?+ ? ?
kooper HEAD ? ? ? ?+ ✓? ?

Based on this matrix Kooper needs different versions of Kubernetes dependencies.

An example would be. If the cluster that will use kooper operators/controllers is a 1.9.x Kubernetes cluster, the version of kooper would be 0.2.x and the kubernetes libraries in 1.9.x compatibility style. For example the project that uses kooper as a dependency, its dep file would be something like this:

...

[[override]]
  name = "k8s.io/api"
  version = "kubernetes-1.9.6"

[[override]]
  name = "k8s.io/apimachinery"
  version = "kubernetes-1.9.6"

[[override]]
  name = "k8s.io/client-go"
  version = "kubernetes-1.9.6"

[[constraint]]
  name = "github.com/szlabs/kooper"
  version = "0.2.0"

...

Documentation

Kooper comes with different topics as documentation.

Core
Other

The starting point would be to check the concepts and then continue with the controller and operator tutorials.

Who is using kooper

Directories

Path Synopsis
client
crd
examples
pod-terminator-operator/apis/chaos/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
Package v1alpha1 is the v1alpha1 version of the API.
pod-terminator-operator/client/k8s/clientset/versioned
This package has the automatically generated clientset.
This package has the automatically generated clientset.
pod-terminator-operator/client/k8s/clientset/versioned/fake
This package has the automatically generated fake clientset.
This package has the automatically generated fake clientset.
pod-terminator-operator/client/k8s/clientset/versioned/scheme
This package contains the scheme of the automatically generated clientset.
This package contains the scheme of the automatically generated clientset.
pod-terminator-operator/client/k8s/clientset/versioned/typed/chaos/v1alpha1
This package has the automatically generated typed clients.
This package has the automatically generated typed clients.
pod-terminator-operator/client/k8s/clientset/versioned/typed/chaos/v1alpha1/fake
Package fake has the automatically generated clients.
Package fake has the automatically generated clients.
Package mocks will have all the mocks of the library, we'll try to use mocking using blackbox testing and integration tests whenever is possible.
Package mocks will have all the mocks of the library, we'll try to use mocking using blackbox testing and integration tests whenever is possible.
monitoring
Package operator contains implementations and definitions to create Kubernetes operators and controllers
Package operator contains implementations and definitions to create Kubernetes operators and controllers
controller
Package controller contains implementation and defition to create kubernetes controllers.
Package controller contains implementation and defition to create kubernetes controllers.
test
integration/operator/apis/superhero/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
Package v1alpha1 is the v1alpha1 version of the API.
integration/operator/client/k8s/clientset/versioned
This package has the automatically generated clientset.
This package has the automatically generated clientset.
integration/operator/client/k8s/clientset/versioned/fake
This package has the automatically generated fake clientset.
This package has the automatically generated fake clientset.
integration/operator/client/k8s/clientset/versioned/scheme
This package contains the scheme of the automatically generated clientset.
This package contains the scheme of the automatically generated clientset.
integration/operator/client/k8s/clientset/versioned/typed/superhero/v1alpha1
This package has the automatically generated typed clients.
This package has the automatically generated typed clients.
integration/operator/client/k8s/clientset/versioned/typed/superhero/v1alpha1/fake
Package fake has the automatically generated clients.
Package fake has the automatically generated clients.
wrapper

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL