![頭圖.png](https://ucc.alicdn.com/pic/developer-ecology/d00247fa43e44091952baed8d2215ae3.png)

作者 | 酒祝  阿里雲技術專家

# 背景

[OpenKruise](https://github.com/openkruise/kruise) 是阿里雲開源的大規模應用自動化管理引擎，在功能上對標了 Kubernetes 原生的 Deployment / StatefulSet 等控制器，但 OpenKruise 提供了更多的增強功能如：優雅原地升級、釋出優先順序/打散策略、多可用區workload抽象管理、統一 sidecar 容器注入管理等，都是經歷了阿里巴巴超大規模應用場景打磨出的核心能力。這些 feature 幫助我們應對更加多樣化的部署環境和需求、為叢集維護者和應用開發者帶來更加靈活的部署釋出組合策略。

目前在阿里巴巴內部雲原生環境中，絕大部分應用都統一使用 OpenKruise 的能力做 Pod 部署、釋出管理，而不少業界公司和阿里雲上客戶由於 K8s 原生 Deployment 等負載不能完全滿足需求，也轉而採用 OpenKruise 作為應用部署載體。

今天的分享文章就從一個阿里雲上客戶對接 OpenKruise 的疑問開始。這裡還原一下這位同學的用法（以下 YAML 資料僅為 demo）：

1. 準備一份 Advanced StatefulSet 的 YAML 檔案，並提交建立。如：

```yaml
apiVersion: apps.kruise.io/v1alpha1
kind: StatefulSet
metadata:
  name: sample
spec:
  # ...
  template:
    # ...
    spec:
      containers:
        - name: main
          image: nginx:alpine
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      podUpdatePolicy: InPlaceIfPossible
```

2. 然後，修改了 YAML 中的 image 映象版本，然後呼叫 K8s api 介面做更新。結果收到報錯如下：

```shell
metadata.resourceVersion: Invalid value: 0x0: must be specified for an update
```

3. 而如果使用 kubectl apply 命令做更新，則返回成功：

```shell
statefulset.apps.kruise.io/sample configured
```

**問題在於，為什麼同一份修改後的 YAML 檔案，呼叫 api 介面更新是失敗的，而用 kubectl apply 更新是成功的呢？**這其實並不是 OpenKruise 有什麼特殊校驗，而是由 K8s 自身的更新機制所決定的。

從我們的接觸來看，絕大多數使用者都有透過 kubectl 命令或是 sdk 來更新 K8s 資源的經驗，但真正理解這些更新操作背後原理的人卻並不多。本文將著重介紹 K8s 的資源更新機制，以及一些我們常用的更新方式是如何實現的。

# 更新原理

不知道你有沒有想過一個問題：對於一個 K8s 資源物件比如 Deployment，我們嘗試在修改其中 image 映象時，如果有其他人同時也在對這個 Deployment 做修改，會發生什麼？

當然，這裡還可以引申出兩個問題：

1. 如果雙方修改的是同一個欄位，比如 image 欄位，結果會怎樣？
2. 如果雙方修改的是不同欄位，比如一個修改 image，另一個修改 replicas，又會怎麼樣？

其實，對一個 Kubernetes 資源物件做“更新”操作，簡單來說就是通知 kube-apiserver 元件我們希望如何修改這個物件。而 K8s 為這類需求定義了兩種“通知”方式，分別是 `update` 和 `patch`。在 update 請求中，我們需要將整個修改後的物件提交給 K8s；而對於 patch 請求，我們只需要將物件中某些欄位的修改提交給 K8s。

那麼回到背景問題，為什麼使用者提交修改後的 YAML 檔案做 update 會失敗呢？這其實是被 K8s 對 update 請求的版本控制機制所限制的。

## Update 機制

Kubernetes 中的所有資源物件，都有一個全域性唯一的版本號（metadata.resourceVersion）。每個資源物件從建立開始就會有一個版本號，而後每次被修改（不管是 update 還是 patch 修改），版本號都會發生變化。

[官方文件](https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions)告訴我們，這個版本號是一個 K8s 的內部機制，使用者不應該假設它是一個數字或者透過比較兩個版本號大小來確定資源物件的新舊，唯一能做的就是透過比較版本號相等來確定物件是否是同一個版本（即是否發生了變化）。而 resourceVersion 一個重要的用處，就是來做 update 請求的版本控制。

K8s 要求使用者 update 請求中提交的物件必須帶有 resourceVersion，也就是說我們提交 update 的資料必須先來源於 K8s 中已經存在的物件。因此，一次完整的 update 操作流程是：

1. 首先，從 K8s 中拿到一個已經存在的物件（可以選擇直接從 K8s 中查詢；如果在客戶端做了 list watch，推薦從本地 informer 中獲取）；
2. 然後，基於這個取出來的物件做一些修改，比如將 Deployment 中的 replicas 做增減，或是將 image 欄位修改為一個新版本的映象；
3. 最後，將修改後的物件透過 update 請求提交給 K8s；
4. 此時，kube-apiserver 會校驗使用者 update 請求提交物件中的 resourceVersion 一定要和當前 K8s 中這個物件最新的 resourceVersion 一致，才能接受本次 update。否則，K8s 會拒絕請求，並告訴使用者發生了版本衝突（Conflict）。

![1.png](https://ucc.alicdn.com/pic/developer-ecology/c8d424b1c4424a0587209184abc8448c.png)

上圖展示了多個使用者同時 update 某一個資源物件時會發生的事情。而如果如果發生了 Conflict 衝突，對於 User A 而言應該做的就是做一次重試，再次獲取到最新版本的物件，修改後重新提交 update。

因此，我們上面的兩個問題也都得到了解答：

1. 使用者修改 YAML 後提交 update 失敗，是因為 YAML 檔案中沒有包含 resourceVersion 欄位。對於 update 請求而言，應該取出當前 K8s 中的物件做修改後提交；
2. 如果兩個使用者同時對一個資源物件做 update，不管操作的是物件中同一個欄位還是不同欄位，都存在版本控制的機制確保兩個使用者的 update 請求不會發生覆蓋。

## Patch 機制

相比於 update 的版本控制，K8s 的 patch 機制則顯得更加簡單。

當使用者對某個資源物件提交一個 patch 請求時，kube-apiserver 不會考慮版本問題，而是“無腦”地接受使用者的請求（只要請求傳送的 patch 內容合法），也就是將 patch 打到物件上、同時更新版本號。

不過，patch 的複雜點在於，目前 K8s 提供了 4 種 patch 策略：json patch、merge patch、strategic merge patch、apply patch（從 K8s 1.14 支援 server-side apply 開始）。透過 kubectl patch -h 命令我們也可以看到這個策略選項（預設採用 strategic）：

```bash
$ kubectl patch -h
# ...
  --type='strategic': The type of patch being provided; one of [json merge strategic]
```

篇幅限制這裡暫不對每個策略做詳細的介紹了，我們就以一個簡單的例子來看一下它們的差異性。如果針對一個已有的 Deployment 物件，假設 template 中已經有了一個名為 app 的容器：

1. 如果要在其中新增一個 nginx 容器，如何 patch 更新？
2. 如果要修改 app 容器的映象，如何 patch 更新？

### json patch（[RFC 6902]()）

新增容器：

```bash
kubectl patch deployment/foo --type='json' -p \
  '[{"op":"add","path":"/spec/template/spec/containers/1","value":{"name":"nginx","image":"nginx:alpine"}}]'
```

修改已有容器 image：

```bash
kubectl patch deployment/foo --type='json' -p \
  '[{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"app-image:v2"}]'
```

可以看到，在 json patch 中我們要指定操作型別，比如 add 新增還是 replace 替換，另外在修改 containers 列表時要透過元素序號來指定容器。

這樣一來，如果我們 patch 之前這個物件已經被其他人修改了，那麼我們的 patch 有可能產生非預期的後果。比如在執行 app 容器映象更新時，我們指定的序號是 0，但此時 containers 列表中第一個位置被插入了另一個容器，則更新的映象就被錯誤地插入到這個非預期的容器中。

### merge patch（[RFC 7386](https://tools.ietf.org/html/rfc7386)）

merge patch 無法單獨更新一個列表中的某個元素，因此不管我們是要在 containers 裡新增容器、還是修改已有容器的 image、env 等欄位，都要用整個 containers 列表來提交 patch：

```bash
kubectl patch deployment/foo --type='merge' -p \
  '{"spec":{"template":{"spec":{"containers":[{"name":"app","image":"app-image:v2"},{"name":"nginx","image":"nginx:alpline"}]}}}}'
```

顯然，這個策略並不適合我們對一些列表深層的欄位做更新，更適用於大片段的覆蓋更新。

不過對於 labels/annotations 這些 map 型別的元素更新，merge patch 是可以單獨指定 key-value 操作的，相比於 json patch 方便一些，寫起來也更加直觀：

```bash
kubectl patch deployment/foo --type='merge' -p '{"metadata":{"labels":{"test-key":"foo"}}}'
```

### strategic merge patch

這種 patch 策略並沒有一個通用的 RFC 標準，而是 K8s 獨有的，不過相比前兩種而言卻更為強大的。

我們先從 K8s 原始碼看起，在 K8s 原生資源的資料結構定義中額外定義了一些的策略註解。比如以下這個擷取了 podSpec 中針對 containers 列表的定義，[參考 Github](https://github.com/kubernetes/api/blob/release-1.18/core/v1/types.go#L2864)：

```go
// ...
// +patchMergeKey=name
// +patchStrategy=merge
Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" protobuf:"bytes,2,rep,name=containers"`
```

可以看到其中有兩個關鍵資訊：`patchStrategy:"merge" patchMergeKey:"name"` 。這就代表了，containers 列表使用 strategic merge patch 策略更新時，會把下面每個元素中的 name 欄位看作 key。

簡單來說，在我們 patch 更新 containers 不再需要指定下標序號了，而是指定 name 來修改，K8s 會把 name 作為 key 來計算 merge。比如針對以下的 patch 操作：

```bash
kubectl patch deployment/foo -p \
  '{"spec":{"template":{"spec":{"containers":[{"name":"nginx","image":"nginx:mainline"}]}}}}'
```

如果 K8s 發現當前 containers 中已經有名字為 nginx 的容器，則只會把 image 更新上去；而如果當前 containers 中沒有 nginx 容器，K8s 會把這個容器插入 containers 列表。

此外還要說明的是，目前 strategic 策略只能用於原生 K8s 資源以及 Aggregated API 方式的自定義資源，對於 CRD 定義的資源物件，是無法使用的。這很好理解，因為 kube-apiserver 無法得知 CRD 資源的結構和 merge 策略。如果用 kubectl patch 命令更新一個 CR，則預設會採用 merge patch 的策略來操作。

# kubectl 封裝

瞭解完了 K8s 的基礎更新機制，我們再次回到最初的問題上。為什麼使用者修改 YAML 檔案後無法直接呼叫 update 介面更新，卻可以透過 kubectl apply 命令更新呢？

其實 kubectl 為了給命令列使用者提供良好的互動體感，設計了較為複雜的內部執行邏輯，諸如 apply、edit 這些常用操作其實背後並非對應一次簡單的 update 請求。畢竟 update 是有版本控制的，如果發生了更新衝突對於普通使用者並不友好。以下簡略介紹下 kubectl 幾種更新操作的邏輯，有興趣可以看一下 [kubectl 封裝的原始碼](https://github.com/kubernetes/kubectl)。

## apply

在使用預設引數執行 apply 時，觸發的是 client-side apply。kubectl 邏輯如下：

首先解析使用者提交的資料（YAML/JSON）為一個物件 A；然後呼叫 Get 介面從 K8s 中查詢這個資源物件：

- 如果查詢結果不存在，kubectl 將本次使用者提交的資料記錄到物件 A 的 annotation 中（key 為 kubectl.kubernetes.io/last-applied-configuration），最後將物件 A提交給 K8s 建立；

- 如果查詢到 K8s 中已有這個資源，假設為物件 B：1. kubectl 嘗試從物件 B 的 annotation 中取出 kubectl.kubernetes.io/last-applied-configuration 的值（對應了上一次 apply 提交的內容）；2. kubectl 根據前一次 apply 的內容和本次 apply 的內容計算出 diff（預設為 strategic merge patch 格式，如果非原生資源則採用 merge patch）；3. 將 diff 中新增本次的 kubectl.kubernetes.io/last-applied-configuration annotation，最後用 patch 請求提交給 K8s 做更新。

這裡只是一個大致的流程梳理，真實的邏輯會更復雜一些，而從 K8s 1.14 之後也支援了 server-side apply，有興趣的同學可以看一下原始碼實現。

## edit

kubectl edit 邏輯上更簡單一些。在使用者執行命令之後，kubectl 從 K8s 中查到當前的資源物件，並開啟一個命令列編輯器（預設用 vi）為使用者提供編輯介面。

當使用者修改完成、儲存退出時，kubectl 並非直接把修改後的物件提交 update（避免 Conflict，如果使用者修改的過程中資源物件又被更新），而是會把修改後的物件和初始拿到的物件計算 diff，最後將 diff 內容用 patch 請求提交給 K8s。

# 總結

看了上述的介紹，大家應該對 K8s 更新機制有了一個初步的瞭解了。接下來想一想，既然 K8s 提供了兩種更新方式，我們在不同的場景下怎麼選擇 update 或 patch 來使用呢？這裡我們的建議是：

- 如果要更新的欄位只有我們自己會修改（比如我們有一些自定義標籤，並寫了 operator 來管理），則使用 patch 是最簡單的方式；
- 如果要更新的欄位可能會被其他方修改（比如我們修改的 replicas 欄位，可能有一些其他元件比如 HPA 也會做修改），則建議使用 update 來更新，避免出現互相覆蓋。

最終我們的客戶改為基於 get 到的物件做修改後提交 update，終於成功觸發了 Advanced StatefulSet 的原地升級。此外，我們也歡迎和鼓勵更多的同學參與到 [OpenKruise](https://github.com/openkruise/kruise) 社群中，共同合作打造一款面向規模化場景、高效能的應用交付解決方案。（歡迎加入釘釘交流群：23330762）

# 課程推薦

為了更多開發者能夠享受到 Serverless 帶來的紅利，這一次，我們集結了 10+ 位阿里巴巴 Serverless 領域技術專家，打造出最適合開發者入門的 Serverless 公開課，讓你即學即用，輕鬆擁抱雲端計算的新正規化——Serverless。

點選即可免費觀看課程：[https://developer.aliyun.com/learning/roadmap/serverless](https://developer.aliyun.com/learning/roadmap/serverless)

> “[阿里巴巴雲原生](http://mp.weixin.qq.com/s?__biz=MzUzNzYxNjAzMg==&mid=2247490783&idx=1&sn=9ae8b44605e6808d80be9d6924a140db&chksm=fae51710cd929e0653dc0b90269772280df9a201315709bc93d62c2a4cfe719a164921469b5e&token=1148911636&lang=zh_CN#rd)關注微服務、Serverless、容器、Service Mesh 等技術領域、聚焦雲原生流行技術趨勢、雲原生大規模的落地實踐，做最懂雲原生開發者的公眾號。”

理解 K8s 資源更新機制，從一個 OpenKruise 使用者疑問開始

相關文章