本文將說明 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 使用。
事前準備
本文假設您已具備下列條件:
- 在專案中啟用 Artifact Registry。
- 安裝 Docker。Cloud Shell 已包含 Docker。
總覽
大致來說,在 Container Registry 或 Artifact Registry 中使用 Docker 的工作流程是一樣的。
Container Registry | Artifact Registry |
---|---|
管理員
|
管理員
|
註冊使用者
|
註冊使用者
|
不過,Container Registry 的捷徑會將管理員和使用者角色合併為單一工作流程。這個捷徑常見於:
- 快速入門導覽課程和教學課程,適用於您在擁有廣泛權限的環境中進行測試的情況。
- 使用 Cloud Build 的工作流程,因為 Cloud Build 服務帳戶具備在相同專案中新增登錄主機的權限。 Google Cloud
捷徑工作流程如下所示:
- 啟用 Container Registry API。
- 授予將存取 Container Registry 的帳戶權限。
向登錄表進行驗證。最簡單的驗證選項,就是在 Google Cloud CLI 中使用 Docker 憑證輔助程式。這是一次性的設定步驟。
gcloud auth configure-docker
建構並標記映像檔。舉例來說,下列指令會建構並標記映像檔
gcr.io/my-project/my-image:tag1
:docker build -t gcr.io/my-project/my-image:tag1
將映像檔推送至登錄檔。例如:
docker push gcr.io/my-project/my-image:tag1
如果專案中沒有
gcr.io
登錄主機,Container Registry 會在上傳映像檔前新增主機。從註冊資料庫提取映像檔,或將映像檔部署至 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 工作流程,請進行下列變更。每個步驟都會連結至有關修改工作流程的其他資訊。
新功能:啟用 Artifact Registry API。
您必須啟用 Artifact Registry API。Cloud Build 和 Cloud Run 和 GKE 等執行階段環境不會自動為您啟用 API。
新建:如果目標 Docker 存放區尚未存在,請建立。您必須先建立存放區,才能向存放區推送任何映像檔。推送映像檔不會建立存放區,且 Cloud Build 服務帳戶並沒有建立存放區的權限。
授予權限給將與 Artifact Registry 互動的帳戶。
已變更:驗證存放區。如果您在 gcloud CLI 中使用憑證輔助程式,則必須指定要新增至 Docker 用戶端設定的主機。舉例來說,下列指令會新增主機
us-central1-docker.pkg.dev
:gcloud auth configure-docker us-central1-docker.pkg.dev
已變更:建構並標記映像檔。
下列範例指令與 Container Registry 範例相同,但會使用映像檔的 Artifact Registry 存放區路徑。
docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
已變更:使用 Artifact Registry 路徑推送映像檔至存放區。例如:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
已變更:使用 Artifact Registry 路徑提取存放區中的映像檔。例如:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
啟用 API
重點:
- 除了 Cloud Build、Cloud Run 和 GKE 等其他 Google Cloud 服務的 API 外,您還必須啟用 Artifact Registry 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 中,您最多可以為專案新增四個登錄主機。您可以透過推送第一個映像檔來新增登錄主機。
如要在專案中新增
gcr.io
等登錄,請由具有專案層級儲存空間管理員角色的帳戶推送初始映像檔。舉例來說,如果
gcr.io
主機不在專案my-project
中,則推送映像檔gcr.io/my-project/my-image:1.0
會觸發下列步驟:- 將
gcr.io
主機新增至專案 - 在專案中為
gcr.io
建立儲存空間值區。 - 將圖片儲存為
gcr.io/my-project/my-image:1.0
- 將
完成初始推送後,您就可以為其他使用者授予儲存體儲存空間權限。
在專案中,註冊資料庫主機會將所有映像檔儲存在相同的儲存空間值區中。在下列範例中,專案 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) 的範例,請參閱「部署映像檔」。