[[425177]]

Registry

Docker Distribution

Docker Distribution 是第一個是實現了打包、發布、存儲和鏡像分發的工具，起到 docker registry 的作用。（目前 Distribution 已經捐贈給了 CNCF）。其中 Docker Distribution 中的 spec 規范后來也就成為了 OCI distribution-spec 規范。可以認為 Docker Distribution 實現了大部分 OCI 鏡像分發的規范，二者在很大程度上也是兼容的。

OCI 的指導思想時先有工業界的實踐，再將這些實踐總結成技術規范，因此盡管 OCI 的 distribution-spec 規范還沒有正式發布（目前版本是 v1.0.0-rc1），但以 Docker Distribution 作為基礎的鏡像倉庫已經成為普遍采用的方案，docker registry http api v2 也就成為了事實上的標準。

Harbor

harbor 也是采用了 Docker Distribution （docker registry）作為后端鏡像存儲服務，在 harbor 2.0 之前的版本，鏡像相關的功能大部分是由 Docker Distribution 來處理，鏡像和 OCI 等制品的元數據是 harbor 組件從 docker registry 中提取出來的；harbor 在 2.0 版本之后，鏡像等 OCI 制品相關的元數據由 harbor 自己來維護，而且元數據是在 PUSH 這些制品時寫入到 harbor 的數據庫中的。

正因得益于此，harbor 不再僅僅是個用來存儲和管理鏡像的服務，而一個云原生倉庫服務，能夠存儲和管理符合 OCI 規范的 Helm Chart、CNAB、OPA Bundle 等多種 Artifact。

Docker Registry to Harbor

回到本文主題：如何將 docker registry 中的鏡像遷移至 harbor？

假如內網環境中有兩臺機器，一臺機器上運行著 docker registry，域名假設為 registry.k8s.li 。另一臺機器運行著 harbor，假設域名為 harbor.k8s.li。現在 docker registry 中存放了五千個鏡像。harbor 是剛剛部署的，里面還沒有鏡像。在磁盤和網絡沒有限制的情況下，如何高效地將 docker registry 中的鏡像遷移到 harbor 中呢？

獲取 Registry 所有鏡像的列表

首先在遷移之前我們要獲取一份 docker registry 中鏡像的列表，這樣我們才能保證遷移后沒有鏡像丟失。根據《 深入淺出容器鏡像的一生》一文中提到的 registry 的存儲目錄結構。在 registry 存儲目錄中，每個鏡像的 tag 都是由 current/index 這個文件指向該 tag 鏡像的 manifests 文件的，由此我們可以通過遍歷 registry 存儲目錄中 current/index 文件的方式來得到所有鏡像的 tag，由此得到該 registry 中所有鏡像的列表。注意，這樣只能得到有 tag 的鏡像，其他沒 tag 的鏡像無法獲取到。

可通過如下命令在 registry 存儲目錄下獲取鏡像列表：

Harbor 創建 project

對于新部署的 harbor 來說，上面只會有一個默認的 library 的 project，需要手動在 harbor 上創建 docker registry 中對應的 project。docker registry 中鏡像的 project 就是 registry 存儲目錄中 repositories 下的目錄名。

得到了鏡像列表，以及在 harbor 上完成了對應 project 的創建，我們就可以做正式的遷移工作啦。根據不同的場景，可使用如下幾種方案：

方案一：docker retag

方案一可能是大多數人首先想到的辦法，也是最簡單粗暴的方法。就是在一臺機器上使用 docker pull 下 docker registry 中的所有鏡像，然后再 docker retag 一下，再 docker push 到 harbor 中。

如果之前看過我寫的《深入淺出容器鏡像的一生》和 《鏡像搬運工 skopeo 初體驗》，并且已經在日常生活中使用 skopeo ，一定會覺得這并不是個聰明的方案，因為 docker pull –> docker tag –> docker pull 的過程中會對鏡像的 layer 進行解壓縮。對于只是將鏡像從一個 registry 復制到另一個 registry 來說，這些 docker 在這些過程中做了很多無用功。詳細的原理可以參考上述兩篇文章，在此不再贅述。

為了追求高效，我們不使用 docker retag 方案，下面看一下方案二：

方案二：skopeo

在《鏡像搬運工 skopeo 初體驗》一文中介紹過可以使用 skopeo copy 直接從一個 registry 中復制鏡像原始 blobs 到另一個 registry 中，在此期間不會涉及鏡像 layer 解壓縮操作。在性能和耗時兩個角度上，都比使用 docker 的方式高效很多。

•  使用 skopeo copy

•  使用 skopeo sync

無論是 docker 和 skopeo 本質上都是通過 registry 的 HTTP API 下載和上傳鏡像的，在這過程中還是多了不少 HTTP 請求的，如果走的是 HTTPS 的話，還涉及了 HTTPS 加密和解密的過程，這期間有很多無用功。那么還有沒有更好的辦法？

方案三：遷移存儲目錄

文章開頭提到 harbor 的后端鏡像存儲也是使用的 docker registry，對于一個 registry 來說，只要是使用的是 Docker Distribution V2 ，它后端的存儲目錄結構都是一模一樣的。那為什么不直接將 registry 的存儲目錄打包復制并解壓到 harbor 的 registry 存儲目錄？這樣又能保證所有的鏡像都遷移過去，不會落下任何一個。

對于 harbor 1.x 版本來講，將 docker registry 的存儲目錄直接遷移到 harbor 的 registry 存儲目錄，然后刪除 harbor 的 redis 數據（因為 harbor 的 redis 緩存了鏡像的元數據信息），重啟 harbor 就好了。重啟 harbor 之后，harbor 會調用后端的 registry 去提取鏡像的元數據信息并存儲到 redis 中。這樣就完成了遷移的工作。

在 docker registry 機器上備份 registry 存儲目錄

備份完成之后將 docker.tar scp 到 harbor 機器上，然后在 harbor 機器上恢復 registry 存儲目錄

這樣遷移之后可能會遇到無法往 harbor push 鏡像的問題。因為 docker registry 容器內 registry 存儲目錄的所屬和所屬組為 root，而 harbor registry 容器內 registry 存儲目錄的所屬和所屬組為 10000:10000，二者權限并不相同，會導致 harbor 無法 push 鏡像。因此在遷移完成之后需要修改一下 harbor registry 目錄的所屬和所屬組。

方案四

對于 harbor 2.x 來講，由于 harbor 強化了 Artifact 的元數據管理能力，即元數據要在 push 或者 sync 到 harbor 時寫入到 harbor 自身的數據庫中。在 harbor 看來只要數據庫中沒有這個 Artifact 的 manifest 信息或者沒有這一層 layer 的信息，harbor 都會認為該 Artifact 或者 layer 不存在，返回 404 的錯誤。按照方案三直接而將 docker registry 存儲目錄解壓到 harbor 的 registry 存儲目錄的方法行不通的。因為是將鏡像解壓到 registry 存儲中的，雖然在 harbor 的 registry 容器看來是有鏡像的，但因為 harbor 的數據庫中沒有鏡像，harbor 就會認為沒有鏡像。那么現在看來只能通過方案二使用 skopeo 將鏡像一個一個地 push 到 harbor 中了。

但對于某些特定的場景下，不能像方案二那樣擁有一個 docker registry 的 HTTP 服務，只有一個 docker registry 的壓縮包，這如何將 docker registry 的存儲目錄中的鏡像遷移到 harbor 2.0 中呢？

在《鏡像搬運工 skopeo 初體驗》中提到過 skopeo 支持的鏡像格式有如下幾種：

需要注意的是，這幾種鏡像的名字，對應著鏡像存在的方式，不同存在的方式對鏡像的 layer 處理的方式也不一樣，比如 docker:// 這種方式是存在 registry 上的；docker-daemon: 是存在本地 docker pull 下來的；再比如 docker-archive 是通過 docker save 出來的鏡像；而 dir: 是鏡像以文件夾的形式保存的。同一個鏡像有這幾種存在的方式就像水有氣體、液體、固體一樣。可以這樣去理解，他們表述的都是同一個鏡像，只不過是存在的方式不一樣而已。

既然鏡像是存放在 registry 存儲目錄里的，那么使用 dir 的形式直接從文件系統讀取鏡像，理論上來講會比方案二要好一些。雖然 skopeo 支持 dir 格式的鏡像，但 skopeo 目前并不支持直接使用 registry 的存儲目錄，所以還是需要想辦法將 docker registry 存儲目錄里的每一個鏡像轉換成 skopeo dir 的形式。

skopeo dir

那么先來看一下 skopeo dir 是什么樣子的？

為了方便測試方案的可行性，先使用 skopeo 命令先從 docker hub 上拉取一個鏡像，并保存為 dir，命令如下：

使用 tree 命令查看一下 alpine 文件夾的目錄結構，如下：

從文件名和大小以及文件的內省我們可以判斷出，manifest 文件對應的就是鏡像的 manifests 文件；類型為 ASCII text 的文件正是鏡像的 image config 文件，里面包含著鏡像的元數據信息。而另一個 gzip compressed data 文件不就是經過 gzip 壓縮過的鏡像 layer 嘛。看一下 manifest 文件的內容也再次印證了這個結論：

•  鏡像的 config 字段對應的正是 e50c909a8df2，而文件類型正是 image.v1+json 文本文件。
•  鏡像的 layer 字段對應的也正是 4c0d98bf9879 而文件類型正是 .tar.gzip gzip 壓縮文件。

從 registry 存儲目錄中撈鏡像出來

接下來到本文的較為精彩的地方了。如何從 registry 存儲里“撈”鏡像出來，轉換成 skopeo 所支持的 dir 格式。

•  首先要得到鏡像的 manifests 文件，從 manifests 文件中可以得到該鏡像的所有 blob 文件。例如對于 registry 存儲目錄中的 library/alpine:latest 鏡像來講，它在 registry 中是這樣存放的：

1.通過 repositories/library/alpine/_manifests/tags/latest/current/link 文件得到 alpine 鏡像 lasts 這個 tag 的 manifests 文件的 sha256 值，然后根據這個 sha256 值去 blobs 找到鏡像的 manifests 文件;

2.根據 current/link 文件中的 sha256 值在 blobs 目錄下找到與之對應的文件，blobs 目錄下對應的 manifests 文件為 blobs/sha256/39/39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01/data;

3.使用正則匹配，過濾出 manifests 文件中的所有 sha256 值，這些 sha256 值就對應著 blobs 目錄下的 image config 文件和 image layer 文件;

4.根據 manifests 文件就可以得到 blobs 目錄中鏡像的所有 layer 和 image config 文件，然后將這些文件拼成一個 dir 格式的鏡像，在這里使用 cp 的方式將鏡像從 registry 存儲目錄里復制出來，過程如下：

最終得到的鏡像格式如下：

和上面的 skopeo copy 出來的 dir 文件夾對比一下，除了一個無關緊要的 version 文件，其他的都一摸一樣。

5.再優化一下，將步驟 4 中的 cp 操作修改成硬鏈接操作，能極大減少磁盤的 IO 操作。需要注意：硬鏈接文件不能跨分區，所以要和 registry 存儲目錄在同一個分區下才行。

然后使用 skopeo copy 或者 skopeo sync 將撈出來的鏡像 push 到 harbor

•  使用 skopeo copy

•  使用 skopeo sync 需要注意的是，skopeo sync 的方式是同步 project 級別的，鏡像的 name 和 tag 就對應的是目錄的名稱

實現腳本

其實修改一下 skopeo 的源碼應該也是可以無縫支持 registry 存儲目錄的。

對比

對比總結一下以上幾種方案：

•  方案一：上手成本低，適用于鏡像數量比較多少，無需安裝 skopeo 的情況，缺點是性能較差；
•  方案二：適用于兩個 registry 之間同步復制鏡像，如將 docker hub 中的一些公共鏡像復制到公司內網的鏡像倉庫中。
•  方案三：適用于鏡像倉庫之間進行遷移，性能是所有方案里最好的，需要額外注意的是如果目的鏡像倉庫是 harbor 2.x，是無法使用這種方式的。
•  方案四：是方案三的妥協版，為了適配 harbor 2.0 ，因為需要重新將鏡像 push 到 harbor ，所以性能上要比方案三差一些。