阿里雲開源 image-syncer 工具，容器映象遷移同步的終極利器
為什麼要做這個工具？
由於阿里雲上的容器服務 ACK 在使用成本、運維成本、方便性、長期穩定性上大大超過公司自建自維護 Kubernets 叢集，有不少公司紛紛想把之前自己維護 Kubernetes 負載遷移到阿里雲 ACK 服務上。在遷移過程中，往往會碰到一個不大不小的坑：那就是怎麼把已有的容器映象平滑的遷移到阿里雲映象服務 ACR 上。這個問題看起來非常簡單，如果只有三五個映象，只要做一次 docker pull/docker push 就能完成，但實際生產中涉及到成千上百個映象，幾 T 的映象倉庫資料時，遷移過程就變的耗時非常漫長，甚至丟失資料。
阿里云云原生應用平臺的工程師——也就是我們，發現這是一個通用的需求，使用者會在各種容器映象倉庫之間做遷移，或者進一步，期望有同步複製的能力，所以我們研發了 image-syncer 這個專案來支援遷雲，並同時開源給業界大眾，用來解決通用的容器映象批量遷移/同步的問題。
這個工具在實際生產中，已經幫助了多家客戶進行映象遷移，其中最大映象倉庫的總量達到 3T 以上，同步時能跑滿機器頻寬，進行同步任務的機器磁碟容量沒有要求。
image-syncer 簡介
如上所述，在 k8s 叢集遷移場景中，映象倉庫之間進行映象遷移/同步是基本需求，而使用 docker pull/push 結合指令碼的傳統方式進行映象同步，有如下幾個侷限性：
- 依賴磁碟儲存，需要及時進行本地映象的清理，並且落盤造成多餘的時間開銷，難以勝任生產場景中大量映象的遷移
- 依賴 docker 程式，docker daemon 對 pull/push 的併發數進行了嚴格的限制，無法進行高併發同步
- 一些功能只能通過 HTTP api 進行操作，單純使用 docker cli 無法做到，使指令碼變得複雜
image-syncer 的定位是一個簡單、易用的批量映象遷移/同步工具，支援幾乎所有目前主流的基於 docker registry V2 搭建的映象儲存服務，比如 ACR、Docker
Hub、Quay、自建 Harbor 等，目前已經初步經過了 TB 級別的生產環境映象遷移驗證，並開源於 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,
使用示例
ACR（Alibaba Cloud Container Registry）是阿里雲提供的容器映象託管服務，支援全球20個地域的映象全生命週期管理，聯合容器服務等雲產品，打造雲原生應用的一站式體驗。這裡通過將自建 harbor 上的映象同步到 ACR，提供 image-syncer 的基本使用示例
從自建 harbor 同步映象到 ACR
1.在阿里雲控制檯上開通容器映象服務，並進入 ACR 控制檯
2.建立名稱空間，預設倉庫型別決定了當倉庫不存在時，docker push 自動建立的倉庫型別是公有的還是私有的；如果部分需要同步的目標倉庫不存在，需要開啟自動建立倉庫按鈕，讓類似" docker push "的操作能自動建立倉庫
3.建立訪問憑證，對應的賬號即為 docker login 的賬號，如下圖：
4.上面的操作使用的是主賬號，預設擁有全部許可權；為了進行許可權管理，我們也可以通過建立 RAM 子賬號，並配置對應許可權，這裡的場景中我們只使用到了建立、更新映象倉庫相關許可權，最小許可權設定如下，訪問控制的資源粒度為 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 使用者登陸入口登陸阿里雲控制檯，並進入 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 可執行檔案（目前只支援 linux amd64 版本，可以自行編譯），解壓，並執行工具
執行命令：
# 設定預設目標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，並生成對應的同步任務，如果生成同步任務失敗，也會在重試階段進行重試，（故意配錯賬號密碼時）執行輸出如下：
正常執行的輸出：
在執行時，image-syncer 會打印出如下的日誌資訊：
從自建 harbor 同步映象到 ACR 企業版
ACR 企業版提供企業級容器映象、Helm Chart 安全託管能力，擁有企業級安全獨享特性，具備千節點映象分發、全球多地域同步能力。提供雲原生應用交付鏈，實現一次應用變更，全球化多場景自動交付。強烈推薦安全需求高、業務多地域部署、擁有大規模叢集節點的企業級客戶使用。
同步到 ACR 企業版和 ACR 普通版所需的操作基本相同：
1.建立 ACR 企業版例項
2.建立名稱空間，並對預設倉庫型別進行設定，並開啟自動建立倉庫的功能
3.配置公網的訪問控制，需要開啟 ACR 企業版的訪問入口，並新增公網白名單，使外部能訪問映象服務
4.配置訪問憑證，這部分和 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 留下 issue，也歡迎加入 Kubernetes 釘釘群討論
【 Kubernetes 釘釘群二維碼】
開源不易，長期的維護專案更不容易，大家覺得好就請給這個專案點個 star，公司內的老闆會看這個專案的 star 數量來決定後續能不能投更多的研發資源來維護這個專案，萬分感謝:)
One More Thing
那麼，映象倉庫能順利遷移，是否遷雲就能順利進行呢？答案是——並沒有那麼簡單，倉庫只是遷雲過程中碰到的問題之一，還需要解決其他痛點。
對於已經在私有云/公有云上已經把業務應用跑在 k8s 上的使用者來說，如何讓業務在遷雲過程中不受影響是頭等大事。阿里云云原生應用平臺的解決方案架構師對此已經有了完善的考慮，力助使用者應用高效穩定的遷移到 ACK 服務上。在幫助這些使用者落實遷雲方案的同時，我們也在不斷思考如何把這些案例中共性的東西做一些沉澱，總結出一些優秀的解決方案、最佳實踐以及開發一些工具來幫助使用者快速完成遷雲的這件事情，這是我們遷移過程中為使用者考慮到的點
如果你有遷移上阿里雲 ACK 的需求，請點選我！期待你的留言