controller-runtime is a subproject of Kubebuilder, which provides a series of libraries for building controllers; Kubebuilder itself generates a lot of template code that uses controller-runtime. controller-runtime contains several The basic concepts are as follows.
- Controller: literally, a controller.
- Reconciler: provides the
Reconcilefunction, the main part of the
Controllerand the entry function, which contains all the business logic of the controller (equivalent to the
syncHandlerfunction in a normal controller), and is used to make the actual state of the object we care about gradually approach the to the desired state. The
Reconcileralso has the following features.
- Usually only one type of object is targeted, and different types of objects use separate controllers.
- Usually does not care about the content and type of events that trigger the
Reconcilefunction; for example, whether a
ReplicaSetis created or updated, the
Reconcileralways compares the number of
Pods in the cluster with the number set in the object, and then takes the appropriate action.
- Builder: Generate
Reconcilerbased on some configuration.
- Manager: manages and starts
Managercan contain multiple
The following is a step-by-step description of how to use the official simple example to build a controller using controller-runtime controller: first define the
Reconciler which contains the main logic of the controller, then use the
Builder to generate the
Controller and add it to the
Manager, and finally start the
Note: Take v0.5.0 version as an example, the definition of Reconcile function has changed in the latest version.
Each step is described in detail as follows.
Reconciler is defined as follows and contains only one
Result are defined as follows.
Request contains the namespace and name of this reconcile object, the object type is configured when generating the controller, a
Reconciler can only handle one type of object;
Result is basically nothing to care about, if
Reconcile returns an error it will automatically requeue.
ReplicaSetReconciler that contains a generic client provided by controller-runtime that functions like a normal kubernetes client and has access to all resources of the cluster.
But unlike the normal kubernetes client, this generic client is a single client that CRUD’s all types of resources, making it very convenient and easy to use.
Then there is the implementation of business logic.
InjectClient assigns the manager’s real client to
Builder and Manager
Builder is used to generate
Manager is used to manage and launch
Controller, which is introduced directly with an example, first generating a
where config is
rest.Config for client-go.
ReplicaSetReconciler and add it to
For function is used to specify the type of object we want to reconcile, and
Owns is used to watch the object whose owner is the reconcile object type (
Owns can specify multiple types), the add/delete/change events of both types of object will trigger the
Manager is started and the whole component is started.
If you want to write unit tests for a common controller, you should rely on the fake client provided by client-go, append various objects needed for testing to a fake client, and use the fake client to complete the tests. If you use the lister, you need to manually add the corresponding object to the corresponding informer indexer, for example.
The controller-runtime uses its own envtest package to start a real apiserver and etcd locally, and then connects to this apiserver for testing. We still need fake objects, but unlike the fake client, these fake objects are created in the apiserver started by controller-runtime, and in the case of CR, CRD needs to be registered with the new apiserver first. a complete example.
The controller-runtime framework itself provides a lot of libraries to help build the controller, making the whole process simple, shielding a lot of generic details to make the whole process of building the controller easier, interested students can try it in different scenarios and needs; even if we do not use controller-runtime we can also use its generic client and envtest and other generic libraries alone.
Separately, to use envtest you need to install a series of bin files (mainly etcd and kube-apiserver) provided by Kubebuilder in your runtime environment (your local and CI environment), you can download them yourself if you are local, or add them to the base image if you need them for your CI environment. An example.