1 /* 2 Copyright 2018 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 /* 18 Package pkg provides libraries for building Controllers. Controllers implement Kubernetes APIs 19 and are foundational to building Operators, Workload APIs, Configuration APIs, Autoscalers, and more. 20 21 # Client 22 23 Client provides a Read + Write client for reading and writing Kubernetes objects. 24 25 # Cache 26 27 Cache provides a Read client for reading objects from a local cache. 28 A cache may register handlers to respond to events that update the cache. 29 30 # Manager 31 32 Manager is required for creating a Controller and provides the Controller shared dependencies such as 33 clients, caches, schemes, etc. Controllers should be Started through the Manager by calling Manager.Start. 34 35 # Controller 36 37 Controller implements a Kubernetes API by responding to events (object Create, Update, Delete) and ensuring that 38 the state specified in the Spec of the object matches the state of the system. This is called a reconcile. 39 If they do not match, the Controller will create / update / delete objects as needed to make them match. 40 41 Controllers are implemented as worker queues that process reconcile.Requests (requests to reconcile the 42 state for a specific object). 43 44 Unlike http handlers, Controllers DO NOT handle events directly, but enqueue Requests to eventually reconcile 45 the object. This means the handling of multiple events may be batched together and the full state of the 46 system must be read for each reconcile. 47 48 * Controllers require a Reconciler to be provided to perform the work pulled from the work queue. 49 50 * Controllers require Watches to be configured to enqueue reconcile.Requests in response to events. 51 52 # Webhook 53 54 Admission Webhooks are a mechanism for extending kubernetes APIs. Webhooks can be configured with target 55 event type (object Create, Update, Delete), the API server will send AdmissionRequests to them 56 when certain events happen. The webhooks may mutate and (or) validate the object embedded in 57 the AdmissionReview requests and send back the response to the API server. 58 59 There are 2 types of admission webhook: mutating and validating admission webhook. 60 Mutating webhook is used to mutate a core API object or a CRD instance before the API server admits it. 61 Validating webhook is used to validate if an object meets certain requirements. 62 63 * Admission Webhooks require Handler(s) to be provided to process the received AdmissionReview requests. 64 65 # Reconciler 66 67 Reconciler is a function provided to a Controller that may be called at anytime with the Name and Namespace of an object. 68 When called, the Reconciler will ensure that the state of the system matches what is specified in the object at the 69 time the Reconciler is called. 70 71 Example: Reconciler invoked for a ReplicaSet object. The ReplicaSet specifies 5 replicas but only 72 3 Pods exist in the system. The Reconciler creates 2 more Pods and sets their OwnerReference to point at the 73 ReplicaSet with controller=true. 74 75 * Reconciler contains all of the business logic of a Controller. 76 77 * Reconciler typically works on a single object type. - e.g. it will only reconcile ReplicaSets. For separate 78 types use separate Controllers. If you wish to trigger reconciles from other objects, you can provide 79 a mapping (e.g. owner references) that maps the object that triggers the reconcile to the object being reconciled. 80 81 * Reconciler is provided the Name / Namespace of the object to reconcile. 82 83 * Reconciler does not care about the event contents or event type responsible for triggering the reconcile. 84 - e.g. it doesn't matter whether a ReplicaSet was created or updated, Reconciler will always compare the number of 85 Pods in the system against what is specified in the object at the time it is called. 86 87 # Source 88 89 resource.Source is an argument to Controller.Watch that provides a stream of events. 90 Events typically come from watching Kubernetes APIs (e.g. Pod Create, Update, Delete). 91 92 Example: source.Kind uses the Kubernetes API Watch endpoint for a GroupVersionKind to provide 93 Create, Update, Delete events. 94 95 * Source provides a stream of events (e.g. object Create, Update, Delete) for Kubernetes objects typically 96 through the Watch API. 97 98 * Users SHOULD only use the provided Source implementations instead of implementing their own for nearly all cases. 99 100 # EventHandler 101 102 handler.EventHandler is an argument to Controller.Watch that enqueues reconcile.Requests in response to events. 103 104 Example: a Pod Create event from a Source is provided to the eventhandler.EnqueueHandler, which enqueues a 105 reconcile.Request containing the name / Namespace of the Pod. 106 107 * EventHandlers handle events by enqueueing reconcile.Requests for one or more objects. 108 109 * EventHandlers MAY map an event for an object to a reconcile.Request for an object of the same type. 110 111 * EventHandlers MAY map an event for an object to a reconcile.Request for an object of a different type - e.g. 112 map a Pod event to a reconcile.Request for the owning ReplicaSet. 113 114 * EventHandlers MAY map an event for an object to multiple reconcile.Requests for objects of the same or a different 115 type - e.g. map a Node event to objects that respond to cluster resize events. 116 117 * Users SHOULD only use the provided EventHandler implementations instead of implementing their own for almost 118 all cases. 119 120 # Predicate 121 122 predicate.Predicate is an optional argument to Controller.Watch that filters events. This allows common filters to be 123 reused and composed. 124 125 * Predicate takes an event and returns a bool (true to enqueue) 126 127 * Predicates are optional arguments 128 129 * Users SHOULD use the provided Predicate implementations, but MAY implement additional 130 Predicates e.g. generation changed, label selectors changed etc. 131 132 # PodController Diagram 133 134 Source provides event: 135 136 * &source.KindSource{&v1.Pod{}} -> (Pod foo/bar Create Event) 137 138 EventHandler enqueues Request: 139 140 * &handler.EnqueueRequestForObject{} -> (reconcile.Request{types.NamespaceName{Name: "foo", Namespace: "bar"}}) 141 142 Reconciler is called with the Request: 143 144 * Reconciler(reconcile.Request{types.NamespaceName{Name: "foo", Namespace: "bar"}}) 145 146 # Usage 147 148 The following example shows creating a new Controller program which Reconciles ReplicaSet objects in response 149 to Pod or ReplicaSet events. The Reconciler function simply adds a label to the ReplicaSet. 150 151 See the examples/builtins/main.go for a usage example. 152 153 Controller Example: 154 155 1. Watch ReplicaSet and Pods Sources 156 157 1.1 ReplicaSet -> handler.EnqueueRequestForObject - enqueue a Request with the ReplicaSet Namespace and Name. 158 159 1.2 Pod (created by ReplicaSet) -> handler.EnqueueRequestForOwnerHandler - enqueue a Request with the 160 Owning ReplicaSet Namespace and Name. 161 162 2. Reconcile ReplicaSet in response to an event 163 164 2.1 ReplicaSet object created -> Read ReplicaSet, try to read Pods -> if is missing create Pods. 165 166 2.2 Reconciler triggered by creation of Pods -> Read ReplicaSet and Pods, do nothing. 167 168 2.3 Reconciler triggered by deletion of Pods from some other actor -> Read ReplicaSet and Pods, create replacement Pods. 169 170 # Watching and EventHandling 171 172 Controllers may Watch multiple Kinds of objects (e.g. Pods, ReplicaSets and Deployments), but they reconcile 173 only a single Type. When one Type of object must be updated in response to changes in another Type of object, 174 an EnqueueRequestsFromMapFunc may be used to map events from one type to another. e.g. Respond to a cluster resize 175 event (add / delete Node) by re-reconciling all instances of some API. 176 177 A Deployment Controller might use an EnqueueRequestForObject and EnqueueRequestForOwner to: 178 179 * Watch for Deployment Events - enqueue the Namespace and Name of the Deployment. 180 181 * Watch for ReplicaSet Events - enqueue the Namespace and Name of the Deployment that created the ReplicaSet 182 (e.g the Owner) 183 184 Note: reconcile.Requests are deduplicated when they are enqueued. Many Pod Events for the same ReplicaSet 185 may trigger only 1 reconcile invocation as each Event results in the Handler trying to enqueue 186 the same reconcile.Request for the ReplicaSet. 187 188 # Controller Writing Tips 189 190 Reconciler Runtime Complexity: 191 192 * It is better to write Controllers to perform an O(1) reconcile N times (e.g. on N different objects) instead of 193 performing an O(N) reconcile 1 time (e.g. on a single object which manages N other objects). 194 195 * Example: If you need to update all Services in response to a Node being added - reconcile Services but Watch 196 Nodes (transformed to Service object name / Namespaces) instead of Reconciling Nodes and updating Services 197 198 Event Multiplexing: 199 200 * reconcile.Requests for the same Name / Namespace are batched and deduplicated when they are enqueued. This allows 201 Controllers to gracefully handle a high volume of events for a single object. Multiplexing multiple event Sources to 202 a single object Type will batch requests across events for different object types. 203 204 * Example: Pod events for a ReplicaSet are transformed to a ReplicaSet Name / Namespace, so the ReplicaSet 205 will be Reconciled only 1 time for multiple events from multiple Pods. 206 */ 207 package pkg 208