Kubernetes API 編程利器：Operator 和 Operator Framework

本節課程主要分享以下三方面的內容：

1. operator 概述
2. operator framework 實戰
3. 工作流程

operator 概述#

基本概念#

首先介紹一下本節所涉及到的基本概念。

• CRD (Custom Resource Definition)：允許用戶自定義 Kubernetes 資源，是一個類型；
• CR (Custom Resourse)：CRD 的一個具體實例；
• webhook：它本質上是一種 HTTP 回調，會註冊到 apiserver 上。在 apiserver 特定事件發生時，會查詢已註冊的 webhook，並把相應的消息轉發過去。

按照處理類型的不同，一般可以將其分為兩類：一類可能會修改傳入對象，稱為 mutating webhook；一類則會只讀傳入對象，稱為 validating webhook。

• 工作隊列：controller 的核心組件。它會監控集群內的資源變化，並把相關的對象，包括它的動作與 key，例如 Pod 的一個 Create 動作，作為一個事件存儲於該隊列中；
• controller：它會循環地處理上述工作隊列，按照各自的邏輯把集群狀態向預期狀態推動。不同的 controller 處理的類型不同，比如 replicaset controller 關注的是副本數，會處理一些 Pod 相關的事件；
• operator：operator 是描述、部署和管理 kubernetes 應用的一套機制，從實現上來說，可以將其理解為 CRD 配合可選的 webhook 與 controller 來實現用戶業務邏輯，即 operator = CRD + webhook + controller。

常見的 operator 工作模式#

工作流程：

1. 用戶創建一個自定義資源 (CRD)；
2. apiserver 根據自己註冊的一個 pass 列表，把該 CRD 的請求轉發給 webhook；
3. webhook 一般會完成該 CRD 的缺省值設定和參數檢驗。webhook 處理完之後，相應的 CR 會被寫入數據庫，返回給用戶；
4. 與此同時，controller 會在後臺監測該自定義資源，按照業務邏輯，處理與該自定義資源相關聯的特殊操作；
5. 上述處理一般會引起集群內的狀態變化，controller 會監測這些關聯的變化，把這些變化記錄到 CRD 的狀態中。

這裡是從 High-Level 大概介紹一下，後面會結合案例重新梳理。

operator framework 實戰#

operator framework 概述#

在開始之前，首先介紹一下 operator framework。它實際上給用戶提供了 webhook 和 controller 的框架，它的主要意義在於幫助開發者屏蔽了一些通用的底層細節，不需要開發者再去實現消息通知觸發、失敗重新入隊等，只需關注被管理應用的運維邏輯實現即可。

主流的 operator framework 主要有兩個：kubebuilder 和 operator-sdk。

兩者實際上並沒有本質的區別，它們的核心都是使用官方的 controller-tools 和 controller-runtime。不過細節上稍有不同，比如 kubebuilder 有著更為完善的測試與部署以及代碼生成的腳手架等；而 operator-sdk 對 ansible operator 這類上層操作的支持更好一些。

kuberbuildere 實戰#

這裡的實戰選用的是 kuberbuilder。案例選用的是阿里雲對外開放的 kruise 項目下的 SidercarSet。

SidercarSet 的功能就是負責給 Pod 插入 sidecar 容器（也稱為輔助容器），例如可以插入一些監控，日誌採集來豐富這個 Pod 的功能，然後根據插入的狀態、Pod 的狀態反過來更新 SidercarSet 以記錄這些輔助容器的狀態。

Step 1：初始化

操作：

新建一個 GitLab 項目，運行

<code>Copykubebuilder init --domain=kruise.io
/<code>

參數解讀：

domain 指定了後續註冊 CRD 對象的 Group 域名。

效果解讀：

拉取依賴代碼庫、生成代碼框架、生成 Makefile/Dockerfile 等工具文件。

我們來看一下它具體生成的內容（為了方便演示，實際生成文件做了部分刪減）：

具體的內容大家可以在實戰的時候自己進行詳細的確認。

Step 2：創建 API

操作：

運行

<code>Copykubebuilder create api --group apps --version v1alpha1 --kind SidecarSet --namespace=false
/<code>

實際上不僅會創建 API，也就是 CRD，還會生成 Controller 的框架。

參數解讀：

• group 加上之前的 domian 即此 CRD 的 Group: apps.kruise.io；
• version 一般分三種，按社區標準：v1alpha1：此 API 不穩定，CRD 可能廢棄、字段可能隨時調整，不要依賴；v1beta1：API 已穩定，會保證向後兼容，特性可能會調整；v1：API 和特性都已穩定；
• kind：此 CRD 的類型，類似於社區原生的 Service 的概念；
• namespaced：此 CRD 是全局唯一還是 namespace 唯一，類似 node 和 Pod。

它的參數基本可以分為兩類。group、version、kind 基本上對應了 CRD 元信息的三個重要組成部分。這裡給出了一些常見的標準，大家實際使用的時候可以參考一下。namespaced 則用於指定我們剛剛創建的 CRD 時全局唯一的（如 node）還是 namespace 唯一的（如 Pod）。這裡用了 false，即指定 SidecarSet 為全局唯一的。

效果解讀：

生成了 CRD 和 controller 的框架，後面需要手工填充代碼。

實際結果如下圖所示：

我們重點關注是圖中藍色字體部分。sidecarset_types.go 就是定義 CRD 的地方，需要我們填充。sidecarset*controller.go 則用於定義 controller，同樣需要進行填充。

Step 3：填充 CRD

1. 生成的 CRD 位於 pkg/apis/apps/v1alpha1/sidecarset_types.go，通常需要進行如下兩個操作：

(1) 調整註釋

code generator 依賴註釋生成代碼，因此有時需要調整註釋。以下列出了本次實戰中 SidecarSet 需要調整的註釋：

• +genclient:nonNamespaced：生成非 namespace 對象；
• +kubebuilder:subresource:status：生成 status 子資源；
• +kubebuilder:printcolumn:name="MATCHED",type='integer',JSONPath=".status.matchedPods",description="xxx": kubectl get sidecarset：後續展示相關。

(2) 填充字段

填充字段是令用戶的 CRD 實際生效、實際有意義的重要部分。

• SidecarSetSpec：填充 CRD 描述信息；
• SidecarSetStatus：填充 CRD 狀態信息。

2. 填充完運行 make 重新生成代碼即可

需要注意的是，研發人員無需參與 CRD 的 grpc 接口、編解碼等 controller 的底層實現。

實際的填充如下圖所示：

SidecarSet 的功能是給 Pod 注入 Sidecar，為了完成該功能，我們在 SidecarSetSpec（左圖） 定義了兩個主要信息：一個是用於選擇哪些 Pod 需要被注入的 Selector；一個是定義 Sidecar 容器的 Containers。

在 SidecarSetStatus（右圖）中定義了狀態信息，MatchedPods 反映的是該 SidecarSet 實際匹配了多少 Pod，UpdatedPods 反映的是已經注入了多少，ReadyPods 反映的則是有多少 Pod 已經正常工作了。

完整的內容可以參考 (https://github.com/openkruise/kruise)。

Step 4：生成 webhook 框架

1. 生成 mutating webhook，運行：

<code>Copykubebuilder alpha webhook --group apps --version v1alpha1 --kind SidecarSet --type=mutating --operations=create
kubebuilder alpha webhook --group core --version v1 --kind Pod --type=mutating --operations=create
/<code>

2. 生成 validating webhook，運行：

<code>Copykubebuilder alpha webhook --group apps --version v1alpha1 --kind SidecarSet --type=validating --operations=create,update
/<code>

參數解讀：

• group/kind 描述需要處理的資源對象；
• type 描述需要生成哪種類型的框架；
• operations 描述關注資源對象的哪些操作。

效果解讀：

• 生成了 webhook 框架，後面需要手工填充代碼。

實際生成結果如下圖所示：

我們執行了三條命令，分別生成了三個不同的需要填充的 handler 中（上圖藍色字體部分）。這裡先不提，在下一步填充操作中再對其詳細講解。

Step 5：填充 webhook

生成的 webhook handler 分別位於：

• - pkg/webhook/default_server/sidecarset/mutating/xxx_handler.go
• - pkg/webhook/default_server/sidecarset/validating/xxx_handler.go
• - pkg/webhook/default_server/pod/mutating/xxx_handler.go

需要改寫、填充的一般包括以下兩個部分：

• 是否需要注入 K8s client：取決於除了傳入的 CRD 以外是否還需要其它資源。在本實戰中，不僅要關注 SidecarSet，同時還要注入 Pod，因此需要注入 K8s client；
• 填充 webhook 的關鍵方法：即 mutatingSidecarSetFn 或 validatingSidecarSetFn。由於待操作資源對象指針已經傳入，因此直接調整該對象屬性即可完成 hook 的工作。

我們來看一下實際的填充結果。

因為第四步我們定義了三個：sidecarset mutating、sidecarset mutaing、pod mutating。

先來看上圖左側的 sidecarset mutating，首先是 setDefaultSidecarSet 把默認值設置好，這也是 mutaing 最常做的事情。

上圖右側 validating 也是非常的標準，也是對 SidecarSet 一些字段進行校驗。

關於 pod mutaing 這裡沒有做展示，這裡面有些不同，這裡面的 mutaingSidecarSetFn 不是進行默認值設置，而是獲取 setDefaultSidecarSet 的數值，然後注入到 Pod 裡面。

Step 6：填充 controller

生成的 controller 框架位於 pkg/controller/sidecarset/sidecarset_controller.go。主要有三點需要進行修改：

• 修改權限註釋。框架會自動生成形如 //+kuberbuilder:rbac;groups=apps,resources=deployments/status,verbs=get;update;path 的註釋，我們可以按照自己的需求修改，該註釋最終會生成 rbac 規則；
• 增加入隊邏輯。缺省的代碼框架會填充 CRD 本身的入隊邏輯（如 SidecarSet 對象的增刪改都會加入工作隊列），如果需要關聯資源對象的觸發機制（如 SidecarSet 也需關注 Pod 的變化），則需手工新增它的入隊邏輯；
• 填充業務邏輯。修改 Reconcile 函數，循環處理工作隊列。Reconcile 函數主要完成「根據 Spec 完成業務邏輯」和「將業務邏輯結果反饋回 status」兩部分。需要注意的是，如果 Reconcile 函數出錯返回 err，默認會重新入隊。

我們來看一下 SidecarSet 的 Controller 的填充結果：

addPod 中先取回該 Pod 對應的 SidecarSet 並將其加入隊列以便 Reconcile 進行處理。

Reconcile 將 SidercarSet 取出之後，根據 Selector 選擇匹配的 Pod，最後根據 Pod 當前的狀態信息計算出集群的狀態，然後回填到 CRD 的狀態中。

SidecarSet 的工作流程#

最後我們再來重新梳理一下 SidecarSet 的工作流程以便我們理解 operator 是如何工作的。

1. 用戶創建一個 SidecarSet；
2. webhook 收到該 SidecarSet 之後，會進行缺省值設置和配置項校驗。這兩個操作完成之後，會完成真正的入庫，並返回給用戶；
3. 用戶創建一個 Pod；
4. webhook 會拿回對應的 SidecarSet，並從中取出 container 注入 Pod 中，因此 Pod 在實際入庫時就已帶有了剛剛的 sidecar；
5. controller 在後臺不停地輪詢，查看集群的狀態變化。第 4 步中的注入會觸發 SidecarSet 的入隊，controller 就會令 SidecarSet 的 UpdatedPods 加 1。

以上就是 SidecarSet 前期一個簡單的功能實現。

這裡我們再補充一個問題。一般的 webhook 由 controller 來完成業務邏輯、狀態更新，但這個不是一定的，兩者之一可以不是必須的。在以上的示例中就是由 webhook 完成主要的業務邏輯，無需 controller 的參與。

本節總結#

本節課的主要內容就到此為止了，這裡為大家簡單總結一下：

• Operator 是 CRD 配合 可選的 webhook 和 controller，在 Kubernetes 體系下擴展用戶業務邏輯的一套機制；
• kubebuilder 是社區認可度很高的一種官方、標準化 Operator 框架；
• 按照上文實戰步驟，填充用戶自定義代碼，就可以很方便的實現一個 Operator。