## 概述

使用者業務在上雲或者雲遷移過程中，需要對映象進行批次遷移。基於此背景，騰訊雲容器專家團隊開發了映象批次遷移工具：image-transfer。該工具支援多種雲廠商映象倉庫之間的批次遷移，同時支援騰訊雲映象倉庫 TCR 個人版 CCR 一鍵全量遷移至騰訊雲映象倉庫企業版 TCR。
本文首先介紹業務上雲/遷移過程中映象遷移的痛點。隨後詳細介紹映象批次遷移工具 image-transfer 的設計思想，功能模組以及最佳實踐。
工具已正式開源，專案地址：https://github.com/tkestack/image-transfer

二進位制包下載地址：https://github.com/tkestack/image-transfer/releases

## 業務上雲，映象怎麼遷移？

業務上雲主要有幾種場景，一是自建 idc 上雲，二是第三方雲遷移，三是異地災備，即混合雲。這些場景中，無論是上雲還是雲遷移，遷移流程主要有如下幾步。

1. 網路規劃。vpc 配置，子網劃分等。
2. 資料遷移。物件儲存，檔案儲存等。
3. 應用遷移。業務，配置等。

在資料遷移過程中，如果業務大量使用容器化部署，則需要批次映象遷移。而目前大部分雲廠商的映象倉庫服務沒有提供映象倉庫批次遷移的能力。業務想要遷移，只能先在本地下載原映象，修改 tag 後，再上傳至目的映象倉庫。這個過程存在以下幾個缺點：

- 耗時耗力。僅僅對於單個映象遷移，就需要三步操作，並且需要時刻盯著，若出現失敗情況，需進一步處理。
- 完全人肉操作，易出現差錯。在對原映象修改 tag 時，由於是人為修改，極易操作失誤，tag 修改錯了等。
- 映象量大時，成本增加，上雲進度緩慢。如果有幾百上千個映象，這樣人肉操作，遷移進度會十分緩慢，且遷移成本會大大增加。

## image-transfer 的原理

### 設計目標

針對映象遷移的痛點。我們希望開發一種映象批次遷移工具。它對使用者而言，只需要簡單的配置，就可以實現映象批次遷移，無需人工干預，提高業務上雲/遷移的進度，降低成本。具體而言，該工具有以下設計目標。

1. **配置簡單，無需複雜輸入**。我們希望對使用者而言這個工具是簡單易用的，僅需配置源、目的映象地址和鑑權，即可完成批次遷移。

2. **快速高效遷移海量映象，降低遷移成本**。針對大量的映象遷移需求，我們希望工具可以高效完成，藉助高併發的一些技術，實現快速遷移。

3. **一定的容錯能力，減少人工干預維護**。在遷移過程中，我們希望工具可以進行一些錯誤的識別和自動修復，儘量減少人工維護，提高運維效率。

4. **對執行環境沒有依賴，提高工具普適性**。我們希望工具是可以在任何 linux，mac os，windows 作業系統中執行，而不用依賴 docker 及其他程式。

5. **支援騰訊雲 CCR 一鍵全量遷移模式**。目前，騰訊雲容器映象服務 TCR 企業版正式上線，騰訊雲 TCR 個人版(CCR)將在未來逐步減少維護，直到下線。因此工具需要支援 CCR 倉庫一鍵全量遷移至 TCR 企業版。

6. 支援自定義 qps 限速。批次遷移映象，頻繁的呼叫映象倉庫介面有可能導致映象倉庫崩潰，因此需要對 qps 進行限制。

### 架構

image-transfer 由多個模組構成，下圖給出了 image-transfer 架構圖。

![](https://main.qcloudimg.com/raw/d33a0aaa649a1098daf486dbe4da1691.png)

- **通用模式輸入（預設）**：用於接受使用者下發的映象遷移任務。包括映象遷移配置檔案和鑑權配置檔案。該模式用於實現雲廠商之間的映象遷移。

- **CCR 一鍵遷移模式輸入**：需要在工具輸入引數新增 --ccrToTcr=true，該模式用於 CCR 倉庫一鍵全量遷移至 TCR 企業版。除了新增 --ccrToTcr=true 引數，還需鑑權配置檔案和騰訊雲 secret 配置檔案。

- **pipeline**：該模組是工具處理映象遷移的核心。負責處理使用者下發的映象遷移任務，包括根據遷移配置檔案處理映象倉庫的同步規則，以及進行映象的分層拉取和傳輸任務。模組採用了高併發的 pipeline 模型，提高遷移速度。

- 重試 task：這個階段會重試 pipeline 中傳輸失敗的任務。重試次數可根據使用者輸入引數而定，預設為 2 次。

### Pipeline

由於工具採用 golang 語言編寫，因此核心處理模組採用了 go 的 pipeline 高併發模型。整個 pipeline 模組分為三個小模組。

#### 多協程處理映象倉庫同步規則

這裡是對使用者輸入的映象遷移配置檔案進行處理解析，獲取每一個需要傳輸的源映象地址（包括 repo 和 tag），以及對應的目的映象地址。然後針對每個源映象地址和目的映象地址組成一個 job。如果映象配置檔案中沒有指定源映象的 tag，則會拉取該 repo 下的所有 tag，再針對每個 tag，組成一個 job。這個過程採用 golang 的多協程方式處理，增加處理速度。協程數量可由使用者在輸入引數指定 --proc，預設是 5 個。每個 job 組成後，會被放入task channel 中，等待被消費。

#### Task傳輸通道

task 通道可看作一個簡易中介軟體，由 golang 的 channel 實現，每個 job 被生產後，會被放入該 channel 中，等待被消費。該設計可以保證生產者生產出 job 就會立即被放入消費線，一旦消費端有空閒，即可進行消費處理。提高 job 處理效率。

#### 多協程處理 task

這些協程就是 job 的消費端。拿到 job 後，會首先拉去 job 中源地址的 manifest，判斷是否為多 manifest 映象，接著對每個 blob 進行拉取，再將 blob 傳輸到目的地址，最後再將 manifest 傳輸到目的地址，整個過程都是利用快取，資料不落盤，提高效率。這個過程採用 golang 的多協程方式處理，增加處理速度。協程數量可由使用者在輸入引數指定 --routines，預設是 5 個。

## 映象遷移最佳實踐

本節將介紹如何利用 image-transfer 工具，實現不同場景下的批次映象遷移。包含場景如下：

1. 不同雲廠商之間的映象遷移。例，從阿里雲映象倉庫 ACR 遷移到騰訊雲映象倉庫 TCR。

2. 開源/自建映象倉庫遷移上雲。例，從 harbor 映象倉庫遷移到騰訊雲映象倉庫 TCR。

3. 騰訊雲 TCR 個人版 (CCR) 一鍵遷移至騰訊雲映象倉庫企業版 TCR。

### 工具安裝：

首先對工具進行下載編譯，有兩種方式，一種是直接獲取二進位制檔案，第二種是下載原始碼編譯。

二進位制 release 包下載地址：

https://github.com/tkestack/image-transfer/releases

示例採用下載原始碼編譯進行演示：

編譯過程也非常簡單，進入原始碼目錄，直接 make。

```
git clone https://github.com/tkestack/image-transfer.git
cd ./image-transfer
make
```

編譯完成後，會在當前目錄生成 image-transfer 二進位制檔案。即可使用。接下來進行最佳實踐演示。

### 最佳實踐之場景一：不同雲廠商之間的映象遷移

以從阿里雲映象倉庫 ACR 遷移到騰訊雲映象倉庫 TCR 為例。

##### 1. 準備騰訊雲映象倉庫 TCR 以及阿里雲映象倉庫 ACR 的訪問憑證資訊檔案：auth.json

```
   grant-test.tencentcloudcr.com:
   username: xxx
   password: xxx
   grant-test2.tencentcloudcr.com:
   username: xxx
   password: xxx
   registry.cn-hangzhou.aliyuncs.com:
   username: xxx
   password: xxx
   ccr.ccs.tencentyun.com:
   username: xxx
   password: xxx
   registry.hub.docker.com:
   username: xxx
   password: xxx
```

配置很簡單，輸入需要訪問源映象倉庫地址，和目的映象倉庫地址。並輸入對應映象倉庫的使用者名稱和密碼即可。

其中 insecure 表示，registry 是否是 http 服務，如果是，insecure 欄位需要為 true，預設是 false，可選。

而目的映象倉庫的使用者需要擁有 push 以及建立倉庫許可權，如果沒有提供，則預設匿名訪問。

其中騰訊雲 TCR 訪問憑證如下方法獲取：
   ![image.png](https://main.qcloudimg.com/raw/692f2dff2c38753710c392439d128098.png)
阿里雲映象倉庫 ACR 的訪問憑證如下獲取：
   ![image.png](https://main.qcloudimg.com/raw/aa29af2cd75e4e3575a12f7fb2a66668.png)

##### 2. 準備好需要遷移的映象規則檔案：rule.yaml

```
registry.cn-hangzhou.aliyuncs.com/grantzhao/sichenzhao:xx": "grant-test.tencentcloudcr.com/grantzhao/sichenzhao
```

該檔案是配置需要傳輸的源映象和目的映象。檔案規則是：源映象地址: 目的映象地址
其中源映象地址，可以指定 tag，也可以不指定 tag，也可以指定多個 tag。
指定單個 tag 時：目的地址可以包含 tag，也可以不包含。不包含 tag 時則使用源映象的 tag。
不指定 tag 時：目的地址必須包含 tag。
指定多個 tag 時：多 tag 之間用英文逗號隔開，比如 grant-test.tencentcloudcr.com/grantzhao/sichenzhao:1.0,2.0,3.0。此時目的地址不能包含 tag，預設使用源地址的 tag。

##### 3. 執行工具

```
   ./image-transfer --routines=5 --securityFile=./security.yaml --ruleFile=./rule.yaml --ns=default \
   --registry=grant-test.tencentcloudcr.com --retry=2 --qps=100
```

引數解釋：

--ns 指定了一個預設的 ns，若目的倉庫的 ns 為空，則由該預設的 ns 代替。

--registry指定了一個預設的 registry，若目的倉庫的 registry 為空，則由該預設的 registry 代替。

--routines=5，表示設定併發數為 5。預設為 5。

--retry=2，表示失敗後的重試次數為 2，預設為 2。

--securityFile，指定鑑權檔案。

--ruleFile，指定映象倉庫配置檔案。

--qps，限制請求的 qps 不高於100/s。

##### 4. 執行結果

![](https://main.qcloudimg.com/raw/48f5c6d34b150a50ef561846ef0db325.png)
最後一行

```
################# Finished, 0 transfer jobs failed, 0 jobs generate failed #################
```

表示執行成功。

### 最佳實踐之場景二：開源/自建映象倉庫遷移上雲

以從開源映象倉庫 docker hub 遷移到騰訊雲映象倉庫 TCR 為例。

##### 1. 準備 docker hub 以及騰訊雲映象倉庫 TCR 的訪問憑證資訊檔案：security.yaml

```
   grant-test2.tencentcloudcr.com:
   username: xxx
   password: xxx
   registry.hub.docker.com:
   username: xxx
   password: xxx
```

##### 2. 準備好需要遷移的映象規則檔案：image.json

```
   sichenzhao/private-test:xxx": "grant-test2.tencentcloudcr.com/grantzhao/sichenzhao
```

##### 3. 執行工具

```
   ./image-transfer --routines=5 --securityFile=./security.yaml --ruleFile=./rule.yaml --ns=default \
   --registry=grant-test.tencentcloudcr.com --retry=2
```

##### 4. 執行結果

![](https://main.qcloudimg.com/raw/598b57f07c0b12f9ebd020fe79212dd4.png)
最後一行

```
################# Finished, 0 transfer jobs failed, 0 jobs generate failed #################
```

表示執行成功。

### 最佳實踐之場景三：騰訊雲 TCR 個人版(CCR)一鍵遷移至騰訊雲映象倉庫企業版 TCR

該場景下的使用方式和上面兩種場景稍有不同。主要表現為輸入引數的變化。

##### 1. 準備映象鑑權配置檔案 security.yaml

```
   grant-test.tencentcloudcr.com:
   username: xxx
   password: xxx
   grant-test2.tencentcloudcr.com:
   username: xxx
   password: xxx
   ccr.ccs.tencentyun.com:
   username: xxx
   password: xxx
```

##### 2. 準備騰訊雲 secret 配置檔案 secret.yaml

對於 TCR 的一鍵遷移模式，不需倉庫的使用者名稱和密碼作為訪問鑑權，而是透過騰訊雲的 secret 資訊。

```
   ccr:
   secretId: xxx
   secretKey: xxx
   tcr:
   secretId: xxx
   secretKey: xxx
```

注意：
檔案格式如上所示，只允許修改 secretId 和 secretKey 項。

如果沒有 ccr 的 secret 資訊，則會用 tcr 的代替。相反如果沒有 tcr 的 secret 資訊，也會用 ccr 的代替。

其中 secret 資訊按如下方式獲取：
   ![image.png](https://main.qcloudimg.com/raw/40fd14da866d23804afd7b822b2e2127.png)
   包含 secretid 和 secretkey 兩個資訊

##### 3. 執行工具

這裡的引數輸入與上面兩種場景略有區別。

```
   ./image-transfer --ccrToTcr=true --routines=5 --securityFile=./security.yaml --secretFile=./secret.yaml --tcrName=tcr-test \
   --retry=3 --tcrRegion=ap-guangzhou --ccrRegion=ap-guangzhou --qps=3000
```

引數解釋：

--ccrToTcr=true，表示開啟 TCR 一鍵全量遷移模式。

--secretFile，提供 secret.yaml 配置檔案。

--tcrName=tcr-test，指定目的 tcr 倉庫的名字。

--tcrRegion，指定目的 tcr 倉庫所在的地域。

--ccrRegion，指定源 ccr 倉庫所在的地域。

##### 4. 執行結果

![](https://main.qcloudimg.com/raw/aaf9e969ccf999e37e5f737b42623aa7.png)

一鍵批次遷移時間會很久，因為需要把 ccr 的全部映象傳輸到 tcr。

最後可以看到，有 16 個 job 失敗了。工具最後會列出失敗的 job 的源映象地址和目的映象地址。對於這些失敗的 job，去倉庫檢查後發現，這些 job 的 tag 是失效的。因此傳輸失敗。

## 總結

本文從問題分析，設計目標，原理解析，最佳實踐等方面詳細介紹了映象批次遷移工具：image-transfer。歡迎大家貢獻原始碼，也歡迎提 issue 需求。

映象批次遷移利器：image-transfer

相關文章