rancher / wrangler

Wrangler Most people writing controllers are a bit lost as they find that there is nothing in Kubernetes that is like where you can just do . Instead a controller is really just a pattern of how you use the generated clientsets, informers, and listers combined with some custom event handlers and a workqueue. Wrangler is a framework for using controllers. Controllers wrap clients, informers, listers into a simple usable controller pattern that promotes some good practices. Some Projects that use Wrangler rancher eks-operator aks-operator gke-operator Versioning and Updates Wrangler releases use semantic versioning. New major releases are created for breaking changes, new minor releases are created for features, and patches are added for everything else. The most recent Major.Minor.x release and any releases being used by the most recent patch version of a supported rancher version will be maintained. The most recent major will receive minor releases, along with patch releases on its most up to date minor release. Older Major.Minor.x releases still in use by rancher will receive security patches at minimum. Consequently, there will be 1-3 maintained releases of the form Major.Minor.x at a time. Currently maintained versions: | Wrangler Version | Rancher Version | Update Level | | ---------------- | --------------- | ---------------------- | | 1.0.x | 2.6.x | Security Fixes | | 1.1.x | 2.7.x | Bug and Security Fixes | Wrangler releases are not from the default branch. Instead they are from branches with the naming pattern . The default branch (i.e. master) is where changes initially go. This includes bug fixes and new features. Bug fixes are cherry-picked to release branches to be included in patch releases. When it's time to create a new minor or major release, a new release branch is created from the default branch. Table of Contents • How it Works • Useful Definitions • How to Use Wrangler • How to Write and Register a Handler • Creating an Instance of a Controller • How to Run Handlers • Different Ways of Interacting with Objects • A Look at Structures Used in Wrangler How it Works Wrangler provides a code generator that will generate the clientset, informers, listers and additionally generate a controller per resource type. The interface to the controller can be seen in the Looking at Structures Used in Wrangler section. The controller interface along with other helpful structs, interfaces, and functions are provided by another project lasso. Lasso ties together the aforementioned tools while wrangler leverages them in a user friendly way. To use the controller to run custom code for Kubernetes resource types all one needs to do is register OnChange handlers and run the controller. Also using the controller interface one can access the client and caches through a simple flat API. A typical, non-wrangler Kubernetes application would most likely use an informer for a resource type to add an event handler. Instead, wrangler uses lasso to register each handler which then aggregates the handlers into one function that accepts an object for the controller's resource type and then runs that object through all the handlers. This function is then registered to the Kubernetes informer for that controller's respective resource type. This is done so that an object can run through the handlers in a serialized way. This allows each handler to receive the updated version of the object and avoid many conflicts that would otherwise occur if the handlers were not chained together in this fashion. Useful Definitions: factory Factories manage controllers. Wrangler generates factories for each API group. Wrangler factories use lasso shared factories for caches and controllers underneath. The lasso factories do most of the heavy lifting but are more resource type agnostic. Wrangler wraps lasso's factories to provide resource type specific clients and controllers. When accessing a wrangler generated controller, a controller for that resource type is requested from a lasso factory. If the controller exists it will be returned. Otherwise, the lasso factory will create it, persist it, and return it. You can consult the lasso repository for more details on factories. informers Broadcasts events for a given resource type and can register handlers for those events. listers Sometimes referred to as a cache, uses informers to update a local list of objects for a certain resource type to avoid making requests to the K8s API. event handlers Functions that run when a particular event is applied to the resource type the event handler is assigned to. workqueue A queue of items to be processed. In this context a queue will usually be a queue of objects of a certain resource type waiting to be processed by all handlers assigned to that resource type. How to Use Wrangler Generate controllers for CRDs by using Run() from the controllergen package. This will look like the following: For the structs to be used when generating controllers they must have the following comments above the structs (note the newline between the comment and struct so it is not rejected by linters): Four types are shown below. This file would be located at relative to the project root directory. The line passing the "./pkg/apis/management.cattle.io/v3" path ensure that the Setting and Catalog controllers are generated. The lines naming the ProjectCatalog and ClusterCatalog structs ensure the respective controllers are generated since neither directly have an ObjectMeta field.: __Note:__ This is real code taken from rancher and may not run at the time of reading this. This is meant to provide an example of how one might begin to use wrangler. Creating an Instance of a Controller Controllers are categorized by their API group and bundled into a struct called a factory. Functions to create factories are generated by the Run function discussed above. To run one of the functions that creates a factory, import the prop…