推送與提取映像檔

推送 (上傳) 和提取 (下載) 映像檔是兩項最常見的 Container Registry 工作。本文著重於說明如何使用 Docker 推送及拉取映像檔。

如果您使用 Cloud Build，請參閱 Cloud Build 說明文件，瞭解如何建構容器並推送至 Container Registry。

如需列出、標記及刪除映像檔的操作說明，請參閱管理映像檔。

事前準備

確認您已完成下列事項：

1. 在專案中啟用 Container Registry。

2. 已安裝及設定 Docker。

新增登錄檔

您可以將下列 Container Registry 登錄新增至專案：

第一次將圖片推送至主機名稱時，系統會在專案中建立註冊資料庫和相應的 Cloud Storage 儲存空間值區。這項初始推送作業需要專案層級的權限，才能建立儲存空間值區。

專案中只要有註冊主機，您就可以在儲存空間值區中設定權限，控管註冊中的圖片存取權。

如要新增登錄檔並設定權限，請按照下列步驟操作：

1. 請確認您具備必要權限。您必須具備「儲存空間管理員」角色 (roles/storage.admin)，或是具備相同權限的自訂角色或預先定義角色。

   如需在專案層級授予儲存空間管理員角色的操作說明，請參閱 身分與存取權管理說明文件。

2. 將初始映像檔推送至主機。例如，下列指令：

   • 從 Docker Hub 提取 busybox 映像檔
   • 在 Container Registry 中為映像檔加上目標路徑的標記，包括 gcr.io 註冊主機和專案 ID my-project
   • 將映像檔推送至登錄檔

   docker pull busybox
   docker tag busybox gcr.io/my-project/busybox
   docker push gcr.io/my-project/busybox
   

Container Registry 會將註冊資料庫新增至專案，為註冊資料庫建立儲存值區，並儲存映像檔。

您現在可以在登錄儲存體儲存空間中設定存取權控管，將登錄存取權授予其他使用者。

將映像檔推送至註冊資料庫

如要使用 Docker 或其他第三方工具將任何本機映像檔推送至 Container Registry，您必須先為映像檔加上註冊資料庫名稱的標記，接著再推送映像檔。

下列因素可能會影響大型圖片的上傳作業：

上傳時間

任何傳送至 Container Registry 的要求都會在 2 小時後逾時。如果您使用存取權杖驗證 Container Registry，權杖會在 60 分鐘後到期。如果上傳時間可能超過 60 分鐘，請使用其他驗證方法。

圖片大小

Container Registry 使用 Cloud Storage 做為每個存放區的基礎儲存空間，Cloud Storage 配額和限制適用於每個註冊項目，包括儲存空間中物件的 5 TB 大小上限。

Container Registry 不支援 Docker 分割上傳。部分工具支援使用區塊上傳或單一巨塊上傳上傳大型圖片。您必須使用單體上傳功能，才能將圖片推送至 Container Registry。

所需權限

如要推送圖片，您必須具備下列其中一個 Cloud Storage 角色，或具備相同權限的角色：

將第一個映像檔推送至專案中的註冊資料庫

角色：Google Cloud 專案層級的「Storage 管理員」(roles/storage.admin)。預先定義的「Owner」角色包含這些權限。

當您第一次將映像檔推送至專案中的註冊主機 (例如 gcr.io) 時，Container Registry 會為註冊機制建立儲存空間值區。「儲存空間管理員」角色具備建立儲存空間值區的必要權限。

將圖片推送至專案中現有的註冊資料庫

角色：在登錄儲存體值區上執行 Storage 舊版值區寫入者 (roles/storage.legacyBucketWriter)。

這個角色具備權限，可為專案中現有的登錄主機推送及拉取映像檔。舉例來說，如果您的專案只包含 gcr.io 登錄表，則具有「Storage 舊版值區」寫入者角色的使用者可以將圖片推送至 gcr.io，但無法推送至 asia.gcr.io。

如要進一步瞭解如何授予登錄檔權限，請參閱「設定存取權控管」。

為本機映像檔加上註冊資料庫名稱的標記

如何標記圖片：

1. 確認您已為 Container Registry 設定驗證。

2. 決定 Container Registry 中的映像檔名稱：

   1. 選擇主機名稱，主機名稱會指定圖片的儲存位置。

      • gcr.io 代管位在美國的資料中心中的映像檔，但此位置日後可能會改變
      • us.gcr.io 代管位於美國資料中心的映像檔，使用的儲存空間值區與 gcr.io 代管的映像檔不同
      • eu.gcr.io 代管位在歐盟的映像檔
      • asia.gcr.io 在亞洲資料中心代管映像檔

      這些位置對應至 Cloud Storage 儲存值區的多區域。將映像檔推送至使用新主機名稱的註冊資料庫時，Container Registry 會在指定的多地區位置建立儲存空間值區。這個值區是註冊資料庫的基礎儲存空間，在專案中，主機名稱相同的所有註冊資料庫會共用一個儲存空間值區。

      在主控台中，映像檔的主機名稱列在「位置」底下。

   2. 選擇目標映像檔名稱，此名稱可以和本機電腦上的映像檔名稱不同。舉例來說，本機映像檔可能會稱為 web-image，但您想將其儲存在 Container Registry 中，並命名為 web-site

   3. 將主機名稱、您在 Google Cloud 主控台的專案 ID 和目標映像檔名稱組合起來：

      HOSTNAME/PROJECT-ID/TARGET-IMAGE
      

      請見如下範例：

      • 主機名稱：gcr.io
      • Google Cloud project: my-project
      • 目標映像檔名稱：web-site

      將主機名稱、專案和目標映像檔名稱組合起來，即可取得用於標記的完整映像檔路徑：

      gcr.io/my-project/web-site

      如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。

3. 為本機映像檔加上上一個步驟中的名稱標記。如果您想為此圖片版本加上標記，請加入標記名稱。

   docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG
   

   更改下列內容：

   • SOURCE_IMAGE 是本機映像檔名稱或映像檔 ID。
   • HOSTNAME 是您在步驟 2 中選擇的註冊主機。
   • PROJECT 是 Google Cloud 專案 ID。
   • TARGET-IMAGE 是儲存在 Container Registry 中的映像檔名稱。
   • TAG 是您要與此圖片版本建立關聯的標記。

   舉例來說，這個指令會在 Container Registry 中將本機映像檔 web-image 標記為 gcr.io/my-project/web-site，並加上標記 v1.5

   docker tag web-image gcr.io/my-project/web-site:v1.5
   

   如果您沒有指定標記，Docker 會新增預設的 latest 標記。由於 latest 是預設標記，因此它代表最近加上 latest 標記的圖片版本，不一定是圖片的最新版本。

Docker 會使用您在指令中指定的映像檔名稱和標記，為映像檔加上標記。

將加上標記的映像檔推送至 Container Registry

1. 確認您已為 Container Registry 設定驗證。

2. 將加上標記的映像檔推送至 Container Registry：

   執行下列指令，推送具有特定標記的映像檔：

   docker push HOSTNAME/PROJECT-ID/IMAGE:TAG
   

   如果省略 :TAG，Docker 會推送標記為 latest 的映像檔版本。

   舉例來說，下列指令會推送標記為 v1.5 的 gcr.io/my-project/web-site 映像檔：

   docker push gcr.io/my-project/web-site:v1.5
   

將映像檔推送至專案中不存在的註冊主機時，Container Registry 會為註冊主機建立儲存空間值區。

如要查看您推送的圖片，請按照下列步驟操作：

• 前往 Google Cloud 主控台查看註冊資料庫和映像檔。

• 執行 gcloud container images list-tags 以查看圖片代碼和自動產生的摘要：

  gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE
  

  此指令會輸出類似以下的結果：

  DIGEST        TAGS        TIMESTAMP
  44bde...      test        2017-..-..
  

從註冊資料庫提取映像檔

提取映像檔時，您必須具備 Storage 物件檢視者角色 (適用於 Registry 儲存空間值區)，或是具備相同權限的角色。

如要從 Container Registry 執行提取作業，請執行下列指令：

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

或

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

其中：

• HOSTNAME 列在控制台的「位置」下，為以下四個選項的其中之一：gcr.io、us.gcr.io、eu.gcr.io 或 asia.gcr.io。
• PROJECT-ID 是您的 Google Cloud 主控台專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
• IMAGE 是 Container Registry 中的映像檔名稱。
• TAG 是套用至映像檔的標記。在註冊資料庫中，每個映像檔所套用的標記均不會重複。
• IMAGE_DIGEST 是映像檔內容的 sha256 雜湊值。在 Google Cloud 控制台中，按一下特定圖片，即可查看該圖片的中繼資料。摘要會列為「映像檔摘要」。

如要執行特定映像檔的提取指令：

1. 按一下映像檔名稱，即可前往特定的註冊資料庫。

2. 在註冊資料庫中，找出您要提取的映像檔版本，然後勾選旁邊的方塊。

3. 按一下頁面頂端的 [顯示提取指令]。

4. 複製提取指令，這項指令可使用標記或摘要來識別映像檔。

後續步驟

• 瞭解如何管理映像檔，包含新增或移除標記及刪除映像檔等作業在內。
• 瞭解如何設定存取權控管。
• 進一步瞭解 Container Registry 的元件和功能。
• 如果要在 Compute Engine 上執行容器，請進一步瞭解 Compute Engine 上的容器。