導語

作者李志宇，騰訊雲後臺開發工程師，日常負責叢集節點和執行時相關的工作，熟悉 containerd、docker、runc 等執行時元件。近期在為某位客戶提供技術支援過程中，遇到了 containerd 映象丟失檔案問題，經過一系列分析、推斷、復現、排查，最終成功找到根因並給出解決方案。現將整個詳細處理過程整理成文分享出來，希望能夠為大家提供一個有價值的問題處理思路以及幫助大家更好地理解相關原理。

containerd 映象丟失檔案問題說明

近期有客戶反映某些容器映象出現了檔案丟失的奇怪現象，經過模擬復現彙總出丟失情況如下：

某些特定的映象會穩定丟失檔案；

“丟失”在某些發行版穩定復現，但在 ubuntu 上不會出現；

v1.2 版本的 containerd 會檔案丟失，而 v1.3 不會。

通過閱讀原始碼和文件，最終解決了這個 containerd 映象丟失問題，並寫下了這篇文章，希望和大家分享下解決問題的經歷和映象生成的原理。為了方便某些心急的同學，本文接下來將首先揭曉該問題的答案~

根因和解決方案

由於核心 overlay 模組 Bug，當 containerd 從映象倉庫下載映象的“壓縮包”生成映象的“層”時，overlay 錯誤地把trusted.overlay.opaque=y這個 xattrs 從下層傳遞到了上層。如果某個目錄設定了這個屬性，overlay 則會認為這個目錄是不透明的，以至於在進行聯合掛載時該目錄將會把下面的目錄覆蓋掉，進而導致映象檔案丟失的問題。

這個問題的解決方案可以有兩種，一種簡單粗暴，直接升級核心中 overlay 模組即可。

另外一種可以考慮把 containerd 從 v1.2 版本升級到 v1.3，原因在於 containerd v1.3 中會主動設定上述 opaque 屬性，該版本 containerd 不會觸發 overlayfs 的 bug。當然，這種方式是規避而非徹底解決 Bug。

snapshotter 生成映象原理分析

雖然根本原因看起來比較簡單，但分析的過程還是比較曲折的。在分享下這個問題的排查過程和收穫之前，為了方便大家理解，本小節將集中講解問題排查過程涉及到的 containerd 和 overlayfs 的知識，比較瞭解或者不感興趣的同學可以直接跳過。

與 docker daemon 一開始的設計不同，為了減少耦合性，containerd 通過外掛的方式由多個模組組成。結合下圖可以看出，其中與映象相關的模組包含以下幾種：

• metadata 是 containerd 通過 bbolt 實現的 kv 儲存模組，用來儲存映象、容器或者層等元資訊。比如命令列 ctr 列出所有 snapshot 或 kubelet 獲取所有 pod 都是通過 metadata 模組查詢的資料。

• content 是負責儲存 blob 的模組，其儲存的關於映象的內容一般分為三種：

  1. 映象的 manifest（一個普通的 json，其中指定了映象的 config 和映象的 layers 陣列）
  2. 映象的 config（同樣是個 json，其中指定映象的元資訊，比如啟動命令、環境變數等）
  3. 映象的 layer（tar 包，解壓、處理後會生成映象的層）

• snapshots 是快照模組總稱，可以設定使用不同的快照模組，常見的模組有 overlayfs、aufs 或 native。在 unpack 時 snapshots 會把生成映象層並儲存到檔案系統；當執行容器時，可以呼叫 snapshots 模組給容器提供 rootfs 。

容器映象規範主要有 docker 和 oci v1、v2 三種，考慮到這三種規範在原理上大同小異，可以參考以下示例，將 manifest 當作是每個映象只有一份的元資訊，用於指向映象的 config 和每層 layer。其中，config 即為映象配置，把映象作為容器執行時需要；layer 即為映象的每一層。

type manifest struct {
  c config
  layers []layer
}

映象下載流程與圖 1 中數字標註出來的順序一致，每個步驟作用總結如下：

首先在 metadata 模組中新增一個 image，這樣我們在執行 list image 時可看到這個 image。

其次是需要下載映象，因為映象是有 manifest、config、layers 等多個部分組成，所以先下載映象的 manifest 並儲存到 content 模組，再解析 manifest 獲取 config 的地址和 layers 的地址。接下來分別把 config 和每個 layer 下載並儲存到 content 模組，這裡需要強調映象的 layer 本來應該是目錄，當建立容器時聯合掛載到 root 下，但是為了方便網路傳輸和儲存，這裡會用 tar + 壓縮的方式儲存。這裡儲存到 content 也是不解壓的。

③、④、⑤的作用關聯性比較強，此處放在一起解釋。snapshot 模組去 content 模組讀取 manifest，找到映象的所有層，再去 content 模組把這些層自“下”而“上”讀取出來，逐一解壓並加工，最後放到 snapshot 模組的目錄下，像圖 1 中的 1001/fs、1002/fs 這些都是映象的層。（當建立容器時，需要把這些層聯合掛載生成容器的 rootfs，可以理解成1001/fs + 1002/fs + ... => 1008/work)。

整個流程的函式呼叫關係如下圖 2，喜歡閱讀原始碼的同學可以照著這個去看下。

為了方便理解，接下來用 layer 表示 snapshot 中的層，把剛下載未經過加工的“層”稱之為映象層的 tar 包或者是 tar 包。

下載映象儲存入 content 的流程比較簡單，直接跳過就好。而通過映象的 tar 包生成 snapshot 中的 layer 這個過程比較巧妙，甚至 bug 也是出現在這裡，接下來進行重點描述。

首先通過 content 拿到了映象的 manifest，這樣我們得知映象是有哪些層組成的。最下面一層映象比較簡單，直接解壓到 snapshot 提供的目錄就可以了，比如 10/fs。假設接下來要在 11/fs 生成第二層（此時 11/fs 還是空的），snapshot 會使用mount -t overlay overlay -o lowerdir=10/fs,upperdir=11/fs,workdir=11/work tmp把已經生成好的 layer 10 和還未生成的 layer 11 掛載到一個 tmp 目錄上，其中寫入層是 11/fs 也就是我們想要生成的 layer。去 content 中拿到 layer 11 對應的 tar 包，遍歷這個 tar 包，根據 tar 包中不同的檔案對掛載點 tmp 進行寫入或者刪除檔案的操作（因為是聯合掛載，所以對於掛載點的操作都會變成對寫入層的操作）。把 tar 包轉化成 layer 的具體邏輯和下面經過簡化的原始碼一致，可以看到如果 tar 包中存在 whiteout 檔案或者當前的層比如 11/fs 和之前的層有衝突比如 10/fs，會把底層目錄刪掉。在把 tar 包的檔案寫入到目錄後，會根據 tar 包中記錄的 PAXRecords 給檔案新增 xattr，PAXRecords 可以看做是 tar 中每個檔案都帶有的 kv 陣列，可以用來對映檔案系統中檔案屬性。

// 這裡的tmp就是overlay的掛載點
applyNaive(tar, tmp) {
  for tar.hashNext() {
    tar_file := tar.Next()										// tar包中的檔案
    real_file := path.Join(root, file.base)		// 現實世界的檔案
    // 按照規則刪除檔案
    if isWhiteout(info) {
      whiteRM(real_file)
    }
    if !(file.IsDir() && IsDir(real_file)) {
      rm(real_file)
    } 
    // 把tar包的檔案寫入到layer中
    createFileOrDir(tar_file, real_file)
    for k, v := range tar_file.PAXRecords {
      setxattr(real_file, k, v)
    }
  }
}

需要刪除的這些情況總結如下：

如果存在同名目錄，兩者進行 merge

如果存在同名但不都是目錄，需要刪除掉下層目錄（上檔案下目錄、上目錄下檔案、上檔案下檔案）

如果存在 .wh. 檔案，需要移除底層應該被覆蓋掉的目錄，比如目錄下存在 .wh..wh.opaque 檔案，就需要刪除 lowerdir 中的對應目錄。

當然這裡的刪除也沒那麼簡單，還記得當前的操作都是通過掛載點來刪除底層的檔案麼？在 overlay 中，如果通過掛載點刪除 lower 層的內容，不會把檔案真的從 lower 的檔案目錄中幹掉，而是會在 upper 層中新增 whiteout，新增 whiteout 的其中一種方式就是設定上層目錄的 xattr trusted.overlay.opaque=y。

當 tar 包遍歷結束以後，對 tmp 做個 umount，得到的 11/fs 就是我們想要的 layer，當我們想要生成 12/fs 這個 layer 時，只需要把 10/fs，11/fs 作為 lowerdir，把 12/fs 作為 upperdir 聯合掛載就可以。也就是說，之後映象的每一個 layer 生成都是需要把之前的 layer 掛載，下面圖說明了整個流程。

可以考慮下為什麼要這麼大費周章？關鍵有兩點。

一是映象中的刪除下層檔案是要遵循 image-spec 中對於 whiteout 檔案的定義（image-spec），這個檔案只會在 tar 包中作為標識，並不會產生真正的影響。而起到真正作用的是在 applyNaive 碰到了 whiteout 檔案，會呼叫聯合檔案系統對底層目錄進行刪除，當然這個刪除對於 overlay 就是標記 opaque。

二是因為存在檔案和目錄相互覆蓋的現象，每一個 tar 包中的檔案都需要和之前所有 tar包 中的內容進行比對，如果不借用聯合檔案系統的“超能力”，我們就只能拿著 tar 中的每一個檔案對之前的層遍歷。

問題排查過程

瞭解了映象相關的知識，我們來看看這個問題的排查過程。首先我們觀察使用者的容器，經過簡化和打碼目錄結構如下，其中目錄 modules 就是事故多發地。

/data
└── prom
    ├── bin
    └── modules
        ├── file
        └── lib/

再觀察下使用者的映象的各個層。我們把映象的層按照從下往上用遞增的 ID 來標註，對這個目錄有修改的有 5099、5101、5102、5103、5104 這幾層。把容器執行起來後，看到的 modules 目錄和 5104 提供的一樣。並沒有把 5103 等“下面”的映象合併起來，相當於 5104 把下面的目錄都覆蓋掉了（當然，5104 和 5103 檔案是有區別的）。

5104 下層目錄為何被覆蓋？

看到這裡，首先想到是不是建立容器的 rootfs 時引數出現了問題，導致少 mount 了一些層？於是模擬手動掛載mount -t overlay overlay -o lowerdir=5104:5103 point把最上兩層掛載，結果 5104 依然把 5103 覆蓋了。這裡推斷可能是存在 overlay 的 .wh. 檔案，於是嘗試在這兩層中搜 .wh. 檔案，無果。於是去查 overlayfs 的文件：

A directory is made opaque by setting the xattr "trusted.overlay.opaque"
to "y". Where the upper filesystem contains an opaque directory, any
directory in the lower filesystem with the same name is ignored.

設定了屬性 trusted.overlay.opaque=y 的目錄會變成“不透明”的，當上層檔案系統被設定為“不透明”時，下層中同名的目錄會被忽略。overlay 如果想要在上層把下層覆蓋掉，就需要設定這個屬性。

通過命令getfattr -n "trusted.overlay.opaque" dir檢視發現，5104 下面的 /data/asr_offline/modules 果然帶有這個屬性，這一現象也進而導致了下層目錄被“覆蓋”。

[root@]$ getfattr -n "trusted.overlay.opaque" 5104/fs/data/asr_offline/modules
# file: 5102/fs/data/asr_offline/modules
trusted.overlay.opaque="y"

一波多折，層層追究
那麼問題來了，為什麼只有特定的發行版會出現這個現象？我們嘗試在 ubuntu 拉下映象，發現“同源”目錄居然沒有設定 opaque！由於映象的層通過把原始檔解壓和解包生成的，我們決定在確保不同作業系統中的“映象原始檔”的 md5 相同之後，在各個作業系統上把映象原始檔通過tar -zxf進行解包並重新手動掛載，發現 5104 均不會把 5103 覆蓋。

根據以上現象推斷，可能是某些發行版下的 containerd 從 content 讀取 tar 包並解壓制作 snapshot 的 layer 時出現問題，錯誤地把 snapshot 的目錄設定上了這個屬性。

為驗證該推斷，決定進行原始碼梳理，由此發現了其中的疑點（相關程式碼如下）——生成 layers 時遍歷 tar 包會讀取每個檔案的 PAXRecords 並且把這個設定在檔案的 xattr 上（ tar 包給每個檔案都準備了 PAXRecords，和 Pod 的 labels 等價）。

func applyNaive() {
  // ...
  for k, v := range tar_file.PAXRecords {
		setxattr(real_file, k, v)
  }
}

func setxattr(path, key, value string) error {
	return unix.Lsetxattr(path, key, []byte(value), 0)
}

因為之前實驗過 v1.3 的 containerd 不會出現這個問題，所以對照了下兩者的程式碼，發現兩者從 tar 包中抽取 PAXRecords 設定 xattr 的邏輯兩者是不一樣的。v1.3 的程式碼如下：

func setxattr(path, key, value string) error {
	// Do not set trusted attributes
	if strings.HasPrefix(key, "trusted.") {
		return errors.Wrap(unix.ENOTSUP, "admin attributes from archive not supported")
	}
	return unix.Lsetxattr(path, key, []byte(value), 0)
}

也就是說 v1.3.0 中不會設定以trusted.開頭的 xattr！如果 tar 包中某目錄帶有trusted.overlay.opaque=y這個 PAX，低版本的 containerd 可能就會把這些屬性設定到 snapshot 的目錄上，而高版本的卻不會。那麼，當用戶在打包時，如果把 opaque 也打到 tar 包中，解壓得到的 layer 對應目錄也就會帶有這個屬性。5104 這個目錄可能就是這個原因才變成 opaque 的。

為了驗證這個觀點，我寫了一段簡單的程式來掃描與 layer 對應的 content 來尋找這個屬性，結果發現 5102、5103、5104 幾個層都沒有這個屬性。這時我也開始懷疑這個觀點了，畢竟如果只是 tar 包中有特別的標識，應該不會在不同的作業系統表現不同。

抱著最後一絲希望掃描了 5099 和 5101，果然也並沒有這個屬性。但在掃描的過程中，注意到 5101 的 tar 包裡存在 /data/asr_offline/modules/.wh..wh.opq 這個檔案。記得當時看程式碼 applyNaive 時如果遇到了 .wh..wh.opq 對應的操作應該是在掛載點刪除 /data/asr_offline/modules，而在 overlay 中刪除 lower 目錄會給 upper 同名目錄加上trusted.overlay.opaque=y。也就是說，在生成 layer 5101 時（需要提前掛載好 5100 和 5099），遍歷 tar 包遇到了這個 wh 檔案，應該先在掛載點刪除 modules，也就是會在 5101 對應目錄加上 opaque=y。

再次以驗證原始碼成果的心態，去 snapshot 的 5101/fs 下檢視目錄 modules 的 opaque，果然和想象的一樣。這些檔案應該都是在 lower層，所以對應的 overlayfs 的操作應該是在 upper 也就是 5101 層的 /data/asr_offline/modules 目錄設定trusted.overlay.opaque=y。去檢視 5101 的這個目錄，果然帶有這個屬性，好奇心驅使著我繼續查看了 5102、5103、5104 這幾層的目錄，發現居然都有這個屬性。

也就是這些 layer 每個都會把下面的覆蓋掉？這好像不符合常理。於是，去表現正常的 ubuntu 中檢視，發現只有 5101 有這個屬性。經過反覆確認 5102、5103、5104 的 tar 包中的確沒有目錄 modules 的 whiteout 檔案，也就是說映象原本的意圖就是讓 5101 把下面的層覆蓋掉，再把 5101、5102、5103、5104 這幾層的 modules 目錄 merge 起來。整個生成映象的流程裡，只有“借用”overlay 生成 snapshot 的 layer 會涉及到作業系統。

雲開霧散，大膽猜探

我們不妨大膽猜測一下，會不會像下圖這樣，在生成 layer 5102 時，因為核心或 overlay 的 bug 把 modules 也添加了不透明的屬性？

為了對這個特性做單獨的測試，寫了個簡單的指令碼。執行指令碼之後，果然發現在這個發行版中，如果 overlay 的低層目錄有這個屬性並且在 upper 層中建立了同樣的目錄，會把這個 opaque“傳播”到 upper 層的目錄中。如果像 containerd 那樣遞推生成映象，肯定從有 whiteout 層開始上面的每一層都會具有這個屬性，也就導致了最終容器在某些特定的目錄只能看到最上面一層。

`#!/bin/bash

mkdir 1 2 work p
mkdir 1/func
touch 1/func/min

mount -t overlay overlay p -o lowerdir=1,upperdir=2,workdir=work
rm -rf p/func
mkdir -p p/func
touch p/func/max
umount p
getfattr -n "trusted.overlay.opaque" 2/func

mkdir 3
mount -t overlay overlay p -o lowerdir=2:1,upperdir=3,workdir=work
touch p/func/sqrt
umount p
getfattr -n "trusted.overlay.opaque" 3/func`

最終總結

在幾個核心大佬的幫助下，確認了是核心 overlayfs 模組的 bug。在 lower 層呼叫 copy_up 時並沒有檢測 xattr，從而導致 opaque 這個 xattr 傳播到了 upper 層。做聯合掛載時，如果上層的檔案得到了這個屬性，自然會把下層檔案覆蓋掉，也就出現了映象中丟失檔案的現象。反思整個排查過程，其實很難在一開始就把問題定位到核心的某個模組上，好在可以另闢蹊徑通過測試和閱讀原始碼逐步逼近“真相”，成功尋得解決方案。
【騰訊雲原生】雲說新品、雲研新術、雲遊新活、雲賞資訊，掃碼關注同名公眾號，及時獲取更多幹貨！！