はじめに
kubernetesのsample-controllerはご存知でしょうか?
もし知らない方のために説明しますと、kubernetesのdeploymentリソースをCustomResource経由で管理し、作成/更新/削除処理を自動化したcontrollerです。これからCustomControllerを開発しようとしている方の入門編としてのうってつけのsampleとなっています。
また、kubebuilderやoperator-SDKなどのSDKを使用せずclient-goとcode-generatorで書かれているので、Kubernetesのコードを読んでみようと思う方のコードリーディングの練習にもなります。
CustomController実装初心者がまずは読むべき本であり、私のバイブルである「実践入門 Kubernetesカスタムコントローラへの道」にて、既にsample-controllerの読み方は解説されておりますが、書面のページの都合上は端折られている箇所があります。
そこで、改めてコードリーディングし直したので、ステップ毎に細かく解説を入れてみました。
sample-controllerの動作
sample-controllerでは、CustomResourceDefinitionとCustomResourceをdeployすることで、CustomResourceに定義したdeploymentのnameとreplicasを使って、deploymentを自動作成します。
また、CustomResourceのreplicasを変更すると、自動でdeploymentも更新され、CustomResourceを削除することでdeploymentも削除される動作となります。
CustomResource定義例
以下のCustomResourceをdeployすることで、上記動作を実現することができます。
apiVersion: samplecontroller.k8s.io/v1alpha1
kind: Foo
metadata:
name: example-foo
spec:
deploymentName: example-foo
replicas: 1
Let’s コードリーディング
api
CustomResource定義には以下のspecとstatusがあります。
ユーザでは、specを指定しますが、statusはContollerによって自動で更新されます。
main関数
sample-controllerはmain.goのmain関数から読んでいきます。まず、はじめにシャットダウンシグナルのsetupを行います。
SetupSignalHandler関数
シャットダウンシグナルのsetupを行う、SetupSignalHandler関数を解説します。
goroutineでSignal受信を待ち、SIGINTまたはSIGTERMが発生した場合、channelをcloseします。
Signal定義は以下の通りです。
以上で、SetupSignalHandler関数の解説を終了します。
main関数の解説に戻ります。
次に、clientset生成します。
kubeClientが標準Resource(deployment)用、
exampleClientがCustomResource用です。
clientsetの作成が完了すると、InformerFactory生成されます。
kubeInformerFactoryが標準Resource(deployment)用、
exampleClientがCustomResource用です。
clientsetとInformerFactoryを使用し、controllerの生成を行います。
Controller構造体のメンバは以下の通りです。
NewController関数
controller生成を行う処理を解説します。
長いため、ステップ毎に解説していきます。
まず、schemeの生成します。
次にEvent recorderを生成します。
Controller構造体に、main関数で作成したclientsetやinformerなどの必要コンポーネントを代入します。
ちなみに、<InformerFactory>.Informer関数を実行することで、informerのメンバに値を代入しています。
informer追加の流れ
Informer関数でf.factory.InformerFor関数が呼ばれます。
InformerFor関数にはdefaultInformer関数の定義も渡されているので、newFunc(f.client, resyncPeriod)の行でdefaultInformer関数が呼ばれます。
defaultInformer関数から、NewFilteredFooInformer関数が呼ばれます。
NewFilteredFooInformer関数では、cache.NewSharedIndexInformer関数が呼ばれ、cache.SharedIndexInformer interfaceにcache.sharedIndexInformer構造体が代入されます。
cache.NewSharedIndexInformer関数定義
informerとなるcache.SharedInformerの定義
Eventごとに実行される関数を定義します。
fooInformerではcontroller.enqueueFoo関数が、deploymentInformerではcontroller.handleObject関数が実行されます。
各Event毎に実行される関数は後述します。
NewController関数内で、Event毎に実行される関数は以下の通りです。
enqueueFoo関数
cache.MetaNamespaceKeyFunc関数が呼ばれ、"namespace/name"形式でobjectのkeyを生成し、workqueueに追加します。
handleObject関数
deploymentのOwner Referenceを取得し、Owner名がCustomResourceの名前と同じであれば、上記enqueueFooを呼び出して、workqueueに追加します。
以上で、NewController関数の解説を終了します。
main関数の解説に戻ります。
標準ResourceとCustomResourceのinformerを開始します。
最後にcontrollerを開始します。
第一引数の2はWorker数です。
Reconcile処理
Reconcile処理ではLoopを使い、本来あるべき姿を保とうとします。
sample-controllerの場合、CustomResourceに定義されたdeploymentのnameとreplicasを使って、以下の処理を自動化します。
- deployment自動作成
- deploymentが削除されたら自動再作成
- CustomResourceの定義が変更されたら、deploymentの更新
- deploymentのreplicasを使って、CustomResourceのstatus更新
それではReconcile処理の解説をしていきます。
Run関数
Run関数では、In-Memory-Cacheを同期させて、Run関数の引数に指定された数だけWorkerを実行します。
cache.wait.Until関数で無限ループを実行することでReconcile Loopを実現しています。
Reconcile Loopの流れ
以下の流れで最終的にBackoffUntil関数が呼び出されます。
BackoffUntil関数には、controller.runWorker関数も引数で渡されているため、f()の箇所で実行され、SIGINTもしくはSIGTERMが発生するまで継続されます。
runWorker関数
runWorker関数はLoopでprocessNextWorkItem関数を呼び出すのみとなっており、戻り値がtrueの間継続されます。
processNextWorkItem関数
長いため、ステップ毎に解説します。
まず、workqueue.Get関数にてReconcileの処理対象itemを取得します。
もしqueueが空なら、即座にfalseを返し、processNextWorkItem関数を終了します。
falseをrunWorker関数に返すことでrunWorker関数を終了させます。
つまり、processNextWorkItem関数はqueueが空になるまで、runWorker関数によって実行されます。
queueから取り出したitemの処理は以下のように無名関数で実行されます。
上記関数をステップ毎に順を追って解説します。
processNextWorkItem関数処理終了後にはworkqueue.Done関数が完了させます。
もし、workqueue.Forget関数が実行されていれば、workqueueからitemを取り除かれます。
queueに入っているitemはリソースの"namespace/name"形式のstringで入っています。
まず、型アサーションでkeyを取り出します。もしstringでない場合は、workqueue.Forget関数がitemの追跡を停止します。その後、deferで前述したworkqueue.Done関数が実行され、workqueueからitemを取り除かれます。
取り出したkeyを引数にsyncHandle関数でdeploymentを作成します。
もしエラーが返ってきたら、AddRateLimited関数で遅延してrequeueし、再度処理対象とします。
この時、workqueue.Done関数では、itemは取り除かれません。
syncHandle関数が正常終了した場合は、workqueue.Forget関数でitemの追跡を停止し、deferでworkqueueからitemを取り除きます。
以上無名関数の解説でした。
processNextWorkItem関数の解説に戻ります。
無名関数でエラーが発生した場合は、エラーを出力しtrueを返し、エラーがない場合はtrueを返すのみとします。いずれにしても、Reconcile Loopは継続されます。
Reconcile Loop中はEvent発生→enqueueFoo関数でitemが入り続け、Loopが継続されます。
次にReconcileの中核であり、リソース作成を行うsyncHandler関数の解説を行います。
syncHandler関数
まず、keyは"namespace/name"の形式なので、/を区切り文字としてsplitします。
もしerrorが発生すれば、nilを返し、processNextWorkItem関数にworkqueueからitemを取り除きます。
次に、listerを使用し、CustomResource objectをIn-Memory-Cacheから取得します。
errors.IsNotFound(err)はerrがNot Foundエラーか否かを判定する関数で、もしNot Foundエラーであればtrueを返し、そうでなければfalseを返します。
以下のコードでは、取得に失敗した場合かつ、Not Foundエラーであればnilをreturnします。
また、Not Foundエラーでなく、単純に取得に失敗しているのであれば、errorをreturnします。
この処理にて、もしCustomResource objectが存在いるにも関わらずエラーが返る場合、processNextWorkItem関数にerrorを返し、workqueue.AddRateLimited関数で遅延requeue後、再度処理を行うことが可能であるためです。
もしerrors.IsNotFound(err)での判定がなければ、CustomResource objectが存在しない場合、requeueが繰り返されます。
CustomResource定義の.Spec.DeploymentNameからdeploymentの名前を生成し、もし名前が生成できない場合は、nilをreturnします。nilをreturnしているので、requeueせずに、itemがworkqueueから削除されます。
deployment objectをIn-Memory-Cacheから取得し、Not Foundエラーが返るのであれば、リソースを作成します。存在しているがobjectの取得ができない、もしくはリソースの作成に失敗する場合はrequeue処理に戻し、再度GetとCreateを試みます。
deploymentリソースの定義設定は、newDeployment関数で行うため、後ほど後述します。
この処理ではdeploymentのReplicasの更新を行います。
もし、CustomResourceの.Spec.Replicasと、deploymentの.Spec.Replicasが異なる場合は、CustomResourceの.Spec.Replicasを用いてdeploymentを更新します。
もし更新に失敗した場合は遅延requeueし、再度更新処理を行います。
updateFooStatus関数にて、CustomResourceのstatusを更新します。
もし更新に失敗する場合は遅延requeueし、再度更新処理を行います。
最後にEventを出力し、nilをreturnします。
これにてworkqueueがForget→Doneで完了します。
以上で、Reconcile処理を行う関数の解説を終了します。
最後に、deploymentの定義作成とCustomResourceのstatus更新を行う関数の解説を行います。
newDeployment関数
CustomResourceに定義されているdeployment定義より、deployment定義が作成されます。
また、”OwnerReferences: []metav1.OwnerReference”の箇所でOwnerReferenceが追加されており、CustomResource削除時にGCによりdeploymetも削除されるようになっています。
updateFooStatus関数
CustomResourceの.Status.AvailableReplicasと、deploymentの.Status.AvailableReplicasが異なる場合は、CustomResourceの.Status.AvailableReplicas更新します。
最後に
sample-controllerを細かく掘り下げてみました。
「実践入門 Kubernetesカスタムコントローラへの道」のsample-controllerの章の読書時や、これからsample-controllerをコードリーディングしようとしている方に、本記事が細かい箇所の手助けとなれば幸いです。
Discussion