|
| 1 | +{% panel style="info", title="Under Development" %} |
| 2 | +This book is being actively developed. |
| 3 | +{% endpanel %} |
| 4 | + |
| 5 | +# Controller Watch Functions |
| 6 | + |
| 7 | +This chapter describes how to use the controller package functions to configure Controllers to watch |
| 8 | +Resources. |
| 9 | + |
| 10 | +[Link to reference documentation](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller) |
| 11 | + |
| 12 | +{% method %} |
| 13 | +## Watching Controller Resource |
| 14 | + |
| 15 | +Controllers may watch Resources and trigger Reconcile calls with the key of the |
| 16 | +object from the watch event. |
| 17 | + |
| 18 | +This example configures a controller to watch for Pod events, and call Reconcile with |
| 19 | +the Pod key. |
| 20 | + |
| 21 | +If Pod *default/foo* is created, updated or deleted, then Reconcile will be called with |
| 22 | +*namespace: default, name: foo* |
| 23 | + |
| 24 | +{% sample lang="go" %} |
| 25 | +```go |
| 26 | +if err := c.Watch(&v1.Pod{}); err != nil { |
| 27 | + log.Fatalf("%v", err) |
| 28 | +} |
| 29 | +``` |
| 30 | +{% endmethod %} |
| 31 | + |
| 32 | + |
| 33 | +{% method %} |
| 34 | +## Watching Created Resources |
| 35 | + |
| 36 | +Controllers may watch Resources of types they create and trigger Reconcile calls with the key of |
| 37 | +the Owner of the object. |
| 38 | + |
| 39 | +This example configures a Controller to watch for Pod events, and call Reconcile with |
| 40 | +the Owner ReplicaSet key. This is done by looking up the object referred to by the Owner reference |
| 41 | +from the watch event object. |
| 42 | + |
| 43 | +- Define a function to lookup the Owner from the key |
| 44 | +- Call `WatchControllerOf` with the Owned object and the function to lookup the owner |
| 45 | + |
| 46 | +If Pod *default/foo-pod* was created by ReplicaSet *default/foo-rs*, and the Pod is |
| 47 | +(re)created, updated or deleted, then Reconcile will be called with *namespace: default, name: foo-rs* |
| 48 | + |
| 49 | +**Note:** This requires adding the following annotations to your Controller struct to ensure the |
| 50 | +correct RBAC rules are in place and informers have been started. |
| 51 | + |
| 52 | +```go |
| 53 | +// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list |
| 54 | +// +kubebuilder:informers:group=core,version=v1,kind=Pod |
| 55 | +``` |
| 56 | + |
| 57 | +{% sample lang="go" %} |
| 58 | +```go |
| 59 | +fn := func(k types.ReconcileKey) (interface{}, error) { |
| 60 | + return informerFactory. |
| 61 | + Apps().V1(). |
| 62 | + ReplicaSets(). |
| 63 | + Lister(). |
| 64 | + ReplicaSets(k.Namespace).Get(k.Name) |
| 65 | +} |
| 66 | +if err := c.WatchControllerOf( |
| 67 | + &corev1.Pod{}, eventhandlers.Path{fn} |
| 68 | +); err != nil { |
| 69 | + log.Fatalf("%v", err) |
| 70 | +} |
| 71 | +``` |
| 72 | +{% endmethod %} |
| 73 | + |
| 74 | +{% method %} |
| 75 | +## Watching Arbitrary Resources |
| 76 | + |
| 77 | +Controllers may watch arbitrary Resources and map them to a key of the Resource managed by the |
| 78 | +controller. Controllers may even map an event to multiple keys, triggering Reconciles for |
| 79 | +each key. |
| 80 | + |
| 81 | +Example: To respond to cluster scaling events (e.g. the deletion or addition of Nodes), |
| 82 | +a Controller would watch Nodes and map the watch events to keys of objects managed by |
| 83 | +the controller. |
| 84 | + |
| 85 | +This simple example configures a Controller to watch for Pod events, and then reconciles objects with |
| 86 | +names derived from the Pod's name. |
| 87 | + |
| 88 | +If Pod *default/foo* is created, updated or deleted, then Reconcile will be called for |
| 89 | +*namespace: default, name: foo-parent-1* and for *namespace: default, name: foo-parent-2*. |
| 90 | + |
| 91 | +**Note:** This requires adding the following annotations to your Controller struct to ensure the |
| 92 | +correct RBAC rules are in place and informers have been started. |
| 93 | + |
| 94 | +```go |
| 95 | +// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list |
| 96 | +// +kubebuilder:informers:group=core,version=v1,kind=Pod |
| 97 | +``` |
| 98 | + |
| 99 | +{% sample lang="go" %} |
| 100 | +```go |
| 101 | +if err := c.WatchTransformationKeysOf(&corev1.Pod{}, |
| 102 | + func(i interface{}) []types.ReconcileKey { |
| 103 | + p, ok := i.(*corev1.Pod) |
| 104 | + if !ok { |
| 105 | + return []types.ReconcileKey{} |
| 106 | + } |
| 107 | + |
| 108 | + // Find multiple parents based off the name |
| 109 | + n := strings.Split(p.Name, "-")[0] |
| 110 | + return []types.ReconcileKey{ |
| 111 | + {p.Namespace, n + "-mapto-1"}, |
| 112 | + {p.Namespace, n + "-mapto-2"}, |
| 113 | + } |
| 114 | + }, |
| 115 | +); err != nil { |
| 116 | + log.Fatalf("%v", err) |
| 117 | + |
| 118 | +} |
| 119 | +``` |
| 120 | +{% endmethod %} |
| 121 | + |
| 122 | + |
| 123 | +{% method %} |
| 124 | +## Watching Channels |
| 125 | + |
| 126 | +Controllers may watch channels for events to trigger Reconciles. This is useful if the Controller |
| 127 | +manages some external state that it is either polled or calls back via a WebHook. |
| 128 | + |
| 129 | +This simple example configures a Controller to read `namespace/name` keys from a channel and |
| 130 | +trigger Reconciles. |
| 131 | + |
| 132 | +If podkeys has *default/foo* inserted, then Reconcile will be called for *namespace: default, name: foo*. |
| 133 | + |
| 134 | +{% sample lang="go" %} |
| 135 | +```go |
| 136 | +podkeys := make(chan string) |
| 137 | +if err := c.WatchChannel(podkeys); err != nil { |
| 138 | + log.Fatalf("%v", err) |
| 139 | +} |
| 140 | +``` |
| 141 | +{% endmethod %} |
0 commit comments