云原生小技巧 : 如何在本地調(diào)試 Kubernetes Webhook？
如果你是一名 Kubernetes Operator 的開發(fā)者，你曾經(jīng)是否面臨過這樣一個棘手的問題：如何在本地環(huán)境中高效地調(diào)試 Webhook，尤其是在涉及有效證書回調(diào)的情況下。這篇文章旨在提供一種清晰的指南，幫助你克服這一挑戰(zhàn)，優(yōu)化本地開發(fā)和測試流程。
為什么本地調(diào)試 Webhook 如此重要？
當(dāng)我們初步涉足 Kubernetes Webhook 時，面對的首個挑戰(zhàn)通常是 Validation Webhook。對于這種驗證型 Webhook 來說，我們可以通過編寫自動化測試來驗證其功能。
這不僅確保了我的 Webhook 按預(yù)期工作，還允許我在日常開發(fā)中臨時禁用它，從而加快了整個開發(fā)過程。這種方法讓我能夠巧妙地避免復(fù)雜的調(diào)試問題，而不對整體功能造成任何影響。
if os.Getenv("ENABLE_WEBHOOKS") != "false" {
if err = (&webappv1.Guestbook{}).SetupWebhookWithManager(mgr); err != nil {
setupLog.Error(err, "unable to create webhook", "webhook", "Guestbook")
os.Exit(1)
}
}然而，對于 Mutating Webhook 來說，情況就變得有點復(fù)雜了。這類 Webhook 通常負(fù)責(zé)埋點的行為甚至更深層次的集群操作，比如注入 sidecar，這時候單靠自動化測試顯然是不夠的。我們需要一個更加高效的本地測試和調(diào)試方法。
在我們團(tuán)隊中，有同事采用 Kind 來部署和測試服務(wù)，這種方法非常值得稱贊。它完全符合 K8s 的操作模式，為我們提供了一個接近生產(chǎn)環(huán)境的本地測試平臺。但是，大家可能也注意到了，這種方式存在一個效率瓶頸：每次進(jìn)行代碼更改后，都需要重新構(gòu)建 Docker 鏡像并部署到集群中，這一過程既耗時又影響開發(fā)流程的連貫性。
作為開發(fā)工程師，我們渴望的是一個極速的內(nèi)部開發(fā)循環(huán)，一個不再需要頻繁的 docker build、docker push 或繁瑣的部署流程，即使這些已經(jīng)完全自動化。
我們希望能夠使用本地熟悉的開發(fā)工具，如 VS Code 或者 IntelliJ IDEA 進(jìn)行本地調(diào)試，而不是先部署到集群環(huán)境，再通過日志來分析錯誤這種遠(yuǎn)程調(diào)試模式。
從 Service 到 URL 的魔法變換
在不禁用 Webhook 的情況下，我們在本地啟動 controller 后會有如下錯誤。這個比較好處理，我們只要使用自簽證書，注入到 WebhookServer 即可，在前面的文章中我介紹過很多次，這里不再贅述。
2023-11-26T12:55:17+08:00 INFO Stopping and waiting for webhooks
...
2023-11-26T12:55:17+08:00 INFO Wait completed, proceeding to shutdown the manager
2023-11-26T12:55:17+08:00 ERROR setup problem running manager
{"error": "open /var/folders/hn/v2s5bx...00000gn/T/k8s-webhook-server/serving-certs/tls.crt:
no such file or directory"}
...我們來運行一個示例，想必下面這個錯誤大家都非常熟悉吧，這個是因為 Webhook 注冊的地址'不對'，它是集群內(nèi)的地址。
? kubectl apply -f ./config/samples
Error from server (InternalError): error when creating "config/samples/webapp_v1_guestbook.yaml":
Internal error occurred: failed calling webhook "vguestbook.kb.io": failed to call webhook:
Post "https://testing-webhooks-webhook-service.testing-webhooks-system.svc:443/validate-webapp-foobar-ai-v1-guestbook?timeout=10s":
no endpoints available for service "testing-webhooks-webhook-service"我們再來看下 ValidatingWebhookConfiguration 的配置。
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: testing-webhooks-validating-webhook-configuration
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
service:
name: testing-webhooks-webhook-service
namespace: testing-webhooks-system
path: /validate-webapp-foobar-ai-v1-guestbook
port: 443
failurePolicy: Fail
matchPolicy: Equivalent
name: vguestbook.kb.io
rules:
- ...
...在這個配置中，webhooks 字段定義了一個或多個要注冊的 Webhook。每個 Webhook 通過 clientConfig 配置與 Kubernetes API 服務(wù)器的連接方式。
正如大家所看到的 https://testing-webhooks-webhook-service.testing-webhooks-system.svc:443/validate-webapp-foobar-ai-v1-guestbook，這個默認(rèn)地址其實就是 K8s 集群內(nèi)部的地址。這恰是 K8s 中處理 Webhook 的常規(guī)方法，其中 service 字段指向集群內(nèi)運行的特定服務(wù)。
然而，在本地開發(fā)環(huán)境中，我們只在本地運行了我們的 Operator，直接使用內(nèi)部服務(wù)是不大可能的，因為它要求 Webhook 服務(wù)必須部署在 K8s 集群中。
使用 kubectl explain 探索 Webhook 配置
當(dāng)我們在 K8s 中配置 Webhook 時，了解其配置細(xì)節(jié)是非常重要的。kubectl explain 是一個非常實用的小工具，它可以幫助我們深入理解 K8s 資源的各個屬性。
以 ValidatingWebhookConfiguration.webhooks.clientConfig 為例：
? kubectl explain ValidatingWebhookConfiguration.webhooks.clientConfig
GROUP: admissionregistration.k8s.io
KIND: ValidatingWebhookConfiguration
VERSION: v1
FIELD: clientConfig <WebhookClientConfig>:
DESCRIPTION:
FIELDS:
caBundle <string>
`caBundle` is a PEM encoded CA bundle which will be used to validate the
webhook's server certificate. If unspecified, system trust roots on the
apiserver are used.
service <ServiceReference>
`service` is a reference to the service for this webhook. Either `service`
or `url` must be specified.
If the webhook is running within the cluster, then you should use `service`.
url <string>
`url` gives the location of the webhook, in standard URL form
(`scheme://host:port/path`). Exactly one of `url` or `service` must be
specified.通過以上提供的詳細(xì)信息，不難發(fā)現(xiàn) clientConfig 它除了通過定義 Service 讓 API 服務(wù)器連接到 WebhookServer 外，還有另外一種方式，那就是直接通過 URL 連接。
為了解決這個問題，我們可以將 Webhook 的配置從服務(wù)轉(zhuǎn)變?yōu)橹苯邮褂?URL。
使用 URL 連接 Webhook
通過將 clientConfig 中的 service 字段替換為 url 字段，我們可以指定 Webhook 服務(wù)的外部 URL。這樣一來，開發(fā)者可以在本地運行 Webhook 服務(wù)，并通過公開的 URL 使其可被 Kubernetes API 服務(wù)器訪問。
例如：
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
url: https://testing-webhooks.loca.lt/validate-webapp-foobar-ai-v1-guestbook這種方法使得在本地開發(fā)環(huán)境中調(diào)試 Webhook 變得更加靈活和便捷。開發(fā)者可以使用本地服務(wù)器或通過隧道（如 ngrok[1] 或 localtunnel[2]）暴露的服務(wù)，從而實現(xiàn)在本地環(huán)境中的有效調(diào)試。
事實上，我最初的首選是 ngrok，因為這玩意確實好用，它還有個 localhost:4040 非常的實用，但遺憾的是，它的 tls 能力是付費的。幸好，有很多平替工具可以選擇，比如 localtunnel，用起來也非常的方便。
步驟 1: 在我們的 main.go 需要接收一個證書路徑
...
var certDir string
flag.StringVar(&certDir, "webhook-cert-dir", "/tmp/k8s-webhook-server/serving-certs", "Admission webhook cert/key dir.")
...
mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
Scheme: scheme,
Metrics: metricsserver.Options{BindAddress: metricsAddr},
HealthProbeBindAddress: probeAddr,
WebhookServer: webhook.NewServer(webhook.Options{
CertDir: certDir,
Port: 9443,
}),
LeaderElection: enableLeaderElection,
LeaderElectionID: "dcc993a0.foobar.ai",
})
...步驟 2：調(diào)整 Makefile，并啟動我們的程序
修改 Makefile 文件，讓其可以接收證書目錄：
.PHONY: run
run: manifests generate fmt vet ## Run a controller from your host.
go run ./cmd/main.go --webhook-cert-dir ./config/certs啟動程序：
? make run
...
go run ./cmd/main.go --webhook-cert-dir ./config/certs
2023-11-26T11:18:42+08:00 INFO controller-runtime.builder Registering a mutating webhook {"GVK": "webapp.foobar.ai/v1, Kind=Guestbook", "path": "/mutate-webapp-foobar-ai-v1-guestbook"}
2023-11-26T11:18:42+08:00 INFO controller-runtime.webhook Registering webhook {"path": "/mutate-webapp-foobar-ai-v1-guestbook"}
2023-11-26T11:18:42+08:00 INFO controller-runtime.builder Registering a validating webhook {"GVK": "webapp.foobar.ai/v1, Kind=Guestbook", "path": "/validate-webapp-foobar-ai-v1-guestbook"}
2023-11-26T11:18:42+08:00 INFO controller-runtime.webhook Registering webhook {"path": "/validate-webapp-foobar-ai-v1-guestbook"}
...
2023-11-26T11:18:42+08:00 INFO controller-runtime.webhook Starting webhook server
...
2023-11-26T11:18:42+08:00 INFO controller-runtime.webhook Serving webhook server {"host": "", "port": 9443}
...步驟 3：將本地主機服務(wù)器通過隧道公開
# 安裝
npm install -g localtunnel
# 使用 lt 命令啟動隧道
lt --port 9443 \
--local-https \
--local-ca $(pwd)/certs/ca.crt \
--local-cert $(pwd)/certs/tls.crt \
--local-key $(pwd)/certs/tls.key \
--subdomain testing-webhooks
your url is: https://testing-webhooks.loca.lt步驟 4：修改 ValidatingWebhookConfiguration 配置
我們將默認(rèn)的 service 服務(wù)。
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
service:
name: testing-webhooks-webhook-service
namespace: testing-webhooks-system
path: /validate-webapp-foobar-ai-v1-guestbook
port: 443
...替換換成 url 直連模式
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
url: https://testing-webhooks.loca.lt/validate-webapp-foobar-ai-v1-guestbook
...以上僅以 ValidatingWebhookConfiguration 為例，如果你的 controller 同時使用了 MutatingWebhookConfiguration，別忘了，處理方式是一樣的。
步驟 5：看看實際效果如何
最后，我們再執(zhí)行同樣一個用例，就可以被當(dāng)前的 ValidatingWebhook 攔截到了。
? kubectl apply -f ./config/samples/webapp_v1_guestbook.yaml
The Guestbook "guestbook-sample" is invalid: metadata.name: Invalid value: "guestbook-sample":
Guestbook name must be no more than 5 characters for test purposes?? 小貼士：對于那些出于安全考慮不愿將本地服務(wù)暴露在公網(wǎng)上的小伙伴們，這里有一個安全的替代方案。你可以使用如 docker.for.mac.host.internal 這樣的特定域名，它允許在不同環(huán)境下安全地連接到你的主機。
為了實現(xiàn)這一點，你需要根據(jù)你所在的環(huán)境，將 docker.for.mac.host.internal 替換為能夠訪問到你本地主機的相應(yīng)域名。此外，別忘了補充 caBundle 字段，確保使用了正確的 CA 證書的 base64 編碼字符串。
示例配置如下所示：
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
caBundle: [你的CA證書的base64編碼字符串]
url: https://docker.for.mac.host.internal:9443/validate-webapp-foobar-ai-v1-guestbook當(dāng)然，在實際開發(fā)中，手動更改 Webhook 配置顯然不是理想選擇。推薦大家根據(jù)項目需求，結(jié)合這里提供的策略，開發(fā)自動化的配置處理流程。這不僅提升效率，還確保了配置的準(zhǔn)確性和項目的靈活性。
Debugging operator on Kubernetes
在以前的舊文中，我分享過 《Kubernetes 101: Debugging Microservices on Kubernetes》 這篇文章，主要介紹微服務(wù)在 K8s 環(huán)境下，在本地如何進(jìn)行有效的調(diào)試。事實上，我們當(dāng)前 webhook 的調(diào)試場景，完全可以利用 Nocalhost[3] 這款工具達(dá)到同樣的目的。
圖片
在 Nocalhost 的開發(fā)模式下，我們可以直接在 K8s 集群中構(gòu)建、測試和調(diào)試應(yīng)用程序的，這意味著我們可以默認(rèn)使用 clientConfig.service 模式，直接通過內(nèi)部服務(wù)來連接，非常的方便。如果你還不太熟悉 Nocalhost，那可得抓緊時間補課了 ??
至于證書，我們自然是選擇 cert-manager 來管理 admission webhooks 證書了，畢竟我們已經(jīng)在集群里運行了，沒有比它更方便的了。
我在 github 上寫了個 chart，感興趣的可以了解下：https://github.com/lqshow/testing-webhooks
寫在最后
在本文中，我們深入了解了 Kubernetes Webhook 的本地調(diào)試流程，從基礎(chǔ)理解到實際操作。通過將傳統(tǒng)的基于服務(wù)的配置方式轉(zhuǎn)變?yōu)橹苯邮褂?URL，我們不僅克服了本地調(diào)試的局限性，還引入了前所未有的靈活性和效率，大幅優(yōu)化了整個開發(fā)周期。
此外，我們還探討了如何在更廣泛的 Kubernetes 生態(tài)中應(yīng)用 Nocalhost 和 cert-manager。這些工具的整合不僅簡化了開發(fā)和調(diào)試過程，還強化了安全性和可擴展性。通過實際案例，我們展示了如何在云原生環(huán)境中靈活地應(yīng)對挑戰(zhàn)，從而提升整體開發(fā)效率。
