揭秘！containerd 鏡像檔案丟失問題，竟是鏡像生成惹得禍

導語

作者李志宇，騰訊云后臺開發工程師，日常負責集群節點和運行時相關的作業，熟悉 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 層，做聯合掛載時，如果上層的檔案得到了這個屬性，自然會把下層檔案覆寫掉，也就出現了鏡像中丟失檔案的現象，反思整個排查程序，其實很難在一開始就把問題定位到內核的某個模塊上，好在可以另辟蹊徑通過測驗和閱讀原始碼逐步逼近“真相”，成功尋得解決方案，
【騰訊云原生】云說新品、云研新術、云游新活、云賞資訊，掃碼關注同名公眾號，及時獲取更多干貨！！

標籤：其他

上一篇：大資料平臺是否更應該容器化?

下一篇：Nginx Ingress on TKE 部署最佳實踐