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 package reconcile 18 19 import ( 20 "context" 21 "errors" 22 "reflect" 23 "time" 24 25 "k8s.io/apimachinery/pkg/types" 26 "sigs.k8s.io/controller-runtime/pkg/client" 27 ) 28 29 // Result contains the result of a Reconciler invocation. 30 type Result struct { 31 // Requeue tells the Controller to requeue the reconcile key. Defaults to false. 32 Requeue bool 33 34 // RequeueAfter if greater than 0, tells the Controller to requeue the reconcile key after the Duration. 35 // Implies that Requeue is true, there is no need to set Requeue to true at the same time as RequeueAfter. 36 RequeueAfter time.Duration 37 } 38 39 // IsZero returns true if this result is empty. 40 func (r *Result) IsZero() bool { 41 if r == nil { 42 return true 43 } 44 return *r == Result{} 45 } 46 47 // Request contains the information necessary to reconcile a Kubernetes object. This includes the 48 // information to uniquely identify the object - its Name and Namespace. It does NOT contain information about 49 // any specific Event or the object contents itself. 50 type Request struct { 51 // NamespacedName is the name and namespace of the object to reconcile. 52 types.NamespacedName 53 } 54 55 /* 56 Reconciler implements a Kubernetes API for a specific Resource by Creating, Updating or Deleting Kubernetes 57 objects, or by making changes to systems external to the cluster (e.g. cloudproviders, github, etc). 58 59 reconcile implementations compare the state specified in an object by a user against the actual cluster state, 60 and then perform operations to make the actual cluster state reflect the state specified by the user. 61 62 Typically, reconcile is triggered by a Controller in response to cluster Events (e.g. Creating, Updating, 63 Deleting Kubernetes objects) or external Events (GitHub Webhooks, polling external sources, etc). 64 65 Example reconcile Logic: 66 67 * Read an object and all the Pods it owns. 68 * Observe that the object spec specifies 5 replicas but actual cluster contains only 1 Pod replica. 69 * Create 4 Pods and set their OwnerReferences to the object. 70 71 reconcile may be implemented as either a type: 72 73 type reconciler struct {} 74 75 func (reconciler) Reconcile(ctx context.Context, o reconcile.Request) (reconcile.Result, error) { 76 // Implement business logic of reading and writing objects here 77 return reconcile.Result{}, nil 78 } 79 80 Or as a function: 81 82 reconcile.Func(func(ctx context.Context, o reconcile.Request) (reconcile.Result, error) { 83 // Implement business logic of reading and writing objects here 84 return reconcile.Result{}, nil 85 }) 86 87 Reconciliation is level-based, meaning action isn't driven off changes in individual Events, but instead is 88 driven by actual cluster state read from the apiserver or a local cache. 89 For example if responding to a Pod Delete Event, the Request won't contain that a Pod was deleted, 90 instead the reconcile function observes this when reading the cluster state and seeing the Pod as missing. 91 */ 92 type Reconciler interface { 93 // Reconcile performs a full reconciliation for the object referred to by the Request. 94 // 95 // If the returned error is non-nil, the Result is ignored and the request will be 96 // requeued using exponential backoff. The only exception is if the error is a 97 // TerminalError in which case no requeuing happens. 98 // 99 // If the error is nil and the returned Result has a non-zero result.RequeueAfter, the request 100 // will be requeued after the specified duration. 101 // 102 // If the error is nil and result.RequeueAfter is zero and result.Requeue is true, the request 103 // will be requeued using exponential backoff. 104 Reconcile(context.Context, Request) (Result, error) 105 } 106 107 // Func is a function that implements the reconcile interface. 108 type Func func(context.Context, Request) (Result, error) 109 110 var _ Reconciler = Func(nil) 111 112 // Reconcile implements Reconciler. 113 func (r Func) Reconcile(ctx context.Context, o Request) (Result, error) { return r(ctx, o) } 114 115 // ObjectReconciler is a specialized version of Reconciler that acts on instances of client.Object. Each reconciliation 116 // event gets the associated object from Kubernetes before passing it to Reconcile. An ObjectReconciler can be used in 117 // Builder.Complete by calling AsReconciler. See Reconciler for more details. 118 type ObjectReconciler[T client.Object] interface { 119 Reconcile(context.Context, T) (Result, error) 120 } 121 122 // AsReconciler creates a Reconciler based on the given ObjectReconciler. 123 func AsReconciler[T client.Object](client client.Client, rec ObjectReconciler[T]) Reconciler { 124 return &objectReconcilerAdapter[T]{ 125 objReconciler: rec, 126 client: client, 127 } 128 } 129 130 type objectReconcilerAdapter[T client.Object] struct { 131 objReconciler ObjectReconciler[T] 132 client client.Client 133 } 134 135 // Reconcile implements Reconciler. 136 func (a *objectReconcilerAdapter[T]) Reconcile(ctx context.Context, req Request) (Result, error) { 137 o := reflect.New(reflect.TypeOf(*new(T)).Elem()).Interface().(T) 138 if err := a.client.Get(ctx, req.NamespacedName, o); err != nil { 139 return Result{}, client.IgnoreNotFound(err) 140 } 141 142 return a.objReconciler.Reconcile(ctx, o) 143 } 144 145 // TerminalError is an error that will not be retried but still be logged 146 // and recorded in metrics. 147 func TerminalError(wrapped error) error { 148 return &terminalError{err: wrapped} 149 } 150 151 type terminalError struct { 152 err error 153 } 154 155 // This function will return nil if te.err is nil. 156 func (te *terminalError) Unwrap() error { 157 return te.err 158 } 159 160 func (te *terminalError) Error() string { 161 if te.err == nil { 162 return "nil terminal error" 163 } 164 return "terminal error: " + te.err.Error() 165 } 166 167 func (te *terminalError) Is(target error) bool { 168 tp := &terminalError{} 169 return errors.As(target, &tp) 170 } 171