## 為什麼要做這個工具？

由於阿里雲上的容器服務 ACK 在使用成本、運維成本、方便性、長期穩定性上大大超過公司自建自維護 Kubernets 叢集，有不少公司紛紛想把之前自己維護 Kubernetes 負載遷移到阿里雲 ACK 服務上。在遷移過程中，往往會碰到一個不大不小的坑：那就是怎麼把已有的容器映象平滑的遷移到阿里雲映象服務 ACR 上。這個問題看起來非常簡單，如果只有三五個映象，只要做一次 docker pull/docker push 就能完成，但實際生產中涉及到成千上百個映象，幾 T 的映象倉庫資料時，遷移過程就變的耗時非常漫長，甚至丟失資料。

阿里云云原生應用平臺的工程師——也就是我們，發現這是一個通用的需求，使用者會在各種容器映象倉庫之間做遷移，或者進一步，期望有同步複製的能力，所以我們研發了 image-syncer 這個專案來支援遷雲，並同時開源給業界大眾，用來解決通用的容器映象批次遷移/同步的問題。

這個工具在實際生產中，已經幫助了多家客戶進行映象遷移，其中最大映象倉庫的總量達到 3T 以上，同步時能跑滿機器頻寬，進行同步任務的機器磁碟容量沒有要求。

## image-syncer 簡介

如上所述，在 k8s 叢集遷移場景中，映象倉庫之間進行映象遷移/同步是基本需求，而使用 docker pull/push 結合指令碼的傳統方式進行映象同步，有如下幾個侷限性：

1. 依賴磁碟儲存，需要及時進行本地映象的清理，並且落盤造成多餘的時間開銷，難以勝任生產場景中大量映象的遷移

1. 依賴 docker 程式，docker daemon 對 pull/push 的併發數進行了嚴格的限制，無法進行高併發同步

1. 一些功能只能透過 HTTP api 進行操作，單純使用 docker cli 無法做到，使指令碼變得複雜

image-syncer 的定位是一個簡單、易用的批次映象遷移/同步工具，支援幾乎所有目前主流的基於 docker registry V2 搭建的映象儲存服務，比如 ACR、Docker

Hub、Quay、自建 Harbor 等，目前已經初步經過了 TB 級別的生產環境映象遷移驗證，並開源於 [https://github.com/AliyunContainerService/image-syncer ](https://github.com/AliyunContainerService/image-syncer)，歡迎大家下載使用以及提供寶貴的建議～

## 工具特性

image-syncer 的特性如下：

1.支援多對多映象倉庫同步

2.支援基於 Docker Registry V2 搭建的 docker 映象倉庫服務 (如 Docker Hub、 Quay、 阿里雲映象服務 ACR、 Harbor等)

3.同步只經過記憶體和網路，不依賴磁碟儲存，同步速度快

4.增量同步, 透過對同步過的映象 blob 資訊落盤，不重複同步已同步的映象

5.併發同步，可以透過配置檔案調整併發數

6.自動重試失敗的同步任務，可以解決大部分映象同步中的網路抖動問題

7.不依賴 docker 以及其他程式

藉助 image-syncer，只需要保證 image-syncer 的執行環境與需要同步的 registry 網路連通，你可以快速地完成從映象倉庫的遷移、複製以及增量同步，並且對硬體資源幾乎沒有要求（因為 image-syncer 嚴格控制網路連線數目=併發數，所以只有在當單個映象層過大的情況下，併發數目過大可能會打滿記憶體，記憶體佔用 <= 併發數 x 最大映象層大小）；除了使用重傳機制規避同步過程中可能出現的偶發問題之外， image-syncer 會在執行結束時統計最後同步失敗的映象個數，並且列印出詳細的日誌，幫助使用者定位同步過程中出現的問題。

## 使用指南

image-syncer 執行，只需要使用者提供一個配置檔案，內容如下：

```

{

"auth": {                   // 認證欄位，其中每個物件為一個registry的一個賬號和

// 密碼；通常，同步源需要具有pull以及訪問tags許可權，

// 同步目標需要擁有push以及建立倉庫許可權，如果沒有提供，則預設匿名訪問

"quay.io": {            // registry的url，需要和下面images中對應registry的url相同

"username": "xxx",               // 使用者名稱，可選

"password": "xxxxxxxxx",         // 密碼，可選

"insecure": true                 // registry是否是http服務，如果是，insecure 欄位需要為true，預設是false，可選，支援這個選項需要image-syncer版本 > v1.0.1

},

"registry.cn-beijing.aliyuncs.com": {

"username": "xxx",

"password": "xxxxxxxxx"

},

"registry.hub.docker.com": {

"username": "xxx",

"password": "xxxxxxxxxx"

}

},

"images": {

// 同步映象規則欄位，其中條規則包括一個源倉庫（鍵）和一個目標倉庫（值）

// 同步的最大單位是倉庫（repo），不支援透過一條規則同步整個namespace以及registry

// 源倉庫和目標倉庫的格式與docker pull/push命令使用的映象url類似（registry/namespace/repository:tag）

// 源倉庫和目標倉庫（如果目標倉庫不為空字串）都至少包含registry/namespace/repository

// 源倉庫欄位不能為空，如果需要將一個源倉庫同步到多個目標倉庫需要配置多條規則

// 目標倉庫名可以和源倉庫名不同（tag也可以不同），此時同步功能類似於：docker pull + docker tag + docker push

"quay.io/coreos/kube-rbac-proxy": "quay.io/ruohe/kube-rbac-proxy",

"xxxx":"xxxxx",

"xxx/xxx/xx:tag1,tag2,tag3":"xxx/xxx/xx"

// 當源倉庫欄位中不包含tag時，表示將該倉庫所有tag同步到目標倉庫，此時目標倉庫不能包含tag

// 當源倉庫欄位中包含tag時，表示只同步源倉庫中的一個tag到目標倉庫，如果目標倉庫中不包含tag，則預設使用源tag

// 源倉庫欄位中的tag可以同時包含多個（比如"a/b/c:1,2,3"），tag之間透過","隔開，此時目標倉庫不能包含tag，並且預設使用原來的tag

// 當目標倉庫為空字串時，會將源映象同步到預設registry的預設namespace下，並且repo以及tag與源倉庫相同，預設registry和預設namespace可以透過命令列引數以及環境變數配置，參考下面的描述

}

```

使用者可以根據配置不同的映象同步規則組合，以匹配不同的遷移/同步需求，如將單個映象 repo 同步到多個不同的映象 repo、將多個源映象同步到單個映象 repo 中（以 tag 區分）、在同一個 registry 中以不同的名字複製一個映象 repo 等等。

使用時需要注意，如果匿名訪問作為同步源的 registry 地址，可能存在許可權問題無法 pull 映象以及無法獲取 tags，這種情況下需要在" auth "中加入有對應許可權的賬號密碼；而如果匿名訪問作為同步目標的 registry 地址，可能存在許可權問題無法 push 映象，同樣也可能需要使用者提供有對應許可權的賬號密碼。

image-syncer 同時支援 insecure 的 registry（類比 docker 的-- insecure - registry 引數，在" auth "的相應條目中新增 " insecure ": true ），可以同時在 http 和 https 兩種型別的映象服務之間遷移。

image-syncer 還提供了一些簡單的引數來控制程式的執行，包括併發數目控制、重傳次數設定等等：

```

-h  --help       使用說明，會列印出一些啟動引數的當前預設值

--config     設定使用者提供的配置檔案所在路徑，使用之前需要建立配置檔案，預設為當前工作目錄下的image-syncer.json檔案

--log        列印出來的log檔案路徑，預設列印到標準錯誤輸出，如果將日誌列印到檔案將不會有命令列輸出，此時需要透過cat對應的日誌檔案檢視

--namespace  設定預設的目標namespace，當配置檔案內一條images規則的目標倉庫為空，並且預設registry也不為空時有效，可以透過環境變數DEFAULT_NAMESPACE設定，同時傳入命令列引數會優先使用命令列引數值

--registry   設定預設的目標registry，當配置檔案內一條images規則的目標倉庫為空，並且預設namespace也不為空時有效，可以透過環境變數DEFAULT_REGISTRY設定，同時傳入命令列引數會優先使用命令列引數值

--proc       併發數，進行映象同步的併發goroutine數量，預設為5

--records    指定傳輸過程中儲存已傳輸完成映象資訊（blob）的檔案輸出/讀取路徑，預設輸出到當前工作目錄，一個records記錄了對應目標倉庫的已遷移資訊，可以用來進行連續的多次遷移（會節約大量時間，但不要把之前自己沒執行過的records檔案拿來用），如果有unknown blob之類的錯誤，可以刪除該檔案重新嘗試

--retries    失敗同步任務的重試次數，預設為2，重試會在所有任務都被執行一遍之後開始，並且也會重新嘗試對應次數生成失敗任務的生成。一些偶爾出現的網路錯誤比如io timeout、TLS handshake timeout，都可以透過設定重試次數來減少失敗的任務數量

```

在同步結束之後，`image-syncer`

會統計成功和失敗的同步任務數目（每個同步任務代表一個映象），並在標準輸出和日誌中列印 "Finished, <number of="" failed="" tasks=""> sync tasks failed, <number of="" generated="" failed="" tasks=""> tasks generate failed" 的字樣，從而可以獲得同步的結果。更多FAQ參見 [FAQs.md](https://github.com/AliyunContainerService/image-syncer/blob/master/FAQs.md)

## 使用示例

ACR（Alibaba Cloud Container Registry）是阿里雲提供的容器映象託管服務，支援全球20個地域的映象全生命週期管理，聯合容器服務等雲產品，打造雲原生應用的一站式體驗。這裡透過將自建 harbor 上的映象同步到 ACR，提供 image-syncer 的基本使用示例

### 從自建 harbor 同步映象到 ACR

1.在阿里雲控制檯上開通容器映象服務，並進入 ACR 控制檯

2.[建立名稱空間](https://help.aliyun.com/document_detail/60765.html?spm=a2c4g.11186623.6.553.f2721edfqdXsJv)，預設倉庫型別決定了當倉庫不存在時，docker push 自動建立的倉庫型別是公有的還是私有的；如果部分需要同步的目標倉庫不存在，需要開啟自動建立倉庫按鈕，讓類似" docker push "的操作能自動建立倉庫

3.建立訪問憑證，對應的賬號即為 docker login 的賬號，如下圖：

![1](https://yqfile.alicdn.com/3fee57c42f5f71c00e88e4039d1b9e7098c422fd.png)

4.上面的操作使用的是主賬號，預設擁有全部許可權；為了進行許可權管理，我們也可以透過[建立 RAM 子賬號](https://help.aliyun.com/document_detail/28672.html?spm=5176.11065259.1996646101.searchclickresult.3fd135d9aGvjm7&aly_as=NB76IejD)，並[配置對應許可權](https://help.aliyun.com/document_detail/67992.html?spm=a2c4g.11186623.6.555.278e6b70q7equN)，這裡的場景中我們只使用到了建立、更新映象倉庫相關許可權，最小許可權設定如下，訪問控制的資源粒度為 image-syncer 名稱空間:

```

{

"Statement": [

{

"Effect": "Allow",

"Action": [

"cr:CreateRepository",

"cr:UpdateRepository",

"cr:PushRepository",

"cr:PullRepository"

],

"Resource": [

"acs:cr:*:*:repository/image-syncer/*"

]

}

],

"Version": "1"

}

```

5.同樣，RAM 賬號需要透過[ RAM 使用者登陸入口](https://signin.aliyun.com/login.htm)登陸阿里雲控制檯，並進入 ACR 控制檯建立訪問憑證（同3.）

6.然後我們可以透過訪問憑證中建立的密碼，完成如下 image-syncer 的同步配置（配置中使用 RAM 子賬號的訪問憑證）；這裡我們將本地搭建的 harbor（ http 服務，要設定 insecure，透過 harbor.myk8s.paas.com:32080 訪問）中的 library/nginx 倉庫同步到華北2（透過為 registry.cn-beijing.aliyuncs.com 訪問）中的 image-syncer 名稱空間下，並且保持倉庫名稱為 nginx，config.json 如下：

```

{

"auth": {

"harbor.myk8s.paas.com:32080": {

"username": "admin",

"password": "xxxxxxxxx",

"insecure": true

},

"registry.cn-beijing.aliyuncs.com": {

"username": "acr_pusher@1938562138124787",

"password": "xxxxxxxx"

}

},

"images": {

"harbor.myk8s.paas.com:32080/library/nginx": ""

}

```

7.下載[最新的 image-syncer 可執行檔案](https://github.com/AliyunContainerService/image-syncer/releases/latest)（目前只支援 linux amd64 版本，可以[自行編譯](https://github.com/AliyunContainerService/image-syncer#compile-manually)），解壓，並執行工具

執行命令：

```

# 設定預設目標registry為registry.cn-beijing.aliyuncs.com，預設目標namespace為image-syncer

# 併發數為10，重試次數為10

# 日誌輸出到./log檔案下，不存在會自動建立，不指定的話預設會將日誌列印到Stderr

# 指定配置檔案為harbor-to-acr.json，內容如上所述

./image-syncer --proc=10 --config=./harbor-to-acr.json --registry=registry.cn-beijing.aliyuncs.com --namespace=image-syncer --retries=10 --log=./log

```

一次同步會經歷三個階段：生成同步任務、執行同步任務以及重試失敗任務；其中，每個同步任務都代表了一個需要同步的 tag （映象），如果配置檔案中某條規則沒有指定 tag，在“生成同步任務”階段會自動 list 源倉庫所有 tag，並生成對應的同步任務，如果生成同步任務失敗，也會在重試階段進行重試，（故意配錯賬號密碼時）執行輸出如下：

![2](https://yqfile.alicdn.com/627442bc3f74ab769b1203d578ffff23bf12cb5d.png)

正常執行的輸出：

![3](https://yqfile.alicdn.com/26861e28725e714972d71e25bbf57abe3a4fb502.png)

在執行時，image-syncer 會列印出如下的日誌資訊：

![4](https://yqfile.alicdn.com/653e81facc3d8ba552a336c7b7952e14a71c5e5b.png)

### 從自建 harbor 同步映象到 ACR 企業版

ACR 企業版提供企業級容器映象、Helm Chart 安全託管能力，擁有企業級安全獨享特性，具備千節點映象分發、全球多地域同步能力。提供雲原生應用交付鏈，實現一次應用變更，全球化多場景自動交付。強烈推薦安全需求高、業務多地域部署、擁有大規模叢集節點的企業級客戶使用。

同步到 ACR 企業版和 ACR 普通版所需的操作基本相同：

1.[建立 ACR 企業版例項](https://help.aliyun.com/document_detail/142168.html?spm=a2c4g.11186623.6.559.27134eca5Fjx7S)

2.建立名稱空間，並對預設倉庫型別進行設定，並開啟自動建立倉庫的功能

3.[配置公網的訪問控制](https://help.aliyun.com/document_detail/142246.html?spm=a2c4g.11186623.6.562.72853b6690SVgI)，需要開啟 ACR 企業版的訪問入口，並新增公網白名單，使外部能訪問映象服務

4.[配置訪問憑證](https://help.aliyun.com/document_detail/142247.html?spm=a2c4g.11186623.6.564.51bf37a5W2ceHc)，這部分和 ACR 普通版相同

5.使用訪問憑證中建立的密碼，完成如下 image-syncer 的同步配置；與之前同步到ACR共享版不同的是，每個ACR企業版例項有自己單獨的域名（一個公網可見，一個僅專有網路可見，如果映象同步工具執行在個人環境上需要使用公網域名；如果要使用僅專有網路可見的域名，則將映象同步工具執行在阿里雲ECS例項上，並且透過配置使域名對該ECS所在的專有網路可見；這裡使用的是公網域名

ruohe-test-registry.cn-shanghai.cr.aliyuncs.com），並且namespace對於每個不同企業版例項之間來說都是隔離的。我們同樣將本地搭建的 harbor（http 服務，要設定i nsecure，透過 harbor.myk8s.paas.com:32080 訪問）中的 library/nginx 倉庫同步到 ACR 企業版例項中 image-syncer 名稱空間下，並且保持倉庫名稱為 nginx，config.json 如下：

```

{

"auth": {

"harbor.myk8s.paas.com:32080": {

"username": "admin",

"password": "xxxxxxxxx",

"insecure": true

},

"ruohe-test-registry.cn-shanghai.cr.aliyuncs.com": {

"username": "ruohehhy",

"password": "xxxxxxxx"

}

},

"images": {

"harbor.myk8s.paas.com:32080/library/nginx": ""

}

```

6.執行工具

執行命令

```

# 設定預設目標registry為ruohe-test-registry.cn-shanghai.cr.aliyuncs.com，預設目標namespace為image-syncer

# 併發數為10，重試次數為10

# 日誌輸出到./log檔案下，不存在會自動建立，不指定的話預設會將日誌列印到Stderr

# 指定配置檔案為harbor-to-acr.json，內容如上所述

./image-syncer --proc=10 --config=./harbor-to-acr.json --registry=ruohe-test-registry.cn-shanghai.cr.aliyuncs.com --namespace=image-syncer --retries=10

```

輸出與前述相同

## 更多能力

以上的 image-syncer 滿足了你的容器映象遷移同步的所有訴求嗎？如果有更多的需求、甚至想共建更多的能力，歡迎訪問 [https://github.com/AliyunContainerService/image-syncer](https://github.com/AliyunContainerService/image-syncer) 留下 issue，也歡迎加入 Kubernetes 釘釘群討論

![5](https://yqfile.alicdn.com/c34156f3751d43a47854f6b55d0a72077442f161.png)

【 Kubernetes 釘釘群二維碼】

開源不易，長期的維護專案更不容易，大家覺得好就請給這個專案點個 star，公司內的老闆會看這個專案的 star 數量來決定後續能不能投更多的研發資源來維護這個專案，萬分感謝:)

## One More Thing

那麼，映象倉庫能順利遷移，是否遷雲就能順利進行呢？答案是——並沒有那麼簡單，倉庫只是遷雲過程中碰到的問題之一，還需要解決其他痛點。

對於已經在私有云/公有云上已經把業務應用跑在 k8s 上的使用者來說，如何讓業務在遷雲過程中不受影響是頭等大事。阿里云云原生應用平臺的解決方案架構師對此已經有了完善的考慮，力助使用者應用高效穩定的遷移到 ACK 服務上。在幫助這些使用者落實遷雲方案的同時，我們也在不斷思考如何把這些案例中的共性的東西做一些沉澱，總結出一些優秀的解決方案、最佳實踐以及開發一些工具來幫助使用者快速完成遷雲的這件事情，這是我們遷移過程中為使用者考慮到的點

![6](https://yqfile.alicdn.com/3378b53ecbe4c47007cf82119e204f8b0632cc26.png)

**如果你有遷移上阿里雲 ACK 的需求，**[**請點選我**](https://page.aliyun.com/form/act1492824539/index.htm)**！期待你的留言～**

</number></number>

阿里雲開源 image-syncer 工具，容器映象遷移同步的終極利器

相關文章