手動將 Artifact Registry 中的存放區遷移至 `gcr.io`

本文說明如何在 Artifact Registry 中手動設定 gcr.io 存放區。

如要使用客戶自行管理的加密金鑰 (CMEK) 在 Artifact Registry 中建立 gcr.io 存放區，請先完成「事前準備」一節中的步驟，然後按照「手動建立存放區」一節中的操作說明進行。

事前準備

  1. 如果尚未安裝 Google Cloud CLI，請立即安裝。如果是現有安裝項目，請執行下列指令，將元件更新至最新版本：

    gcloud components update

  2. 啟用 Artifact Registry 和 Resource Manager API。 gcloud CLI 會使用 Resource Manager API 檢查是否具備其中一項必要權限。

    執行下列指令：

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

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

必要的角色

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

  • 如要建立 Artifact Registry 存放區並授予個別存放區的存取權，您必須在 Google Cloud 專案中擁有 Artifact Registry 管理員 (roles/artifactregistry.admin) 角色。
  • 如要查看及管理套用至 Cloud Storage 儲存空間值區的現有 Container Registry 設定，請在 Google Cloud 專案中指派「Storage 管理員」 (roles/storage.admin) 角色。
  • 首次將映像檔推送至 gcr.io 主機名稱時，請先建立 gcr.io 存放區： Artifact Registry 推送建立寫入者 (roles/artifactregistry.createOnPushWriter) 在 Google Cloud 專案中
  • 如要在專案層級授予存放區存取權： 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) Google Cloud 專案
  • 如要列出機構中已啟用的服務，請執行下列操作： Cloud Asset 檢視者 (roles/cloudasset.viewer) 機構

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

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

限制

Artifact Registry gcr.io 存放區有以下限制：

  • 從 Container Registry 轉換時，您無法將 Container Registry 主機對應至其他專案中的 Artifact Registry 存放區。

  • 每個 Container Registry 主機名稱只會對應至同一多地區中的一個 Artifact Registry gcr.io 存放區。

  • gcr.io 存放區的名稱是預先定義的，無法修改。

如要進一步控管存放區位置，可以改用 Artifact Registry 中的 pkg.dev 存放區。由於pkg.dev存放區不支援 gcr.io 網域，因此這種轉換方法需要對現有的自動化和工作流程進行更多變更。如要瞭解功能差異，請參閱「選擇轉換選項」。

建立存放區

建立 gcr.io 存放區，以便為使用者設定存取權，並在啟用重新導向功能前，將現有的 Container Registry 映像檔複製到 Artifact Registry。

手動建立存放區

如要使用客戶自行管理的加密金鑰 (CMEK) 加密存放區內容，或組織中存在位置限制，導致無法在特定位置建立新資源，請手動建立 gcr.io 存放區。Google Cloud

如要手動建立 gcr.io 存放區，請按照下列步驟操作：

  1. 如果您使用 CMEK，請建立要搭配這個存放區使用的金鑰，並授予使用金鑰的權限。請參閱「啟用客戶自行管理的加密金鑰」。

  2. 新增存放區。

    主控台

    1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

      開啟「存放區」頁面

    2. 點選 [Create Repository] (建立存放區)。

    3. 指定存放區名稱。

      Container Registry 主機名稱 Artifact Registry 存放區名稱
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io

    4. 將 Docker 指定為存放區格式。

    5. 在「位置類型」下方，為存放區指定多區域：

      Container Registry 主機名稱 Artifact Registry 存放區位置 Artifact Registry 存放區名稱
      gcr.io 美國 gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io 歐洲 eu.gcr.io
      us.gcr.io 美國 us.gcr.io

    6. 為存放區新增說明。請勿加入私密資料，因為存放區說明不會加密。

    7. 在「Encryption」(加密) 區段中，選擇存放區的加密機制。

      • Google-managed encryption key - 使用 Google-owned and Google-managed encryption key加密存放區內容。
      • 客戶管理的金鑰：使用您透過 Cloud Key Management Service 控制的金鑰，加密存放區內容。如需金鑰設定操作說明，請參閱「為存放區設定 CMEK」。

    8. 點選「建立」。

    gcloud

    執行下列指令來建立新的存放區：

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION \
    --description=DESCRIPTION \
    --kms-key=KMS-KEY

    替換下列值：

    • REPOSITORY 是存放區的名稱。

      Container Registry 主機名稱 Artifact Registry 存放區名稱
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io

    • LOCATION 是存放區的多區域：

      Container Registry 主機名稱 Artifact Registry 存放區位置 Artifact Registry 存放區名稱
      gcr.io 美國 gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io 歐洲 eu.gcr.io
      us.gcr.io 美國 us.gcr.io

    • DESCRIPTION 是存放區的說明。請勿加入私密資料，因為存放區說明不會加密。

    • KMS-KEY 是 Cloud KMS 加密金鑰的完整路徑。如果您使用客戶管理的加密金鑰加密存放區內容，路徑格式如下：

      projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

      替換下列值：

      • KMS-PROJECT 是儲存金鑰的專案。
      • KMS-LOCATION 是金鑰的位置。
      • KEY-RING 是金鑰環的名稱。
      • KEY 是金鑰的名稱。

    如要確認存放區已建立，請使用下列指令列出存放區：

    gcloud artifacts repositories list

將流量重新導向至新存放區前，請先確認現有自動化程序可以存取存放區。下一步是設定權限，授予存放區的存取權。

授予存放區權限

Container Registry 使用 Cloud Storage 角色控管存取權。Artifact Registry 有自己的 IAM 角色，這些角色比 Container Registry 更清楚地劃分讀取、寫入和存放區管理角色。

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

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

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

    前往「Buckets」(值區) 頁面

  2. 按一下要查看的登錄主機儲存空間 bucket。 在 bucket 名稱中，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. 展開角色，查看具備該角色的主體。

這份清單包含直接在 bucket 上授予的 IAM 角色，以及從父項專案繼承的角色。您可以根據角色選擇要授予的 Artifact Registry 角色。

Cloud Storage 和基本角色

授予目前存取 Container Registry 的使用者和服務帳戶 Artifact Registry 存放區的存取權。如要瞭解從上層專案繼承的 Cloud Storage 角色，請確認主體目前是否使用 Container Registry。部分主體可能只會存取與 Container Registry 無關的其他 Cloud Storage 值區。

在 IAM 推出前就存在的「擁有者」、「編輯者」和「檢視者」基本角色，對儲存空間 buckets 的存取權有限。這些角色並不會如名稱所示，提供 Cloud Storage 資源的所有存取權，而是為其他 Google Cloud 服務提供額外權限。確認哪些使用者和服務帳戶需要存取 Artifact Registry，並使用角色對應表，協助您授予適當的角色 (如果存取 Artifact Registry 是適當的)。

下表根據預先定義的 Cloud Storage 角色授予的權限，對應 Artifact Registry 角色，以供 Container Registry 存取。

必要存取權 目前的角色 Artifact Registry 角色 授予角色的位置
僅提取圖片 (唯讀) Storage 物件檢視者
(roles/storage.objectViewer)		 Artifact Registry Reader
(roles/artifactregistry.reader) 		Artifact Registry 存放區或 Google Cloud 專案
  • 推送及提取映像檔 (讀取和寫入)
  • 刪除圖片
 Storage 舊版值區寫入者
(roles/storage.legacyBucketWriter)		 Artifact Registry 存放區管理員
(roles/artifactregistry.repoAdmin)		 Artifact Registry 存放區或 Google Cloud 專案
首次將映像檔推送至專案中的 gcr.io 主機名稱時，系統會在 Artifact Registry 中建立 gcr.io 存放區。 Storage 管理員
(roles/storage.admin)		 Artifact Registry 推送建立存放區管理員
(roles/artifactregistry.createOnPushRepoAdmin)		 Google Cloud 專案
建立、管理及刪除存放區 Storage 管理員
(roles/storage.admin)		 Artifact Registry 管理員
(roles/artifactregistry.admin)		 Google Cloud 專案
從專案繼承的服務代理角色

Google Cloud 服務的預設服務帳戶在專案層級擁有自己的角色。舉例來說，Cloud Run 的服務代理人具有 Cloud Run 服務代理人角色。

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

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

自訂角色

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

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

從 Container Registry 複製容器

建議使用我們的自動遷移工具，將映像檔從 Container Registry 複製到 Artifact Registry。

如要使用其他工具複製映像檔，請參閱「從 Container Registry 複製映像檔」一文。

設定其他功能

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

Artifact Analysis

構件分析支援 Container Registry 和 Artifact Registry。這兩項產品都使用相同的構件分析 API 進行映像檔中繼資料和安全漏洞掃描，並使用相同的 Pub/Sub 主題傳送構件分析通知。

不過，只有在啟用重新導向功能時，才會發生下列動作：

  • 自動掃描 Artifact Registry 中的 gcr.io 存放區。
  • 在 Pub/Sub 通知中加入 gcr.io 存放區活動。

您仍可繼續使用 gcloud container images 指令，列出與 gcr.io 映像檔路徑相關聯的附註和事件。

Container Registry Artifact Registry
針對支援的 OS 映像檔，透過隨選掃描功能掃描 OS 和語言套件安全漏洞。自動掃描只會傳回 OS 安全漏洞資訊。進一步瞭解掃描類型。
隨選掃描
自動掃描
  • Google Cloud CLI 指令 gcloud container images 包含用於查看掃描結果的標記，包括安全漏洞和其他中繼資料。
  • 掃描只會針對 Container Registry 中 支援的作業系統，回報映像檔的作業系統安全漏洞資訊。
 透過隨選和自動掃描功能，掃描 OS 和語言套件安全漏洞。進一步瞭解掃描類型。
隨選掃描
自動掃描
  • Google Cloud CLI 指令 gcloud artifacts docker images 包含可查看掃描結果的標記，包括安全漏洞和其他中繼資料。
  • 掃描結果會顯示 Artifact Registry 中映像檔的 OS 安全漏洞資訊 (適用於 支援的作業系統)，以及支援和不支援作業系統的語言套件安全漏洞資訊。

Pub/Sub 通知

Artifact Registry 會將變更發布至與 Container Registry 相同的 gcr 主題。如果您已在與 Artifact Registry 相同的專案中，搭配 Container Registry 使用 Pub/Sub，則無需額外設定。不過，您必須啟用重新導向功能，Artifact Registry 才會發布 gcr.io 存放區的訊息。

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

啟用 gcr.io 流量重新導向

建立 gcr.io 存放區，並為第三方用戶端設定權限和驗證後，即可啟用 gcr.io 流量重新導向。

啟用重新導向後，如果遇到問題，可以執行 gcloud artifacts settings disable-upgrade-redirection 指令，將流量導回 Container Registry，待問題解決後再重新啟用重新導向。

確認啟用重新導向的權限

如要啟用重新導向功能，您必須具備專案層級的下列權限：

  • artifactregistry.projectsettings.update - 具備更新 Artifact Registry 專案設定的權限。這項權限位於 Artifact Registry 管理員角色 (roles/artifactregistry.admin) 中。
  • storage.buckets.update - 整個專案的儲存空間值區更新權限。這項權限屬於「Storage 管理員」角色 (roles/storage.admin)。

如果您沒有這些權限，請要求管理員在專案層級授予權限。

下列指令會授予專案的 Artifact Registry 管理員和儲存空間管理員角色。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

替換下列值：

  • PROJECT_ID 是 Google Cloud 專案 ID。
  • PRINCIPAL 是您要更新的帳戶電子郵件地址。例如 my-user@example.com

驗證專案設定

如要驗證專案設定，請執行下列指令：

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

將 PROJECT_ID 替換為 Google Cloud專案 ID。

Artifact Registry 會檢查對應至 Container Registry 主機名稱的存放區。

雖然啟用重新導向時，Artifact Registry 可以為您建立缺少的 gcr.io 存放區，但我們建議您先建立這些存放區，以便在啟用重新導向前執行下列動作：

開啟重新導向功能

如要啟用 gcr.io 流量的重新導向功能，請按照下列步驟操作：

如要啟用重新導向功能，請執行下列指令：

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

將 PROJECT_ID 替換為 Google Cloud專案 ID。

Artifact Registry 會開始啟用重新導向。

如要檢查目前的重新導向狀態，請執行下列指令：

gcloud artifacts settings describe

啟用重新導向後，結果如下：

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

即使您未為所有 Container Registry 主機名稱建立 gcr.io 存放區，系統仍會重新導向 gcr.io、asia.gcr.io、eu.gcr.io 和 us.gcr.io 的所有流量。如果您將映像檔推送至沒有對應 Artifact Registry 存放區的主機名稱，Artifact Registry 會建立存放區 (前提是您具有 artifactregistry.repositories.createOnPush 權限的角色)。預先定義的「Create-on-push Writer」(artifactregistry.createOnPushWriter) 和「Create-on-push Repository Administrator」(artifactregistry.createOnPushRepoAdmin) 角色都具備這項權限。

啟用重新導向後，您可以測試自動化功能，並確認是否能使用新的 gcr.io 存放區推送及提取映像檔。

確認重新導向

確認對 gcr.io 主機名稱的提取和推送要求是否正常運作。

  1. 使用其中一個 gcr.io 存放區的 gcr.io 路徑，將測試映像檔推送至該存放區。

    1. 使用 gcr.io 路徑為圖片加上標記。舉例來說，下列指令會將 local-image 映像檔標記為 us.gcr.io/my-project/test-image：

      docker tag local-image us.gcr.io/my-project/test-image

    2. 推送您標記的映像檔。舉例來說，這個指令會推送 us.gcr.io/my-project/test-image 映像檔：

      docker push us.gcr.io/my-project/test-image

  2. 列出存放區中的映像檔，確認映像檔已成功上傳。舉例來說，如要列出 us.gcr.io/my-project 中的映像檔，請執行下列指令：

    gcloud container images list --repository=us.gcr.io/my-project

  3. 使用映像檔的 Container Registry 路徑，從存放區提取映像檔。 舉例來說，這項指令會提取 us.gcr.io/my-project/test-image 映像檔。

    docker pull us.gcr.io/my-project/test-image

完成這項初步測試後，請確認現有的映像檔建構和部署自動化程序是否正常運作，包括：

  • 啟用重新導向後，使用 Container Registry 的使用者和服務帳戶仍可推送、提取及部署映像檔。
  • 自動化程序只會將映像檔推送至現有存放區。
  • 如果啟用 Artifact Analysis 安全漏洞掃描功能，掃描作業會找出 gcr.io 存放區中含有安全漏洞的映像檔。
  • 如果您使用二進位授權，現有政策可正常處理從 gcr.io 存放區部署的映像檔。
  • 設定的 Pub/Sub 訂閱項目包括gcr.io存放區變更的通知。

清除 Container Registry 映像檔

啟用重新導向後，刪除 gcr.io 路徑中映像檔的指令，會刪除對應 Artifact Registry gcr.io 存放區中的映像檔。刪除 gcr.io 路徑中映像檔的刪除指令，不會刪除儲存在 Container Registry 主機上的映像檔。

如要安全移除所有 Container Registry 映像檔，請刪除每個 Container Registry 主機名稱的 Cloud Storage bucket。

如要刪除每個 Container Registry 儲存空間 bucket：

主控台

  1. 前往 Google Cloud 控制台的 Cloud Storage 頁面。

  2. 選取要刪除的儲存空間值區。在 bucket 名稱中，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. 按一下 [Delete] (刪除)，系統會顯示確認對話方塊。

  4. 如要確認刪除，請輸入 bucket 名稱，然後按一下「Delete」(刪除)。

gcloud

如要大量刪除 bucket 中十萬張以上的圖片，請避免使用 gcloud CLI，因為刪除程序需要很長時間才能完成。請改用 Google Cloud 控制台執行這項作業。詳情請參閱大量刪除 Cloud Storage 物件。

如要刪除 bucket，請使用 gcloud storage rm 指令，並加上 --recursive 旗標。

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

將 BUCKET-NAME 替換為 Container Registry 儲存空間值區名稱。在 bucket 名稱中，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

回應類似下列範例：

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

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

後續步驟