Debian Codegraph @

pkg/server/hooks.go

raw
1 /*
2 Copyright 2014 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 server
18
19 import (
20 "context"
21 "errors"
22 "fmt"
23 "net/http"
24 "runtime/debug"
25
26 utilerrors "k8s.io/apimachinery/pkg/util/errors"
27 utilruntime "k8s.io/apimachinery/pkg/util/runtime"
28 "k8s.io/apiserver/pkg/server/healthz"
29 restclient "k8s.io/client-go/rest"
30 "k8s.io/klog/v2"
31 )
32
33 // PostStartHookFunc is a function that is called after the server has started.
34 // It must properly handle cases like:
35 // 1. asynchronous start in multiple API server processes
36 // 2. conflicts between the different processes all trying to perform the same action
37 // 3. partially complete work (API server crashes while running your hook)
38 // 4. API server access **BEFORE** your hook has completed
39 //
40 // Think of it like a mini-controller that is super privileged and gets to run in-process
41 // If you use this feature, tag @deads2k on github who has promised to review code for anyone's PostStartHook
42 // until it becomes easier to use.
43 type PostStartHookFunc func(context PostStartHookContext) error
44
45 // PreShutdownHookFunc is a function that can be added to the shutdown logic.
46 type PreShutdownHookFunc func() error
47
48 // PostStartHookContext provides information about this API server to a PostStartHookFunc
49 type PostStartHookContext struct {
50 // LoopbackClientConfig is a config for a privileged loopback connection to the API server
51 LoopbackClientConfig *restclient.Config
52 // Context gets cancelled when the server stops.
53 context.Context
54 }
55
56 // PostStartHookProvider is an interface in addition to provide a post start hook for the api server
57 type PostStartHookProvider interface {
58 PostStartHook() (string, PostStartHookFunc, error)
59 }
60
61 type postStartHookEntry struct {
62 hook PostStartHookFunc
63 // originatingStack holds the stack that registered postStartHooks. This allows us to show a more helpful message
64 // for duplicate registration.
65 originatingStack string
66
67 // done will be closed when the postHook is finished
68 done chan struct{}
69 }
70
71 type PostStartHookConfigEntry struct {
72 hook PostStartHookFunc
73 // originatingStack holds the stack that registered postStartHooks. This allows us to show a more helpful message
74 // for duplicate registration.
75 originatingStack string
76 }
77
78 type preShutdownHookEntry struct {
79 hook PreShutdownHookFunc
80 }
81
82 // AddPostStartHook allows you to add a PostStartHook.
83 func (s *GenericAPIServer) AddPostStartHook(name string, hook PostStartHookFunc) error {
84 if len(name) == 0 {
85 return fmt.Errorf("missing name")
86 }
87 if hook == nil {
88 return fmt.Errorf("hook func may not be nil: %q", name)
89 }
90 if s.disabledPostStartHooks.Has(name) {
91 klog.V(1).Infof("skipping %q because it was explicitly disabled", name)
92 return nil
93 }
94
95 s.postStartHookLock.Lock()
96 defer s.postStartHookLock.Unlock()
97
98 if s.postStartHooksCalled {
99 return fmt.Errorf("unable to add %q because PostStartHooks have already been called", name)
100 }
101 if postStartHook, exists := s.postStartHooks[name]; exists {
102 // this is programmer error, but it can be hard to debug
103 return fmt.Errorf("unable to add %q because it was already registered by: %s", name, postStartHook.originatingStack)
104 }
105
106 // done is closed when the poststarthook is finished. This is used by the health check to be able to indicate
107 // that the poststarthook is finished
108 done := make(chan struct{})
109 if err := s.AddBootSequenceHealthChecks(postStartHookHealthz{name: "poststarthook/" + name, done: done}); err != nil {
110 return err
111 }
112 s.postStartHooks[name] = postStartHookEntry{hook: hook, originatingStack: string(debug.Stack()), done: done}
113
114 return nil
115 }
116
117 // AddPostStartHookOrDie allows you to add a PostStartHook, but dies on failure
118 func (s *GenericAPIServer) AddPostStartHookOrDie(name string, hook PostStartHookFunc) {
119 if err := s.AddPostStartHook(name, hook); err != nil {
120 klog.Fatalf("Error registering PostStartHook %q: %v", name, err)
121 }
122 }
123
124 // AddPreShutdownHook allows you to add a PreShutdownHook.
125 func (s *GenericAPIServer) AddPreShutdownHook(name string, hook PreShutdownHookFunc) error {
126 if len(name) == 0 {
127 return fmt.Errorf("missing name")
128 }
129 if hook == nil {
130 return nil
131 }
132
133 s.preShutdownHookLock.Lock()
134 defer s.preShutdownHookLock.Unlock()
135
136 if s.preShutdownHooksCalled {
137 return fmt.Errorf("unable to add %q because PreShutdownHooks have already been called", name)
138 }
139 if _, exists := s.preShutdownHooks[name]; exists {
140 return fmt.Errorf("unable to add %q because it is already registered", name)
141 }
142
143 s.preShutdownHooks[name] = preShutdownHookEntry{hook: hook}
144
145 return nil
146 }
147
148 // AddPreShutdownHookOrDie allows you to add a PostStartHook, but dies on failure
149 func (s *GenericAPIServer) AddPreShutdownHookOrDie(name string, hook PreShutdownHookFunc) {
150 if err := s.AddPreShutdownHook(name, hook); err != nil {
151 klog.Fatalf("Error registering PreShutdownHook %q: %v", name, err)
152 }
153 }
154
155 // RunPostStartHooks runs the PostStartHooks for the server.
156 func (s *GenericAPIServer) RunPostStartHooks(ctx context.Context) {
157 s.postStartHookLock.Lock()
158 defer s.postStartHookLock.Unlock()
159 s.postStartHooksCalled = true
160
161 context := PostStartHookContext{
162 LoopbackClientConfig: s.LoopbackClientConfig,
163 Context: ctx,
164 }
165
166 for hookName, hookEntry := range s.postStartHooks {
167 go runPostStartHook(hookName, hookEntry, context)
168 }
169 }
170
171 // RunPreShutdownHooks runs the PreShutdownHooks for the server
172 func (s *GenericAPIServer) RunPreShutdownHooks() error {
173 var errorList []error
174
175 s.preShutdownHookLock.Lock()
176 defer s.preShutdownHookLock.Unlock()
177 s.preShutdownHooksCalled = true
178
179 for hookName, hookEntry := range s.preShutdownHooks {
180 if err := runPreShutdownHook(hookName, hookEntry); err != nil {
181 errorList = append(errorList, err)
182 }
183 }
184 return utilerrors.NewAggregate(errorList)
185 }
186
187 // isPostStartHookRegistered checks whether a given PostStartHook is registered
188 func (s *GenericAPIServer) isPostStartHookRegistered(name string) bool {
189 s.postStartHookLock.Lock()
190 defer s.postStartHookLock.Unlock()
191 _, exists := s.postStartHooks[name]
192 return exists
193 }
194
195 func runPostStartHook(name string, entry postStartHookEntry, context PostStartHookContext) {
196 var err error
197 func() {
198 // don't let the hook *accidentally* panic and kill the server
199 defer utilruntime.HandleCrash()
200 err = entry.hook(context)
201 }()
202 // if the hook intentionally wants to kill server, let it.
203 if err != nil {
204 klog.Fatalf("PostStartHook %q failed: %v", name, err)
205 }
206 close(entry.done)
207 }
208
209 func runPreShutdownHook(name string, entry preShutdownHookEntry) error {
210 var err error
211 func() {
212 // don't let the hook *accidentally* panic and kill the server
213 defer utilruntime.HandleCrash()
214 err = entry.hook()
215 }()
216 if err != nil {
217 return fmt.Errorf("PreShutdownHook %q failed: %v", name, err)
218 }
219 return nil
220 }
221
222 // postStartHookHealthz implements a healthz check for poststarthooks. It will return a "hookNotFinished"
223 // error until the poststarthook is finished.
224 type postStartHookHealthz struct {
225 name string
226
227 // done will be closed when the postStartHook is finished
228 done chan struct{}
229 }
230
231 var _ healthz.HealthChecker = postStartHookHealthz{}
232
233 func (h postStartHookHealthz) Name() string {
234 return h.name
235 }
236
237 var errHookNotFinished = errors.New("not finished")
238
239 func (h postStartHookHealthz) Check(req *http.Request) error {
240 select {
241 case <-h.done:
242 return nil
243 default:
244 return errHookNotFinished
245 }
246 }