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 builder 18 19 import ( 20 "sigs.k8s.io/controller-runtime/pkg/predicate" 21 ) 22 23 // {{{ "Functional" Option Interfaces 24 25 // ForOption is some configuration that modifies options for a For request. 26 type ForOption interface { 27 // ApplyToFor applies this configuration to the given for input. 28 ApplyToFor(*ForInput) 29 } 30 31 // OwnsOption is some configuration that modifies options for an owns request. 32 type OwnsOption interface { 33 // ApplyToOwns applies this configuration to the given owns input. 34 ApplyToOwns(*OwnsInput) 35 } 36 37 // WatchesOption is some configuration that modifies options for a watches request. 38 type WatchesOption interface { 39 // ApplyToWatches applies this configuration to the given watches options. 40 ApplyToWatches(*WatchesInput) 41 } 42 43 // }}} 44 45 // {{{ Multi-Type Options 46 47 // WithPredicates sets the given predicates list. 48 func WithPredicates(predicates ...predicate.Predicate) Predicates { 49 return Predicates{ 50 predicates: predicates, 51 } 52 } 53 54 // Predicates filters events before enqueuing the keys. 55 type Predicates struct { 56 predicates []predicate.Predicate 57 } 58 59 // ApplyToFor applies this configuration to the given ForInput options. 60 func (w Predicates) ApplyToFor(opts *ForInput) { 61 opts.predicates = w.predicates 62 } 63 64 // ApplyToOwns applies this configuration to the given OwnsInput options. 65 func (w Predicates) ApplyToOwns(opts *OwnsInput) { 66 opts.predicates = w.predicates 67 } 68 69 // ApplyToWatches applies this configuration to the given WatchesInput options. 70 func (w Predicates) ApplyToWatches(opts *WatchesInput) { 71 opts.predicates = w.predicates 72 } 73 74 var _ ForOption = &Predicates{} 75 var _ OwnsOption = &Predicates{} 76 var _ WatchesOption = &Predicates{} 77 78 // }}} 79 80 // {{{ For & Owns Dual-Type options 81 82 // projectAs configures the projection on the input. 83 // Currently only OnlyMetadata is supported. We might want to expand 84 // this to arbitrary non-special local projections in the future. 85 type projectAs objectProjection 86 87 // ApplyToFor applies this configuration to the given ForInput options. 88 func (p projectAs) ApplyToFor(opts *ForInput) { 89 opts.objectProjection = objectProjection(p) 90 } 91 92 // ApplyToOwns applies this configuration to the given OwnsInput options. 93 func (p projectAs) ApplyToOwns(opts *OwnsInput) { 94 opts.objectProjection = objectProjection(p) 95 } 96 97 // ApplyToWatches applies this configuration to the given WatchesInput options. 98 func (p projectAs) ApplyToWatches(opts *WatchesInput) { 99 opts.objectProjection = objectProjection(p) 100 } 101 102 var ( 103 // OnlyMetadata tells the controller to *only* cache metadata, and to watch 104 // the API server in metadata-only form. This is useful when watching 105 // lots of objects, really big objects, or objects for which you only know 106 // the GVK, but not the structure. You'll need to pass 107 // metav1.PartialObjectMetadata to the client when fetching objects in your 108 // reconciler, otherwise you'll end up with a duplicate structured or 109 // unstructured cache. 110 // 111 // When watching a resource with OnlyMetadata, for example the v1.Pod, you 112 // should not Get and List using the v1.Pod type. Instead, you should use 113 // the special metav1.PartialObjectMetadata type. 114 // 115 // ❌ Incorrect: 116 // 117 // pod := &v1.Pod{} 118 // mgr.GetClient().Get(ctx, nsAndName, pod) 119 // 120 // ✅ Correct: 121 // 122 // pod := &metav1.PartialObjectMetadata{} 123 // pod.SetGroupVersionKind(schema.GroupVersionKind{ 124 // Group: "", 125 // Version: "v1", 126 // Kind: "Pod", 127 // }) 128 // mgr.GetClient().Get(ctx, nsAndName, pod) 129 // 130 // In the first case, controller-runtime will create another cache for the 131 // concrete type on top of the metadata cache; this increases memory 132 // consumption and leads to race conditions as caches are not in sync. 133 OnlyMetadata = projectAs(projectAsMetadata) 134 135 _ ForOption = OnlyMetadata 136 _ OwnsOption = OnlyMetadata 137 _ WatchesOption = OnlyMetadata 138 ) 139 140 // }}} 141 142 // MatchEveryOwner determines whether the watch should be filtered based on 143 // controller ownership. As in, when the OwnerReference.Controller field is set. 144 // 145 // If passed as an option, 146 // the handler receives notification for every owner of the object with the given type. 147 // If unset (default), the handler receives notification only for the first 148 // OwnerReference with `Controller: true`. 149 var MatchEveryOwner = &matchEveryOwner{} 150 151 type matchEveryOwner struct{} 152 153 // ApplyToOwns applies this configuration to the given OwnsInput options. 154 func (o matchEveryOwner) ApplyToOwns(opts *OwnsInput) { 155 opts.matchEveryOwner = true 156 } 157