Upgrade to Pro — share decks privately, control downloads, hide ads and more …

WIP: Dive Into controller-runtime v0.9.3

WIP: Dive Into controller-runtime v0.9.3

controller-runtime v0.9.3について詳しくまとめます.
また途中です.ちょくちょくpackage単位で加筆予定.

v0.1: package builder
v0.2: package cache & certwatcher
v0.3:package client

Ec9465c5a5f2ea26a80db56f9d2f99b0?s=128

Drumato

July 30, 2021
Tweet

Transcript

  1. 詳解 Controller-runtime v0.9.3 Drumato

  2. Notation • 本スライドでは以下の略語を使用します • Custom Controller … CC • k8s

    … K8s/k8s • Resource type … RT ◦ API endpointに用いられるresourceのplural nameのこと
  3. Objectives/Attentions • Controller-runtimeの機能を網羅的に把握する ◦ 詳しい仕組み/内部実装を知るわけではないので注意 • CCの"こんなときはこう書く"をある程度clearにしたい • 0.9.3で増えたこと,みたいなのを話すわけではないです ◦

    controller-runtimeのPATCH versionはどんどん増える • 内容が古かったり間違っていても責任を負いません • 随時更新します,じっくり待っていただけると
  4. controller-runtime structure そのまま使うことが多くないものも掲載

  5. Structure builder reconcile.Reconcilerに対する初期化をうまくやるためのAPI suite cache client-go/tools/cacheを更にwrapしたもの Informerなどのclient-go componentをうまく抽象化している certwatcher fsnotifyを用いたtls.Config.GetCertificateの実装

    HTTPS serverを起動中にcertificate/keyを変更できるように client K8s API client wrapper cluster Cache等にaccessするinterface Manager interfaceはCluster interfaceを実装 config controller-runtimeのcomponent configのための機能を提供 通常は自動生成される(ex. tenant-controller) controller CCをつくるための機能 Managerから間接的に叩くことを強く推奨している ただしcontroller/controllerutil はよく使う
  6. Structure conversion Conversion Webhookのためのinterface def 実装はwebhook/conversion envtest Local cplaneを用いたintegration testのための機能

    event Reconcile targetとなるresourceに関するeventを表現したtype def finalizer Finalizerに関するinterface def 使うときはcontrollerutil handler External event watcherを書くときに使ったり healthz Health Checkのために使うtype defなど Manager.AddHealthzCheck()を使うのが基本 leaderelection CCのLeader electionに関する定義 NewManager()時にoptionを渡せば良いのでこのpackageは意識しない log go-logrをcontroller-runtimeがwrapしたもの
  7. Structure manager Controllerの作成に用いられる cache/client/scheme等はこれを経由して触る metrics Metricsに関するもの predicate controllerpredicateに関するAPI suite ratelimiter

    Controllerに対するrequest queueを制限するinterface def 自分で定義するとかはせず,client-goのdefault implを設定して使う reconcile Reconcilerを表すinterfaceなど ResultやRequestのみ触る recorder k8s Eventの発行に関するinterface def Manager.GetEventRecorderFor()を使ってinstantiation runtime 歴史的背景で残っていて,今はほぼ使わない runtime/injectのみ使うかも scheme k8s API に関するGo typesを扱うためのもの
  8. Structure source Controllerのhookに使われる,event streamのためのAPI suite webhook Webhook serverの構築に使われるAPI suite 現在はAdmission

    Webhookにのみ対応し, Conversion Webhookについてはfuture worksとしている
  9. Builder -building a controller smoothly-

  10. Builder • CCの初期化をきれいに書ける,conf injection API • ざっくりと出来ること ◦ controllerのwatch対象を追加/制御できる ◦

    controllerpredicateを設定できる ◦ RateLimiter/Logger/CacheSyncTimeoutの設定をcustomizeできる • Kubebuilderによって自動生成されるので,これ使うのがdefault
  11. Builder#For • controllerのwatch対象となるresource typeを指定する • Create/Delete/Update eventがtriggerとなってreconcileが呼び出されるように • 必ず一度だけ呼び出す,呼び出さなかったり二回呼び出すとerror •

    v0.6.0からopts が追加,For resourceにのみpredicateを書いたり出来るように ◦ 神PR ◦ Kubebuilder v2ではv0.5.0がdefault,v3にupdateするか,go.modを書き換える ◦ 現在ForOptionを実装しているのはWithPredicateとprojectAsのみ ▪ projectAs … 対象objectのmetadataのみを見るようにするoption?
  12. Builder#Owns • controllerによって生成されるresource typeを指定する • Child resourceのCreate/Update/Deleteから"For resource"のreconcileが発火する ◦ Childの変更を検知したければ使うと良い

    ◦ というかSetControllerReference()したObjectは書いとこう • 同じくopts によって個別にconfigできる • 内部的には Builder.OwnsInput []OwnsInput というmemberに格納 ◦ Forと違って複数回呼び出すことができる
  13. Builder#Watches • For()やOwns()が呼び出す,low-level API • v0.5.0でこれを使っても個別にPredicateを実装することはできなさそう ◦ For()の格納先と • ownerReferenceによって結ばれないresourceのeventでreconcile起こしたいなら

    • optsによって以下略 • handler.EventHandlerについては後述
  14. Builder#WithEventFilter • Reconcile eventに対してpredicateを設定するための機能 • Attention: reconcile eventとtargetは別! • Predicateについて詳しくは後述

    • An important point: ForやOwnsなど,すべてのreconcile eventに引っかかる ◦ For resourceもchild resourceにもこのFilterが適用される ◦ 各Event構造体にどちらのresourceが入っているかはruntime checkが必要 ▪ なんかちゃんとGVKが埋まってない時がある...? • 一応こういうIssueがあった ▪ Type castingして,第二引数のboolを使うのが良さそう • Type switchでも良い
  15. Builder#WithOptions • RateLimiterやLoggerの注入など • CacheSyncTimeoutの設定ができるの,意外と重要? ◦ CacheSyncTimeout … controller Listerが待つ時間の設定

    ▪ この時間を超えてもsyncできないとmgr.Start()がerror返す
  16. WebhookBuilder • Webhook Serverを建てるためのBuilder ◦ Kubebuilder なら create webhookだけで自動生成される •

    同じようにFor().Complete()するだけ ◦ 簡単 • 前はBuilderで一斉管理していたのが分割されたっぽい ◦ PR
  17. Cache -Cache k8s object at client side-

  18. Cache • Informerなど,API object cacheに関する処理や構造を隠蔽している • Manager(のdefault impl)が暗黙的に使っているのであまり意識することはない ◦ API

    access関係の実装を知りたくなったらcache packageに,ぐらいの感覚でいいかも ◦ Cache mechanismを理解したかったらここらへんから読み始めると良さそう • Managerに対してGetFieldIndexer()とか呼ぶと,実際にはCache APIが動く
  19. Certwatcher -Certificate and key utility-

  20. Certwatcher • fsnotifyを使った証明書/鍵の管理を行う機能 ◦ fsnotify … file update/create/modify/rename等を監視できる機能 ▪ inotifyという,Linux

    inode basedな監視APIが有名 • CCで必須となるcomponentとかではない • 使い方 … tls.Config.GetCertificateに渡すだけ ◦ usecase … 証明書を更新したりしたときにserver reloadが必要なさそう • これもWebhookBuilderを使うと勝手に使用される ◦ controller-runtimeでの使われ方 ▪ STEP1: WebhookBuilderがServer structをいい感じに設定する ▪ STEP2: ManagerがServerを起動してくれる ◦ こういうのが動いているんだな,くらいで良さそう • 実は文字通り"ささやかな"contributionしました ◦ Just fix typo...
  21. Client -Interact with Kubernetes API Server-

  22. Client • Kubernetes APIを扱うためのpackage • 2つのinterfaceを持つ ◦ Reader … Get/List

    ◦ Writer … Create/Update/Delete • 普通にNew()を呼ぶとdirect clientが使える • Kubernetesとしては"cacheから読む,API serverに書き込む"というのが基本 ◦ NewDelegatingClient()を呼べばこのpatternを踏襲したclientが使える ◦ ReaderとWriterで異なるresourceを扱いたい場合にも有効 ◦ NewManager()したときもこれを使われているはず ▪ ymmtさんの記事にある"Unstructured Objectはdefaultではcacheされない"には注意 • 以下のsub packageが存在 ◦ apiutil … low-level apiが中心 ◦ config … client config ◦ fake … test用package 多分ほぼ読まない
  23. だいぶ大きなpackageなので 一部のみ話します

  24. Client#ListOptions • List API実行時に使われるconfig information • 以下のfieldを持つ ◦ LabelSelector ◦

    FieldSelector ◦ Namespace ◦ Limit … API serverから返ってくるList Entryの数に制限をかける ▪ もしLimitより多くのentryが存在する場合List objectにContinueが入っている ◦ Continue ◦ Raw … その他細かいconfigを設定できるやつ ▪ ResourceVersionとか
  25. Client#IgnoreNotFound • Get API等を実行したときのerrorからNotFoundを取り除く仕組み • Resource deleteを実行したときにcontrollerがerror起こさないように使う事が多 い • Reconcile

    Eventに照らし合わせると,CCでの利用はほぼ必須? ◦ Finalizer未使用 -> reconcile by deleteの段階でGet -> Errorが返る ◦ Finalizer使用 -> deletionTimestampがつくだけなのでUpdateが来るが,後々Deleteも来る • 私の記事を見てもらえると!
  26. Client#Indexing • FieldIndexerという仕組みで, object lookupを効率的/効果的に行える仕組み ◦ Kubebuilder Bookを読むとsimple usecaseが書かれてある ▪

    まずはFieldIndexerを使ってowner refでindexing ▪ あとはList()の際にindexでlookupすれば良い
  27. Cluster -Interact with Kubernetes Cluster-