如何優(yōu)雅的將Docker Registry中容器鏡像遷移至Harbor
Registry
Docker Distribution
Docker Distribution[1] 是第一個是實現了打包、發(fā)布、存儲和鏡像分發(fā)的工具，起到 Docker registry 的作用。其中 Docker Distribution 中的 spec 規(guī)范[2] 后來也就成為了 OCI distribution-spec[3] 規(guī)范。可以認為 Docker Distribution 實現了大部分 OCI 鏡像分發(fā)的規(guī)范，二者在很大程度上也是兼容的。OCI 的指導思想是先有工業(yè)界的實踐，再將這些實踐總結成技術規(guī)范，因此盡管 OCI 的 distribution-spec[4] 規(guī)范還沒有正式發(fā)布（目前版本是v1.0.0-rc1[5]），但以 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 規(guī)范的 Helm Chart、CNAB、OPA Bundle 等 Artifact 。
docker registry to harbor
好了，扯了這么多沒用的概念，回到本文要解決的問題：如何將 docker registry 中的鏡像遷移至 harbor？
假如內網環(huán)境中有兩臺機器，一臺機器上運行著 docker registry，域名假設為 registry.k8s.li 。另一臺機器運行著 harbor，假設域名為 harbor.k8s.li。現在 docker registry 中存放了五千個鏡像。harbor 是剛剛部署了，里面還沒有鏡像。在磁盤和網絡沒有限制的情況下，如何將 docker registry 中的鏡像遷移到 harbor 中？
獲取 registry 所有鏡像的列表
根據木子在 深入淺出容器鏡像的一生 🤔[6] 文章中提到的 registry 的存儲目錄結構，我們可以使用如下命令獲取 registry 中的所有鏡像的列表。
# 首先進入到 registry 存儲的主目錄下 ：
- cd /var/lib/registry
- find docker -type d -name "current" | sed 's|docker/registry/v2/repositories/||g;s|/_manifests/tags/|:|g;s|/current||g' > images.list
方案一：docker retag
方案一可能是大多數人首先想到的辦法，也是最簡單粗暴的方法。就是在一臺機器上使用 docker pull 下 docker registry 中的所有鏡像，然后再 docker retag 一下，再 docker push 到 harbor 中。
- # 假設其中的一個鏡像為 library/alpine:latest
- docker pull registry.k8s.li/library/alpine:latest
- docker tag registry.k8s.li/library/alpine:latest harbor.k8s.li/library/alpine:latest
- docker push harbor.k8s.li/library/alpine:latest
如果你之前讀過木子曾經寫過的 深入淺出容器鏡像的一生 🤔[7] 和 鏡像搬運工 skopeo 初體驗[8] 并且已經在日常生活中使用 skopeo ，你一定會很覺著這個方案很蠢，因為 docker pull –> docker tag –> docker pull 的過程中會對鏡像的 layer 進行解壓縮，但對于只是將鏡像從一個 registry 復制到另一個 registry 來說，這些過程中做了很多無用功。詳細的原理可以翻看一下剛提到的兩篇文章，在此就不再贅述。
那么對于追求極致的人來講肯定不會采用 docker retag 這么蠢的辦法啦，下面就講一下方案二：
方案二：skopeo
在 鏡像搬運工 skopeo 初體驗[9] 中介紹過可以使用 skopeo copy 直接從一個 registry 中復制鏡像原始的 layer 到另一個 registry 中，期間不會涉及鏡像 layer 解壓縮操作。至于性能和耗時，比 docker 高到不知道哪里去了 😂。
- 使用 skopeo copy
- skopeo copy docker://registry.k8s.li/library/alpine:latest \ docker://harbor.k8s.li/library/alpine:latest
- 使用 skopeo sync
- skopeo sync --insecure-policy --src-tls-verify=false --dest-tls-verify=false --src docker --dest docker registry.k8s.li/library/alpine:latest harbor.k8s.li/library/alpine:latest
但還有沒有更好的辦法？要知道無論是 docker 和 skopeo 本質上都是通過 registry 的 HTTP API 下載和上傳鏡像的，在這過程中還是多了不少 HTTP 請求的，還有沒有更好的辦法？
方案三：遷移存儲目錄
文章開篇提到 harbor 的后端鏡像存儲也是使用的 docker registry，那為何不直接將 registry 的存儲目錄打包復制并解壓到 harbor 的 registry 存儲目錄呢？對于 harbor 1.x 版本來講，將 docker 的 registry 存儲目錄遷移到 harbor 的 registry 存儲目錄，然后刪除 harbor 的 redis 數據，重啟 harbor 就完事兒了。重啟 harbor 之后，harbor 會調用后端的 registry 去提取鏡像的元數據信息并存儲到 redis 中。這樣就完成了遷移的工作。
- # 切換到 harbor 的存儲目錄
- cd /data/harbor
- # 將 docker registry 備份的 docker 目錄解壓到 harbor 的 registry 目錄下，目錄層級一定要對應好
- tar -xf docker.tar.gz -C ./registry
- # 刪除 harbor 的 regis 數據，重啟 harbor 后會重建 redis 數據。
- rm -f redis/dump.rdb
- # 切換到 harbor 的安裝目錄重啟 harbor
- cd /opt/harbor
- docker-compose restart
方案四：
對于 harbor 2.x 來講，由于 harbor 強化了 Artifact 的元數據管理能力，即元數據在 push 或者 sync 到 harbor 時會寫入到 harbor 自身的數據庫中。在 harbor 看來只要數據庫中沒有這個 Artifact 的 manifest 信息或者沒有這一層 layer 的信息，harbor 都會認為該 Artifact 或者 layer 不存在，返回 404 的錯誤。所以按照方案三直接而將 registry 存儲目錄解壓到 harbor 的 registry 存儲目錄時行不通的。那么現在看來只能通過 skopeo copy 的方法將鏡像一個一個地 push 到 harbor 中了。
對于某些特定的場景下，不能像方案二那樣擁有一個 docker registry 的 HTTP 服務，只有一個 docker registry 的壓縮包，這如何將 docker registry 的存儲目錄中的鏡像遷移到 harbor 2.0 中呢？
那么再次邀請我們的 skopeo 大佬出場，在 鏡像搬運工 skopeo 初體驗[10] 中提到過 skopeo 支持的鏡像格式有如下幾種：
| IMAGE NAMES | example |
|---|---|
| containers-storage: | containers-storage: |
| dir: | dir:/PATH |
| docker:// | docker://k8s.gcr.io/kube-apiserver:v1.17.5 |
| docker-daemon: | docker-daemon:alpine:latest |
| docker-archive: | docker-archive:alpine.tar (docker save) |
| oci: | oci:alpine:latest |
需要注意的是，這幾種鏡像的名字，對應著鏡像存在的方式，不同存在的方式對鏡像的 layer 處理的方式也不一樣，比如 docker:// 這種方式是存在 registry 上的，docker-daemon: 是存在本地 docker pull 下來的，再比如 docker-archive 是通過 docker save 出來的鏡像。同一個鏡像有這幾種存在的方式就像水有氣體、液體、固體一樣。可以這樣去理解，他們表述的都是同一個鏡像，只不過是存在的方式不一樣而已。
既然鏡像是存放在 registry 存儲目錄里的，那么使用 dir 的形式直接從文件系統(tǒng)讀取鏡像，理論上來講會比方案二要好一些。雖然 skopeo 支持 dir 格式的鏡像，但 skopeo 目前并不支持直接使用 registry 的存儲目錄，所以還是需要想辦法將 docker registry 存儲目錄里的每一個鏡像轉換成 skopeo dir 的形式。
skopeo dir
那么先來看一下 skopeo dir 是什么樣子的？
為了方便測試方案的可行性，先使用 skopeo 命令先從 docker hub 上拉取一個鏡像，并保存為 dir，命令如下：
- skopeo copy docker://alpine:latest dir:./alpine
使用 tree 命令查看一下 alpine 文件夾的目錄結構，如下：
- ╭─root@sg-02 /var/lib/registry
- ╰─# tree -h alpine
- alpine
- ├── [2.7M] 4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580
- ├── [1.4K] e50c909a8df2b7c8b92a6e8730e210ebe98e5082871e66edd8ef4d90838cbd25
- ├── [ 528] manifest.json
- └── [ 33] version
- 0 directories, 4 files
- ╭─root@sg-02 /var/lib/registry
- ╰─# file alpine/e50c909a8df2b7c8b92a6e8730e210ebe98e5082871e66edd8ef4d90838cbd25
- alpine/e50c909a8df2b7c8b92a6e8730e210ebe98e5082871e66edd8ef4d90838cbd25: ASCII text, with very long lines, with no line terminators
- ╭─root@sg-02 /var/lib/registry
- ╰─# file alpine/4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580
- alpine/4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580: gzip compressed data
從文件名和大小以及文件的內省我們可以判斷出，manifest 文件對應的就是鏡像的 manifests 文件；類型為 ASCII text 的文件正是鏡像的 image config 文件，里面包含著鏡像的元數據信息。而另一個 gzip compressed data 文件不就是經過 gzip 壓縮過的鏡像 layer 嘛。看一下 manifest 文件的內容也再次印證了這個結論：
- 鏡像的 config 字段對應的正是 e50c909a8df2，而文件類型正是 image.v1+json 文本文件。
- 鏡像的 layer 字段對應的也正是 4c0d98bf9879 而文件類型正是 .tar.gzip gzip 壓縮文件。
- alpine/4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580: gzip compressed data
- ╭─root@sg-02 /var/lib/registry
- ╰─# cat alpine/manifest.json
- {
- "schemaVersion": 2,
- "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
- "config": {
- "mediaType": "application/vnd.docker.container.image.v1+json",
- "size": 1471,
- "digest": "sha256:e50c909a8df2b7c8b92a6e8730e210ebe98e5082871e66edd8ef4d90838cbd25"
- },
- "layers": [
- {
- "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
- "size": 2811321,
- "digest": "sha256:4c0d98bf9879488e0407f897d9dd4bf758555a78e39675e72b5124ccf12c2580"
- }
- ]
- }
從 registry 存儲目錄中摳鏡像出來
接下來到本文的精彩的地方了。如何將 registry 存儲里的鏡像提取出來，轉換成 skopeo 所支持的 dir 格式。
- 首先要得到鏡像的 manifests 文件，從 manifests 文件中得到所有的 blob 文件。例如對于 registry 存儲目錄中的 library/alpine:latest 鏡像。
- ╭─root@sg-02 /var/lib/registry/docker/registry/v2
- ╰─# tree
- .
- ├── blobs
- │ └── sha256
- │ ├── 21
- │ │ └── 21c83c5242199776c232920ddb58cfa2a46b17e42ed831ca9001c8dbc532d22d
- │ │ └── data
- │ ├── a1
- │ │ └── a143f3ba578f79e2c7b3022c488e6e12a35836cd4a6eb9e363d7f3a07d848590
- │ │ └── data
- │ └── be
- │ └── be4e4bea2c2e15b403bb321562e78ea84b501fb41497472e91ecb41504e8a27c
- │ └── data
- └── repositories
- └── library
- └── alpine
- ├── _layers
- │ └── sha256
- │ ├── 21c83c5242199776c232920ddb58cfa2a46b17e42ed831ca9001c8dbc532d22d
- │ │ └── link
- │ └── be4e4bea2c2e15b403bb321562e78ea84b501fb41497472e91ecb41504e8a27c
- │ └── link
- ├── _manifests
- │ ├── revisions
- │ │ └── sha256
- │ │ └── a143f3ba578f79e2c7b3022c488e6e12a35836cd4a6eb9e363d7f3a07d848590
- │ │ └── link
- │ └── tags
- │ └── latest
- │ ├── current
- │ │ └── link
- │ └── index
- │ └── sha256
- │ └── a143f3ba578f79e2c7b3022c488e6e12a35836cd4a6eb9e363d7f3a07d848590
- │ └── link
- └── _uploads
- 26 directories, 8 files
1. 通過 repositories/library/alpine/_manifests/tags/latest/current/link 文件得到 manifests 文件的 sha256 值，然后根據這個 sha256 值去 blobs 找到鏡像的 manifests 文件;
- ╭─root@sg-02 /var/lib/registry/docker/registry/v2/repositories/library/alpine/_manifests/tags/latest/current/
- ╰─# cat link
- sha256:39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01#
2. 根據 link 文件中的 sha256 值在 blobs 目錄下找到與之對應的文件，blobs 目錄下對應的 manifests 文件為 blobs/sha256/39/39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01/data;
- ╭─root@sg-02 /var/lib/registry/docker/registry/v2/repositories/library/alpine/_manifests/tags/latest/current
- ╰─# cat /var/lib/registry/docker/registry/v2/blobs/sha256/39/39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01/data
- {
- "schemaVersion": 2,
- "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
- "config": {
- "mediaType": "application/vnd.docker.container.image.v1+json",
- "size": 1507,
- "digest": "sha256:f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a"
- },
- "layers": [
- {
- "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
- "size": 2813316,
- "digest": "sha256:cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08"
- }
- ]
- }
3. 使用正則匹配，過濾出 manifests 文件中的所有 sha256 值，這些 sha256 值就對應著 blobs 目錄下的 image config 文件和 image layer 文件
- ╭─root@sg-02 /var/lib/registry/docker/registry/v2/repositories/library/alpine/_manifests/tags/latest/current
- ╰─# cat /var/lib/registry/docker/registry/v2/blobs/sha256/39/39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01/data | grep -Eo "\b[a-f0-9]{64}\b"
- f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a
- cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08
4. 根據 manifests 文件就可以得到 blobs 目錄中鏡像的所有 layer 和 image config 文件，然后將這些文件拼成一個 dir 格式的鏡像，在這里使用 cp 的方式將鏡像從 registry 存儲目錄里 撈 出來 😂
- # 首先創(chuàng)建一個文件夾，為了保留鏡像的 name 和 tag，文件夾的名稱就對應的是 NAME:TAG
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# mkdir -p skopeo/library/alpine:latest
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# cp /var/lib/registry/docker/registry/v2/blobs/sha256/39/39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01/data skopeo/library/alpine:latest/manifest
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# cp /var/lib/registry/docker/registry/v2/blobs/sha256/f7/f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a/data skopeo/library/alpine:latest/f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# cp /var/lib/registry/docker/registry/v2/blobs/sha256/cb/cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08/data skopeo/library/alpine:latest/cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# tree skopeo/library/alpine:latest
- skopeo/library/alpine:latest
- ├── cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08
- ├── f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a
- └── manifest
- 0 directories, 3 files
和上面的 skopeo copy 出來的 dir 文件夾對比一下，到此為止鏡像所需要的文件就基本上都齊全了，就差一個 version 文件，這個文件無關緊要可以去掉。
5. 再優(yōu)化一下，將步驟 4 中的 cp 操作修改成硬鏈接操作，能極大減少磁盤的 IO 操作。需要注意，硬鏈接文件不能跨分區(qū)，所以要和 registry 存儲目錄在同一個分區(qū)下才行。
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# ln /var/lib/registry/docker/registry/v2/blobs/sha256/39/39eda93d15866957feaee28f8fc5adb545276a64147445c64992ef69804dbf01/data skopeo/library/alpine:latest/manifest
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# ln /var/lib/registry/docker/registry/v2/blobs/sha256/f7/f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a/data skopeo/library/alpine:latest/f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# ln /var/lib/registry/docker/registry/v2/blobs/sha256/cb/cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08/data skopeo/library/alpine:latest/cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08
- ╭─root@sg-02 /var/lib/registry/docker
- ╰─# tree skopeo/library/alpine:latest
- skopeo/library/alpine:latest
- ├── cbdbe7a5bc2a134ca8ec91be58565ec07d037386d1f1d8385412d224deafca08
- ├── f70734b6a266dcb5f44c383274821207885b549b75c8e119404917a61335981a
- └── manifest
- 0 directories, 3 files
然后使用 skopeo copy 或者 skopeo sync 將鏡像 push 到 harbor
- 使用 skopeo copy
- skopeo copy --insecure-policy --src-tls-verify=false --dest-tls-verify=false \
- dir:skopeo/library/alpine:latest docker://harbor.k8s.li/library/alpine:latest
- 使用 skopeo sync
需要注意的是，skopeo sync 的方式是同步 project 級別的，鏡像的 name 和 tag 就對應的是目錄的名稱
- skopeo sync --insecure-policy --src-tls-verify=false --dest-tls-verify=false \
- --src dir --dest docker skopeo/library/ harbor.k8s.li/library/
實現腳本
大叫一聲 shell 大法好！😂
- #!/bin/bash
- REGISTRY_DOMAIN="harbor.k8s.li"
- REGISTRY_PATH="/var/lib/registry"
- # 切換到 registry 存儲主目錄下
- cd ${REGISTRY_PATH}
- gen_skopeo_dir() {
- # 定義 registry 存儲的 blob 目錄 和 repositories 目錄，方便后面使用
- BLOB_DIR="docker/registry/v2/blobs/sha256"
- REPO_DIR="docker/registry/v2/repositories"
- # 定義生成 skopeo 目錄
- SKOPEO_DIR="docker/skopeo"
- # 通過 find 出 current 文件夾可以得到所有帶 tag 的鏡像，因為一個 tag 對應一個 current 目錄
- for image in $(find ${REPO_DIR} -type d -name "current"); do
- # 根據鏡像的 tag 提取鏡像的名字
- name=$(echo ${image} | awk -F '/' '{print $5"/"$6":"$9}')
- link=$(cat ${image}/link | sed 's/sha256://')
- mfs="${BLOB_DIR}/${link:0:2}/${link}/data"
- # 創(chuàng)建鏡像的硬鏈接需要的目錄
- mkdir -p "${SKOPEO_DIR}/${name}"
- # 硬鏈接鏡像的 manifests 文件到目錄的 manifest 文件
- ln ${mfs} ${SKOPEO_DIR}/${name}/manifest.json
- # 使用正則匹配出所有的 sha256 值，然后排序去重
- layers=$(grep -Eo "\b[a-f0-9]{64}\b" ${mfs} | sort -n | uniq)
- for layer in ${layers}; do
- # 硬鏈接 registry 存儲目錄里的鏡像 layer 和 images config 到鏡像的 dir 目錄
- ln ${BLOB_DIR}/${layer:0:2}/${layer}/data ${SKOPEO_DIR}/${name}/${layer}
- done
- done
- }
- sync_image() {
- # 使用 skopeo sync 將 dir 格式的鏡像同步到 harbor
- for project in $(ls ${SKOPEO_DIR}); do
- skopeo sync --insecure-policy --src-tls-verify=false --dest-tls-verify=false \
- --src dir --dest docker ${SKOPEO_DIR}/${project} ${REGISTRY_DOMAIN}/${project}
- done
- }
- gen_skopeo_dir
- sync_image
其實魔改一下 skopeo 的源碼也是可以無縫支持 registry 存儲目錄的，目前正在研究中 😃
對比
| 方法 | 適用范圍 | 缺點 | |
|---|---|---|---|
| 一 | docker retag | 兩個 registry 之間同步鏡像 | |
| 二 | skopeo | 兩個 registry 之間同步鏡像 | |
| 三 | 解壓目錄 | registry 存儲目錄到另一個 registry | harbor 1.x |
| 四 | skopeo dir | registry 存儲目錄到另一個 registry | 適用于 harbor 2.x |
對比總結一下以上幾種方案：
- 方案一：上手成本低，適用于鏡像數量比較多少，無需安裝 skopeo 的情況，缺點是性能較差。
- 方案二：適用于兩個 registry 之間同步復制鏡像，如將 docker hub 中的一些公共鏡像復制到公司內網的鏡像倉庫中。
- 方案三：適用于鏡像倉庫之間進行遷移，性能是所有方案里最好的，需要額外注意的是如果目的鏡像倉庫是 harbor 2.x，是無法使用這種方式的。
- 方案四：是方案三的妥協(xié)版，為了適配 harbor 2.0 ，因為需要重新將鏡像 push 到 harbor ，所以性能上要比方案三差一些。
