Docker 異動

本文將說明 Container Registry 和 Artifact Registry 在使用 Docker 驗證、推送及提取容器映像檔時的差異。

本指南的比較重點是 pkg.dev Artifact Registry 存放區，這是與 Container Registry 無關的一般 Artifact Registry 存放區，可支援所有 Artifact Registry 功能。

如果您的管理員設定了支援 gcr.io 網域的存放區，系統就會自動將對 gcr.io 主機名稱的請求重新導向至對應的 Artifact Registry 存放區。如要使用在 Artifact Registry 中代管的 gcr.io 存放區，您必須具備適當的 Artifact Registry 角色或具備等同權限的角色。

如要瞭解使用 Cloud Build 建構及部署至 Cloud Run 或 Google Kubernetes Engine 時，Container Registry 和 Artifact Registry 之間的差異，請參閱「Cloud Build、Cloud Run 和 GKE 的變更」。

您可以利用這項資訊，調整現有的 Docker 相關指令、設定或說明文件，以便搭配 Container Registry 使用。

事前準備

本文假設您已具備下列條件：

  1. 在專案中啟用 Artifact Registry。
  2. 安裝 Docker。Cloud Shell 已包含 Docker。

總覽

大致來說，在 Container Registry 或 Artifact Registry 中使用 Docker 的工作流程是一樣的。

Container Registry Artifact Registry
管理員
  1. 啟用 Container Registry API
  2. 將初始映像檔推送至主機，新增註冊主機 (例如 `gcr.io`)。
  3. 授予儲存空間值區的 Cloud Storage 角色，讓註冊主機提供圖片存取權。
 管理員
  1. 啟用 Artifact Registry API
  2. 新增 Docker 存放區。
  3. 授予 Artifact Registry 角色，提供映像檔存取權。
註冊使用者
  1. 將圖片定義為 Dockerfile 檔案。
  2. 建構映像檔。
  3. 向登錄表進行驗證。
  4. 將圖片加上標記並推送至登錄檔。
  5. 從註冊資料庫提取映像檔，或將映像檔部署至 Google Cloud 執行階段。
 註冊使用者
  1. 將圖片定義為 Dockerfile 檔案。
  2. 建構映像檔。
  3. 向登錄表進行驗證。
  4. 將映像檔加上標記並推送至登錄檔。
  5. 從註冊資料庫提取映像檔，或將映像檔部署至 Google Cloud 執行階段。

不過，Container Registry 的捷徑會將管理員和使用者角色合併為單一工作流程。這個捷徑常見於：

  • 快速入門導覽課程和教學課程，適用於您在擁有廣泛權限的環境中進行測試的情況。
  • 使用 Cloud Build 的工作流程，因為 Cloud Build 服務帳戶具備在相同專案中新增登錄主機的權限。 Google Cloud

捷徑工作流程如下所示：

  1. 啟用 Container Registry API。
  2. 授予將存取 Container Registry 的帳戶權限。

  3. 向登錄表進行驗證。最簡單的驗證選項，就是在 Google Cloud CLI 中使用 Docker 憑證輔助程式。這是一次性的設定步驟。

    gcloud auth configure-docker

  4. 建構並標記映像檔。舉例來說，下列指令會建構並標記映像檔 gcr.io/my-project/my-image:tag1：

    docker build -t gcr.io/my-project/my-image:tag1

  5. 將映像檔推送至登錄檔。例如：

    docker push gcr.io/my-project/my-image:tag1

    如果專案中沒有 gcr.io 登錄主機，Container Registry 會在上傳映像檔前新增主機。

  6. 從註冊資料庫提取映像檔，或將映像檔部署至 Google Cloud 執行階段。例如：

    docker pull gcr.io/my-project/my-image:tag1

這個工作流程需要使用下列捷徑：

  • 推送圖片的帳戶具有「儲存空間管理員」角色，或具備相同權限的角色，例如「擁有者」。這個角色的廣泛權限可讓使用者讀取及寫入專案中的所有儲存空間值區，包括 Container Registry 未使用的值區。
  • 啟用 部分 Google Cloud API 時，Container Registry API 會自動啟用。也就是說，這些服務的使用者可在同一個專案中隱含存取 Container Registry。舉例來說，可在 Cloud Build 中執行建構作業的使用者，可以將映像檔推送至登錄，並根據預設新增登錄主機。

在 Artifact Registry 中，管理員和存放區使用者角色明確分開，可變更建構和部署工作流程中的步驟。如要為 Artifact Registry 調整 Container Registry 工作流程，請進行下列變更。每個步驟都會連結至有關修改工作流程的其他資訊。

  1. 新功能：啟用 Artifact Registry API。

    您必須啟用 Artifact Registry API。Cloud Build 和 Cloud Run 和 GKE 等執行階段環境不會自動為您啟用 API。

  2. 新建：如果目標 Docker 存放區尚未存在，請建立。您必須先建立存放區，才能向存放區推送任何映像檔。推送映像檔不會建立存放區，且 Cloud Build 服務帳戶並沒有建立存放區的權限。

  3. 授予權限給將與 Artifact Registry 互動的帳戶。

  4. 已變更：驗證存放區。如果您在 gcloud CLI 中使用憑證輔助程式，則必須指定要新增至 Docker 用戶端設定的主機。舉例來說，下列指令會新增主機 us-central1-docker.pkg.dev：

    gcloud auth configure-docker us-central1-docker.pkg.dev

  5. 已變更：建構並標記映像檔。

    下列範例指令與 Container Registry 範例相同，但會使用映像檔的 Artifact Registry 存放區路徑。

    docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  6. 已變更：使用 Artifact Registry 路徑推送映像檔至存放區。例如：

    docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  7. 已變更：使用 Artifact Registry 路徑提取存放區中的映像檔。例如：

    docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

啟用 API

重點：

下表比較說明如何為各項服務啟用 API：

Container Registry

您必須先啟用 Container Registry API，才能使用 Docker 或其他第三方用戶端與 Container Registry。

啟用下列 Google Cloud API 時，系統也會自動啟用 Container Registry API：

  • App Engine 彈性環境
  • Cloud Build
  • Cloud Run 函式
  • Cloud Run
  • 在 Artifact Analysis 中執行容器掃描或隨選掃描
  • Google Kubernetes Engine

在預設權限下，如果使用者可以在 Cloud Build 中執行建構作業、使用 Artifact Analysis 掃描容器，或是將容器部署至Google Cloud 執行階段，則在註冊資料庫位於同一專案時，使用者就能隱含地存取 Container Registry 中的映像檔。

Artifact Registry

您必須先啟用 Artifact Registry API，才能使用 Docker 用戶端或其他 Google Cloud 服務搭配 Artifact Registry。

Cloud Build、Cloud Run 和 GKE 等服務不會自動啟用 Artifact Registry API。

您可以使用 gcloud 在同一個專案中啟用多個 API。舉例來說，如要啟用 Cloud Build API 和 Artifact Registry API，請執行下列指令：

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

新增註冊表和存放區

重點：

  • 您必須先建立 Artifact Registry Docker 存放區，才能將映像檔推送至該存放區。

    說明將映像檔推送至 Container Registry 的說明文件通常不會包含註冊建立步驟，因為具有 Storage 管理員權限的帳戶可以將註冊資料庫新增至專案，並將初始映像檔推送至註冊資料庫主機。

  • Container Registry 會將所有映像檔儲存在同一個儲存空間值區的單一多區域中。在 Artifact Registry 中，您可以在相同地區或多地區中建立多個存放區，並設定不同的存取政策。

以下比較說明各項服務中的存放區設定：

Container Registry

在 Container Registry 中，您最多可以為專案新增四個登錄主機。您可以透過推送第一個映像檔來新增登錄主機。

  1. 如要在專案中新增 gcr.io 等登錄，請由具有專案層級儲存空間管理員角色的帳戶推送初始映像檔。

    舉例來說，如果 gcr.io 主機不在專案 my-project 中，則推送映像檔 gcr.io/my-project/my-image:1.0 會觸發下列步驟：

    1. 將 gcr.io 主機新增至專案
    2. 在專案中為 gcr.io 建立儲存空間值區。
    3. 將圖片儲存為 gcr.io/my-project/my-image:1.0

  2. 完成初始推送後，您就可以為其他使用者授予儲存體儲存空間權限。

在專案中，註冊資料庫主機會將所有映像檔儲存在相同的儲存空間值區中。在下列範例中，專案 my-project 在註冊表 gcr.io 中具有兩個名為 web-app 的映像檔。一個位於專案 ID my-project 正下方。另一個圖片則位於存放區 team1 中。

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

具有 Artifact Registry 存放區管理員角色的帳戶必須先建立存放區，才能將映像檔推送至該存放區。接著，您可以授予權限，讓其他使用者存取存放區。

在 Artifact Registry 中，每個存放區都是獨立的資源。因此，所有圖片路徑都必須包含存放區。

有效的圖片路徑：

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

無效的圖片路徑 (不含存放區)：

us-central1-docker.pkg.dev/my-project/web-app:1.0

以下範例說明將映像檔推送至缺少的存放區時，可能會發生的情況。

  • 如果 us-central1-docker.pkg.dev/my-project/team1 不存在，則將圖片推送至 us-central1-docker.pkg.dev/my-project/team1。
  • 在 us-central1-docker.pkg.dev/my-project/team1 存在但 us-central1-docker.pkg.dev/my-project/team2 不存在的情況下，將映像檔推送至 us-central1-docker.pkg.dev/my-project/team2。

授予權限

重點：

  • 將適當的 Artifact Registry 角色授予您在 Artifact Registry 中使用的帳戶。
  • Google Cloud 服務對 Container Registry 和 Artifact Registry 皆具備相同的讀取或寫入權限。不過，預設的 Cloud Build 服務帳戶無法建立存放區。
  • Container Registry 支援儲存空間值區層級的存取權控管。Artifact Registry 支援存放區層級的存取權控管。

以下比較說明各服務中的權限設定：

Container Registry

Container Registry 會使用 Cloud Storage 角色控管存取權。

儲存值區層級的 Storage 物件檢視器
從專案中現有的註冊主機提取 (讀取) 映像檔。
儲存空間值區層級的 Storage 舊版值區寫入者
為專案中的現有註冊主機推送 (寫入) 及提取 (讀取) 映像檔。
專案層級的儲存空間管理員
將初始映像檔推送至主機，以便在專案中新增儲存庫主機。

將初始映像檔推送至登錄後，您可以將 Cloud Storage 角色授予其他需要存取儲存值區的帳戶。請注意，任何擁有 Storage Admin 角色所有權限的帳戶，都能在整個專案中讀取、寫入及刪除儲存體值區和儲存體物件。

儲存值區的權限會套用至登錄中的所有存放區。舉例來說，任何使用者只要在 gcr.io/my-project 的值區中具備 Storage Object Viewer 權限，就能讀取所有這些存放區中的圖片：

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry 有專屬的角色可控管存取權。這些角色可明確區分管理員和存放區使用者角色。

只有管理存放區的帳戶，才應具備 Artifact Registry 存放區管理員或 Artifact Registry 管理員角色。

Artifact Registry 讀取者
列出構件和存放區。下載構件。
Artifact Registry 寫入者
列出構件和存放區。下載構件、上傳新的構件版本，以及新增或更新標記。
Artifact Registry 存放區管理員
Artifact Registry Writer 權限，以及刪除構件和標記的權限。
Artifact Registry 管理員
Artifact Registry 存放區管理員權限，以及建立、更新、刪除及授予存放區權限的權限。

您可以在存放區層級套用這些權限。例如：

  • 將 us-central1-docker.pkg.dev/my-project/team1 的存取權授予 Team 1
  • 將 us-central1-docker.pkg.dev/my-project/team2 的存取權授予 Team 2。

如要進一步瞭解如何授予 Artifact Registry 權限，請參閱存取權控管說明文件。

向登錄表進行驗證

重點：

  • Artifact Registry 支援與 Container Registry 相同的驗證方法。
  • 針對 Docker 憑證輔助程式，您必須指定要加入 Docker 用戶端設定的主機。
  • 如要使用 docker login 進行驗證，請使用 Artifact Registry 主機，而非 Container Registry 主機。

使用憑證輔助程式

指令 gcloud auth configure-docker 和獨立憑證輔助程式預設只會為 *.gcr.io 主機名稱設定 Docker。針對 Artifact Registry，您必須指定要新增至 Docker 用戶端設定的 Artifact Registry 主機清單。

舉例來說，如要為 us-central1 區域中的 Docker 存放區設定驗證機制，請執行下列指令：

gcloud auth configure-docker us-central1-docker.pkg.dev

如果日後在 us-east1 和 asia-east1 中新增存放區，您必須再次執行指令，將對應的區域主機名稱新增至 Docker 設定。

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

如要進一步瞭解 Artifact Registry 驗證方法，請參閱「為 Docker 設定驗證機制」。

使用密碼驗證

登入 Docker 時，請使用 Artifact Registry 主機名稱，而非 *.gcr.io 主機名稱。以下範例顯示使用 base64 編碼服務帳戶金鑰驗證主機 us-central1-docker.pkg.dev：

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

建構及標記圖片

重點： - Artifact Registry 會為存放區使用不同的主機名稱。

為映像檔加上標記時，請使用 Artifact Registry 路徑，而非 Container Registry 路徑。例如：

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

將映像檔推送至登錄檔

重點： - 在 Artifact Registry 中，您必須先建立目標存放區，才能將映像檔推送至該存放區。- Artifact Registry 會為存放區使用不同的主機名稱。

推送映像檔時，請使用 Artifact Registry 路徑，而非 Container Registry 路徑。例如：

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

從註冊資料庫提取映像檔

重點：

  • Artifact Registry 主機名稱與 Container Registry 主機名稱不同。

提取映像檔時，請使用 Artifact Registry 路徑，而非 Container Registry 路徑。例如：

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

如需將映像檔部署至 Google Cloud 執行階段 (例如 Cloud Run 和 GKE) 的範例，請參閱「部署映像檔」。