轉換至標準存放區

如果您使用 Container Registry 管理容器映像檔，本頁會說明如何設定 pkg.dev Artifact Registry 存放區，以及使用存放區與使用 Container Registry 的差異。

以下操作說明主要適用於存放區管理員。如要瞭解建構、推送、拉取和部署映像檔的異動方式，請參閱以下資訊：

• 在 Google Cloud中建構及部署內容的異動
• 使用 Docker 推送及提取的異動

事前準備

1. 請透過 Google Cloud 控制台或指令啟用 Artifact Registry API：

   gcloud services enable artifactregistry.googleapis.com
   

2. 如果尚未安裝 gcloud CLI，請先安裝。如為現有安裝項目，請執行下列指令，將元件更新至最新版本：

   gcloud components update
   

3. 開始遷移前，請先瞭解 Artifact Registry 的定價。

必要的角色

如要取得設定 gcr.io 存放區所需的權限，請要求管理員為您授予 Google Cloud 專案的下列 IAM 角色：

• 如要建立 Artifact Registry 存放區，並授予存放區存取權： Artifact Registry 管理員 (roles/artifactregistry.admin)
• 如要查看及管理套用至 Cloud Storage 儲存空間值區的現有 Container Registry 設定，請按照下列步驟操作： Storage Admin (roles/storage.admin)
• 如要在專案層級授予存放區存取權： 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 或包含等同權限的角色，例如資料夾管理員 (roles/resourcemanager.folderAdmin) 或機構管理員 (roles/resourcemanager.organizationAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

總覽

pkg.dev 存放區是支援所有功能的一般 Artifact Registry 存放區。

為簡化操作，本頁的操作說明假設 Container Registry 和 Artifact Registry 都位於同一個 Google Cloud 專案中。您可以繼續使用這兩項服務，並在轉換至 Artifact Registry 時逐步執行設定步驟，並更新自動化動作。如有需要，您可以在單獨專案中設定 Artifact Registry，並執行相同的整體步驟。

Artifact Registry 也提供 gcr.io 存放區。這些存放區可將 gcr.io 流量從現有註冊服務重新導向至對應的 Artifact Registry 存放區。雖然這些工具可與 Container Registry 相容，但也有一些功能限制。不過，如果您有許多含有 gcr.io 參照的工具設定、指令碼或程式碼，可能需要採用更具策略性的做法，才能轉換至 Artifact Registry。請參閱支援 gcr.io 網域的存放區轉換說明文件，協助您做出適當的決定。

轉換步驟

本指南將說明如何完成下列步驟：

1. 為容器建立 Docker 存放區。您必須先建立存放區，才能將圖片推送至該存放區。
2. 授予存放區權限。
3. 設定驗證，以便連線至新的存放區。
4. 如有需要，請從您要用於新存放區的 Container Registry 複製映像檔。
5. 請嘗試推送及拉取容器。
6. 請嘗試將映像檔部署至執行階段環境。
7. 設定其他功能。
8. 轉換完成後，清理 Container Registry 中的映像檔。

建立存放區

如果您之前未在多區域中推送映像檔，Container Registry 會自動在多區域中建立儲存空間值區。

在 Artifact Registry 中，您必須先建立存放區，才能上傳圖片。建立存放區時，您必須指定下列項目：

• 存放區格式。Artifact Registry 會將容器儲存在 Docker 存放區中。

• 存放區的單一區域或多區域位置。

  選擇 Artifact Registry 存放區的位置時，請考量存放區與其他基礎架構和使用者的距離。如果您打算將映像檔從 Container Registry 複製到 Artifact Registry，位置的不同可能會影響複製費用。

• 如果您使用客戶自行管理的加密金鑰 (CMEK) 進行加密，則需要 Cloud Key Management Service 金鑰。

  在 Container Registry 中，您可以將 Container Registry 儲存空間值區設為使用 CMK。在 Artifact Registry 中，您可以設定存放區在建立時使用 CMEK。如要進一步瞭解如何在 Artifact Registry 中使用 CMEK，請參閱「啟用客戶管理的加密金鑰」。

Container Registry 會在網域 gcr.io 上託管容器。Artifact Registry 在網域 pkg.dev 上託管容器。

如要瞭解如何建立存放區 (包括使用 CMEK 進行加密的存放區)，請參閱「建立存放區」一文。

授予權限

Container Registry 會使用 Cloud Storage 角色來控管存取權。Artifact Registry 有專屬的 IAM 角色，這些角色比容器 Registry 更清楚地區分讀取、寫入和存放區管理角色。

如要快速將儲存空間儲存格中授予的現有權限對應至建議的 Artifact Registry 角色，請使用角色對應工具。

或者，您也可以使用 Google Cloud 控制台查看有權存取儲存值區的使用者清單。

1. 在 Google Cloud 控制台，前往 Cloud Storage「Buckets」頁面。
   

   前往「Buckets」(值區) 頁面

2. 按一下要查看的註冊主機的儲存空間值區。在值區名稱中，PROJECT-ID 是您的Google Cloud 專案 ID。

   • gcr.io: artifacts.PROJECT-ID.appspot.com
   • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
   • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
   • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

3. 按一下「Permissions」(權限) 分頁標籤。

4. 在「權限」分頁中，按一下「依角色查看」子分頁。

5. 展開角色，查看具備該角色的主體。

清單中包含直接在儲存桶中授予的 IAM 角色，以及從父專案繼承的角色。您可以根據角色，選擇最適當的 Artifact Registry 角色來授予。

Cloud Storage 和基本角色

將 Artifact Registry 存放區的存取權授予目前存取 Container Registry 的使用者和服務帳戶。針對從父專案繼承的 Cloud Storage 角色，您應確認實體目前是否使用 Container Registry。有些使用者身分原則可能只會存取與 Container Registry 無關的其他 Cloud Storage 值區。

在 IAM 推出前就存在的基本角色「擁有者」、「編輯者」和「檢視者」具有有限的儲存空間儲存桶存取權。這些權限並不會提供名稱所暗示的所有 Cloud Storage 資源存取權，也不會為其他服務提供額外權限。 Google Cloud 請確認哪些使用者和服務帳戶需要存取 Artifact Registry，並使用角色對應表格，在適當情況下授予正確的角色。

下表會根據預先定義的 Cloud Storage 角色授予 Container Registry 存取權的權限，對應 Artifact Registry 角色。Artifact Registry 角色提供一些額外的權限區隔，這些權限在預先定義的 Cloud Storage 角色中無法使用。

需要的存取權	目前的角色	Artifact Registry 角色	授予角色的位置
僅提取圖片 (唯讀)	Storage 物件檢視器 (roles/storage.objectViewer)	Artifact Registry Reader (roles/artifactregistry.reader)	Artifact Registry 存放區或 Google Cloud 專案
推送及提取圖片 (讀取和寫入)	Storage 舊版值區寫入者 (roles/storage.legacyBucketWriter)	Artifact Registry Writer (roles/artifactregistry.writer)	Artifact Registry 存放區或 Google Cloud 專案
推送、提取及刪除圖片	Storage 舊版值區寫入者 (roles/storage.legacyBucketWriter)	Artifact Registry 存放區管理員 (roles/artifactregistry.repoAdmin)	Artifact Registry 存放區或 Google Cloud 專案
建立、管理及刪除存放區	Storage 管理員 (roles/storage.admin)	Artifact Registry 管理員 (roles/artifactregistry.admin)	Google Cloud 專案

從專案繼承的服務代理角色

Google Cloud 服務的預設服務帳戶會在專案層級獲得專屬角色。舉例來說，Cloud Run 的服務代理人具有 Cloud Run Service Agent 角色。

在大多數情況下，這些服務代理角色都包含 Container Registry 和 Artifact Registry 的等同預設權限，因此如果您在與現有 Container Registry 服務相同的專案中執行 Artifact Registry，就不需要再進行任何變更。

如要進一步瞭解服務代理角色中的權限，請參閱服務代理角色參考資料。

自訂角色

您可以使用角色對應表格，根據使用者或服務帳戶所需的存取權層級，決定要授予他們的角色。

如需授予 Artifact Registry 角色的操作說明，請參閱「設定角色和權限」。

向存放區進行驗證

Artifact Registry 支援與 Container Registry 相同的驗證方法。

如果您使用的是 Docker 憑證輔助程式：

• 您必須使用 2.0 以上版本，才能與 Artifact Registry 存放區互動。您可以在 GitHub 取得獨立版本。
• 您必須使用要使用的 Artifact Registry 位置，設定憑證輔助程式。根據預設，憑證輔助程式只會設定 Container Registry 主機的存取權。

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

從 Container Registry 複製容器

如果 Container Registry 中有您想繼續在 Artifact Registry 中使用的容器，可以透過幾種方式複製這些容器。如需詳細操作說明，請參閱「從 Container Registry 複製映像檔」一文

推送及提取圖片

在 Artifact Registry 中標記、推送及提取映像檔的 Docker 指令，與在 Container Registry 中使用的指令類似。兩者的主要差異如下：

• Artifact Registry Docker 存放區的主機名稱包含位置前置字串，後面接著 -docker.pkg.dev。例如 australia-southeast1-docker.pkg.dev、europe-north1-docker.pkg.dev 和 europe-docker.pkg.dev。
• 由於 Artifact Registry 支援單一專案中的多個 Docker 存放區，因此您必須在指令中指定存放區名稱。

舉例來說，在 Container Registry 中，這個指令會將映像檔 my-image 推送至專案 my-project 中的登錄 eu.gcr.io。

docker push eu.gcr.io/my-project/my-image

在 Artifact Registry 中，這個指令會將映像檔 my-image 推送至存放區 my-repo 和專案 my-project 中的區域存放區 europe-north1-docker.pkg.dev。

docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image

如要進一步瞭解如何在 Artifact Registry 中推送及提取映像檔，請參閱「推送及提取映像檔」。

部署映像檔

常見 Google Cloud 整合作業的服務帳戶會設定為具備相同專案中存放區的預設權限。

使用 Cloud Build 建構映像檔並推送至存放區的做法，通常與 Container Registry 相同。在 Artifact Registry 中，主要差異在於您必須先建立目標存放區，才能將映像檔推送至該存放區，包括您推送的第一個映像檔。

請務必先建立所需的存放區，再執行推送映像檔的指令，包括 Docker 指令 docker push 和 Cloud Build 指令 gcloud builds submit。

Cloud Build 建構工具仍託管於 gcr.io。詳情請參閱「與 Cloud Build 整合」。

其他功能

本節說明您可能已在 Container Registry 中設定的其他功能設定。

Artifact Analysis

構件分析支援 Container Registry 和 Artifact Registry。Artifact Analysis 說明文件包含這兩項產品。

• 這兩項產品都使用相同的 Artifact Analysis API。在 Container Registry 或 Artifact Registry 中啟用 Artifact Analysis API 時，兩項產品的 API 都會啟用。
• 兩項產品都會使用相同的 Pub/Sub 主題來傳送Artifact Analysis 通知。
• 您可以繼續使用 gcloud container images 指令，列出與 gcr.io 映像檔路徑相關聯的備註和事件。

Pub/Sub 通知

Artifact Registry 會將變更發布至與 Container Registry 相同的 gcr 主題。如果您已在與 Artifact Registry 相同的專案中，使用 Pub/Sub 搭配 Container Registry，則不需要額外設定。

如果您在獨立專案中設定 Artifact Registry，gcr 主題可能不存在。如需設定操作說明，請參閱「設定 Pub/Sub 通知」。

服務範圍

透過 VPC Service Controls，您可以為 Google 代管服務的資源設定安全範圍，並控管跨服務邊界的資料移動。

如需操作說明，請參閱「保護服務範圍內的存放區」。

清理 Container Registry 映像檔

準備停止使用 Container Registry 時，請刪除 Container Registry 的儲存值區，以便刪除剩餘的映像檔。

如要刪除各個 Container Registry 儲存空間值區，請按照下列步驟操作：

gcloud storage rm gs://BUCKET-NAME --recursive

Removing gs://artifacts.my-project.appspot.com/...

如果其他 Google Cloud 服務在同一個 Google Cloud專案中執行，請保留啟用的 Container Registry API。如果您嘗試停用 Container Registry API。如果專案中啟用了其他已設定依附元件的服務，Container Registry 會顯示警告。停用 Container Registry API 後，即使您目前未在這些服務中使用 Container Registry，系統也會自動停用同個專案中具有已設定依附元件的任何服務。

後續步驟

• 請試試 Docker 快速入門導覽課程。