![Webhook: Deep Dive
34
▌admission.Response には builder が複数種?意されている
https://godoc.org/sigs.k8s.io/controller-
runtime/pkg/webhook/admission#Response
func Allowed(reason string) Response {}
func Denied(reason string) Response {}
func Patched(reason string, patches ...jsonpatch.JsonPatchOperation) Response {}
func Errored(code int32, err error) Response {}
func ValidationResponse(allowed bool, reason string) Response {}
func PatchResponseFromRaw(original, current []byte) Response {}](https://image.slidesharecdn.com/k8smeetup-kubebuilder-v2-190927060304/85/Kubernetes-Meetup-Tokyo-23-kubebuilder-v2-34-320.jpg)
Kubernetes Meetup Tokyo #23 kubebuilder-v2
- 1. Kubebuilder /controller-runtime ?? with v2 Kazuhito MATSUDA
- 2. ??紹介: 松? ?仁 ▌エンジニア＠Cybozu, Inc. lインフラ刷新チーム Neco l@kfyharukz (GitHub) l(研究員, 富?通研究所) l 今?のコードサンプルは以下にあります https://github.com/kfyharukz/kubebuilder-tutorial 2
- 3. kubebuilder ▌CRD 及び controller を作るためのフレームワーク l kubebuilder それ?体はサブプロジェクトの成果物を利? した CLI ツール l controller-runtime l controller を実装するためのライブラリ l Discovery ベースの k8s Client を持つ l controller-tools l コードから DeepCopy 及び k8s manifest を?成するツール 3
- 4. やってみよう 4 install: https://book.kubebuilder.io/quick-start.html で，何すればいいの? $ kubebuilder init --domain piyo.com $ kubebuilder create api --group fuga --version v1 --kind Hoge $ kubebuilder create webhook --group fuga --version v1 -- kind Hoge --defaulting --programmatic-validation
- 5. 実装するべきは 5 1. api/<ver.>/<kind>_types.go l CRD に相当する type を書く．これをベースに CRD manifest が?成される 2. controllers/<kind>_controller.go l Reconcile 関数にロジックを書く 3. api/<ver.>/<kind>_webhook.go l Defaulting/Validating Webhook を書く 4. main.go l 起動処理を書く
- 7. Demo: Scaffolding Type & Webhook 7
- 8. Following contents 8 ▌How to implement l Reconciler l Webhook l main.go ▌How to deploy ▌How to test
- 9. How to implement: Reconciler 9
- 10. Reconciler basics 10 1. リソースの取得 2. 遷移先状態の決定 3. リソースの操作 Get List request Modify Update Patch Create result
- 11. Client を使ったリソース取得?操作 11 ▌Reader: Get, List l Get は NamespacedName で?意にマッチ l List は label, namespace などでマッチ ▌Writer: Create, Delete, Update, Patch l Update は楽観ロックで動作．操作時に現状態が変わっていると失敗 l Patch はマージ可能であれば現状態が変わっていても成功 https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client
- 12. func Reconcile の戻り値 12 ▌戻り値で Requeue の制御が?える l Result: requeue するか否か＆いつ requeue するか l error: non-nil だと requeue される ▌他のコントローラーによる処理などを待つ必要がある場合に 利?できる
- 13. Reconciler コードサンプル 13 1. Custom Resource (LogicalVolume) を List 2. DeletionTimestamp から?定時間経過したかを確認 3. Finalizer を消す Patch を作成?適? 4. (必要なら) RBAC の Marker を書く https://github.com/cybozu- go/topolvm/blob/master/controller/controllers/logicalvolume_controller.go
- 14. How to implement: Webhook 14
- 15. Admission webhook ▌リソースの操作 (作成?変更?削除) 時に独?に作成した webhook にコールバックをかける仕組み l 編集 (mutating)，検証 (validating) ができる 出展?https://kubernetes.io/blog/2019/03/21/a-guide-to-kubernetes-admission-controllers/ 15
- 16. Admission Webhook 16 ▌Defaulting Webhook l Mutating Webhook の?種 l レシーバを操作することで，値を設定できる https://github.com/kfyharukz/kubebuilder-tutorial/blob/master/api/v1/cronjob_webhook.go
- 17. Admission Webhook 17 ▌Validating Webhook l レシーバの中?を確認して，validation を?う l Allowed なら nil，Denied なら error を返す https://github.com/kfyharukz/kubebuilder-tutorial/blob/master/api/v1/cronjob_webhook.go
- 18. How to implement: main.go 18 ▌scaffold されたファイルに追加するのは 2 ?のみ l 作成した type を Scheme に追加 l 上記 Scheme を Reconciler 作成時に渡す https://github.com/kfyharukz/kubebuilder-tutorial/blob/master/main.go
- 20. How to deploy 20 ▌CRD ▌RBAC l _controller.go/_webhook.go の Marker から?成 ▌Mutating/ValidatingWebhookConfiguration ▌Service l webhook の callback エンドポイント ▌Certificate l cert-manager を使って webhook ?の証明書を作成 ▌Deployment l controller(manager) 本体．コンテナイメージ名の扱いには注意 https://github.com/kfyharukz/kubebuilder-tutorial/tree/master/config
- 21. How to test 21 ▌envtest パッケージを使ってテストできる l 公式?順でインストールすると /usr/local/kubebuilder/bin に kube-apiserver と etcd の バイナリがインストールされる l 実際に kube-apiserver と通信しながらテストできる環境 が作れる https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest Scaffold の サポートはほぼない…
- 23. Diagram: controller-runtime Custom Resource Reconciler Custom Resource Webhook SchemeClient Index Cache Custom Resouce Types kube-apiserver Event Recorder (Existing Types) Runnables (Controllers &Webhooks) register add use for serialize/deserialize 23https://godoc.org/sigs.k8s.io/controller-runtime conroller-runtime.Manager これを実装
- 24. How to test: Reconciler 24 1. envtest で api-server & etcd を実? (?動?成) 2. manager & reconciler のセットアップ l main.go でやっていることと同じ?順でセットアップ可能 3. k8s client を使って操作，結果確認 l API リソースの CRUD 操作に対し，Eventually に期待する状態に到達することを チェックする https://github.com/kfyharukz/kubebuilder-tutorial/blob/master/controllers/cronjob_controller_test.go
- 25. How to test: Webhook 25 1. envtest で api-server & etcd を実? (?動?成) l api-server の起動オプションを変更 2. manager & webhook のセットアップ l 別途?意した証明書を読み込ませる l webhook サーバの起動を待つ 3. apiserver に WebhookConfiguration を apply l ?成された manifest をベースに使う l CA 証明書，及びコールバック先を変更 4. k8s client を使って Create，結果確認 l Allowed/Denied やエラー内容，作成されたリソースをチェック https://github.com/kfyharukz/kubebuilder-tutorial/blob/master/controllers/cronjob_webhook_test.go
- 26. How to implement: Webhook (Advanced) 26 ▌kubebuilder の?成する Defaulting/Validating の枠 組みだけでは出来ないことがある l 既存リソース (corev1 等) の Admission Webhook l 対象リソース以外の状態を踏まえた Mutation/Validation キャッシュやらプロセスの管理は ?倒だから controller-runtime に任せたい…
- 27. How to implement: Webhook (Advanced) 27 ▌Defaulting/Validating の実装 は以下を 2 つからなる l <type>_webhook.go を Handle 関数に落とし込むコード l Handle 関数を組み込んだ Webhook を?成するコード // builder はこの関数を呼ぶことで Webhook を作る func ValidatingWebhookFor(validator Validator) *Webhook { return &Webhook{ Handler: &validatingHandler{validator: validator}, } } type validatingHandler struct { validator Validator decoder *Decoder } func (h *validatingHandler) InjectDecoder(d *Decoder) erro r {…} // Webhook で実際に呼ばれる処理 func (h *validatingHandler) Handle(ctx context.Context, re q Request) Response {…} https://github.com/kubernetes-sigs/controller- runtime/blob/master/pkg/webhook/admission/validator.go admission.Handle を実装＆Webhook インスタンスを ?成してやれば良い https://github.com/cybozu- go/topolvm/tree/master/hook
- 28. kubebuilder v1 vs v2 ▌go modules のサポート ▌webhook 実装の scaffolding ▌webhook ?証明書管理の削除 /WebhookConfig を外部リソー ス化 l cert-manager をデフォルトに l manifests の scaffolding をサポート ▌manager を StatefulSet でなく Deployment に変更 l ConfigMap による Leader Election がデフォルト有効になったため ▌Test scaffolding の再考(#920) 28 v1->v2 のマイグレーションは…? ロジックだけコピペ?
- 29. Thank you for listening. 29
- 30. Appendix 30
- 31. 3131
- 32. controller-runtime?s components ▌Managers l controller/webhook の実?管理 l cache や client などの共通要素を inject l leader election 管理 ▌Controllers l 各種ソースから event を受信 l event を適切にフィルタリング l ?同期に reconcile 処理を呼ぶ ▌Reconcilers l controller のロジック実装部 l 対象の NamespacedName を受け 取って処理 ▌Clients and Caches l APIオブジェクトのクライアント l 透過キャッシュ＆インデクシング機 能あり ▌Scheme l Go types と API GVK の紐付け， 相互変換 32 https://godoc.org/sigs.k8s.io/controller-runtime
- 33. controller-runtime?s components ▌Webhooks l 対象のAPIコール時に validation/mutation l manager がサーバを管理 l (後ほど詳述) ▌Testing l envtest パッケージでテスト?環境 (etcdとapi-server) を提供 l ginkgo 等でテストがかける l (後ほど詳述) 33 https://godoc.org/sigs.k8s.io/controller-runtime
- 34. Webhook: Deep Dive 34 ▌admission.Response には builder が複数種?意されている https://godoc.org/sigs.k8s.io/controller- runtime/pkg/webhook/admission#Response func Allowed(reason string) Response {} func Denied(reason string) Response {} func Patched(reason string, patches ...jsonpatch.JsonPatchOperation) Response {} func Errored(code int32, err error) Response {} func ValidationResponse(allowed bool, reason string) Response {} func PatchResponseFromRaw(original, current []byte) Response {}
- 35. Scaffold: Webhook Config # v2 から manifest として?成される # 証明書は cert-manager 利?をベースとしている apiVersion: admissionregistration.k8s.io/v1b eta1 kind: MutatingWebhookConfiguration metadata: annotations: certmanager.k8s.io/inject-ca- from: kubebuilder-tutorial- system/kubebuilder-tutorial-serving-cert creationTimestamp: null name: kubebuilder-tutorial-mutating- webhook-configuration namespace: kubebuilder-tutorial-system webhooks: - clientConfig: caBundle: Cg== service: name: kubebuilder-tutorial-webhook- service namespace: kubebuilder-tutorial-system path: /mutate-batch-tutorial- kubebuilder-io-v1-cronjob failurePolicy: Fail name: mcronjob.kb.io rules: # .go の Marker が反映される - apiGroups: - batch.tutorial.kubebuilder.io apiVersions: - v1 operations: - CREATE - UPDATE resources: - cronjobs 35
- 36. How to test: Reconciler ▌v1 ではすぐに使えるテストコードが?成される l envtest パッケージを使ったテスト?の api-server を実? l テスト対象の Reconciler の受信 request に probe を 仕込む関数を?意 l Tutorial (Cronjob) のサンプルコードも?成される ▌v2 ではテストのやり?を考え中の模様 (#920) l probe を仕込む意味はあるのか (event と request は 1:1 対応ではない) lサンプルはある 36