使用 IAM 控管存取權

本頁說明用於控管 Container Registry 存取權的權限。

設定權限後，您可以為用於推送及提取映像檔的 Docker 用戶端設定驗證。

如果您使用 Artifact Analysis 處理容器中繼資料 (例如映像檔中發現的安全漏洞)，請參閱 Artifact Analysis 說明文件，瞭解如何授予檢視或管理中繼資料的存取權。

事前準備

確認您有管理使用者的權限。您必須具備下列任一角色的權限：

• 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
• 安全性管理員 (roles/iam.securityAdmin)

除了授予這些角色之外，您也可以使用具有相同權限的自訂角色或預先定義的角色。

權限與角色

所有與 Container Registry 互動的使用者、服務帳戶和其他身分，都必須具備 Cloud Storage 的適當身分和存取管理 (IAM) 權限。

• Google Cloud 通常會存取 Container Registry 的服務，會設定為具備相同Google Cloud 專案中登錄項的預設權限。如果預設權限無法滿足您的需求，請務必設定適當的權限。
• 如要使用其他身分，您必須設定必要權限。

您可以透過 Cloud Storage 權限控管 Container Registry 主機的存取權。下表列出具有 Container Registry 所需權限的 Cloud Storage 角色。

使用 Google Cloud 控制台查看 Container Registry 圖片時，需要額外具備一些權限，請參閱「使用 Cloud 控制台所需的常用權限」一文。

推送圖片需要物件讀取和寫入權限，以及 storage.buckets.get 權限。Storage 舊版值區寫入者角色包含單一 Cloud Storage 角色的必要權限，但不會授予儲存值區和物件的完整控制權。

儲存管理員角色可授予儲存值區和物件的完整控制權。如果您在專案層級授予此權限，主體將可存取專案中的所有儲存值區，包括 Container Registry 未使用的值區。請仔細考量哪些主體需要這個角色。

• 根據預設，Cloud Build 服務帳戶具備 Storage 管理員角色的權限。因此，這個服務帳戶可以透過第一次推送，將註冊資料庫新增至父項專案，並將映像檔推送至父項專案中的現有註冊資料庫。
• 如果您使用 Docker 或其他工具建立映像檔並將其推送至登錄，建議您使用具有較寬鬆的儲存空間管理員角色的帳戶，為專案新增登錄，然後將儲存空間舊版值區寫入者或儲存空間物件檢視者角色授予需要推送或提取映像檔的其他帳戶。

如要進一步瞭解 Cloud Storage 角色和權限，請參閱 Cloud Storage 說明文件。

授予 IAM 權限

Container Registry 使用 Cloud Storage 值區做為容器映像檔的基礎儲存空間。您可以透過授予註冊資料庫值區的權限，控管映像檔的存取權。

第一次將映像檔推送至主機名稱時，系統會將註冊主機及其儲存空間值區新增至專案。舉例來說，第一次推送至 gcr.io/my-project 會將 gcr.io 登錄檔主機新增至具有專案 ID my-project 的專案，並為登錄檔建立 Storage 值區。值區名稱的格式如下：

• artifacts.PROJECT-ID.appspot.com (適用於主機 gcr.io 上儲存的圖片)
• STORAGE-REGION.artifacts.PROJECT-ID.appspot.com 適用於儲存在其他註冊資料庫主機上的映像檔

如要順利執行這項首次圖片推送作業，執行推送作業的帳戶必須具備 Storage 管理員角色的權限。

將初始映像檔推送至登錄主機後，您就可以授予登錄儲存空間值區的權限，以便控管登錄中映像檔的存取權：

• Storage 舊版值區寫入器，用於推送及拉取
• 僅限 Storage 物件檢視器可讀取

您可以使用 Google Cloud console或 Google Cloud CLI 授予值區權限。

限制和規定

您只能為 Container Registry 主機授予儲存體值區層級的權限。

• Container Registry 會忽略針對 Cloud Storage 值區中的個別物件所設定的權限。
• 您無法授予登錄檔內存放區的權限。如果您需要更精細的存取控管機制，Artifact Registry 提供的存放區層級存取控管機制可能更符合您的需求。
• 如果您為任何 Container Registry 儲存空間值區啟用統一值區層級存取權，則必須明確授予存取登錄的所有使用者和服務帳戶權限。在這個情況下，擁有者和編輯者角色可能不會自行授予所需的權限。

授予權限

1. 如果專案中尚未有登錄主機，則必須由具備 儲存空間管理員角色權限的帳戶將第一個映像檔推送至登錄。這會為 Registry 主機建立儲存空間值區。

   Cloud Build 具備執行相同專案內初始圖片推送作業所需的權限。如果您使用其他工具推送映像檔，請驗證您用於透過 Container Registry 進行驗證的 Google Cloud 帳戶的權限。

   如要進一步瞭解如何使用 Docker 推送初始映像檔，請參閱「新增儲存庫」一文。

2. 在 Container Registry 專案中，授予註冊主機使用的 Cloud Storage 值區適當權限。

   主控台

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

   2. 按一下 bucket 的連結 artifacts.PROJECT-ID.appspot.com 或 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com。

      將 PROJECT-ID 替換為託管 Container Registry 專案的 Google Cloud 專案 ID，並將 STORAGE-REGION 替換為託管映像檔的存放區多區域 (asia、eu 或 us)。

   3. 選取 [Permission] (權限) 分頁標籤。

   4. 按一下「新增」。

   5. 在「主體」欄位中，輸入需要存取權的帳戶電子郵件地址，並以半形逗號分隔。電子郵件地址可以是下列其中一種：

      • Google 帳戶 (例如 someone@example.com)
      • Google 群組 (例如 my-developer-team@googlegroups.com)

      • 身分與存取權管理 (IAM) 服務帳戶。

        請參閱通常會存取登錄表的Google Cloud 服務清單，找出相關聯服務帳戶的電子郵件地址。如果服務是在與 Container Registry 不同的專案中執行，請務必使用其他專案中的服務帳戶電子郵件地址。

   6. 從「Select a role」(請選擇角色) 下拉式選單中，選取「Cloud Storage」類別，然後選取適當的權限。

      • Storage 物件檢視者 (僅用於擷取圖片)
      • Storage 舊版值區寫入器 (用於推送及提取圖片)

   7. 按一下「新增」。

   gcloud

   1. 執行下列指令，列出專案中的 bucket：

      gcloud storage ls
      

      回應類似下列範例：

      gs://[BUCKET_NAME1]/
      gs://[BUCKET_NAME2]/
      gs://[BUCKET_NAME3]/ ...
      

      在傳回的值區清單中，找出註冊主機的值區。儲存圖片的值區名稱為 BUCKET-NAME，格式如下：

      • artifacts.PROJECT-ID.appspot.com (適用於主機 gcr.io 上儲存的圖片)
      • STORAGE-REGION.artifacts.PROJECT-ID.appspot.com 如果映像檔儲存在其他註冊資料庫主機上

      地點

      • PROJECT-ID 是您的 Google Cloud 專案 ID。
      • STORAGE-REGION 是儲存空間值區的位置：
        • us，適用於 us.gcr.io 主機中的註冊資料庫
        • eu，適用於 eu.gcr.io 主機中的註冊資料庫
        • asia，適用於 asia.gcr.io 主機中的註冊資料庫

   2. 在您的殼層或終端機視窗中執行下列指令：

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
      --member=TYPE:EMAIL-ADDRESS \
      --role=ROLE
      

      地點

      • BUCKET_NAME 是 Cloud Storage 值區的名稱，格式為 artifacts.PROJECT-ID.appspot.com 或 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com
      • TYPE 可以是下列任一值：
        • 如果 EMAIL-ADDRESS 指定服務帳戶，則使用 serviceAccount。
        • user，如果 EMAIL-ADDRESS 是 Google 帳戶。
        • group，如果 EMAIL-ADDRESS 是 Google 群組。

      • EMAIL-ADDRESS 可以是下列其中一項：

        • Google 帳戶 (例如 someone@example.com)
        • Google 群組 (例如 my-developer-team@googlegroups.com)

        • 身分與存取權管理 (IAM) 服務帳戶。

          請參閱通常會存取登錄表的Google Cloud 服務清單，找出相關聯服務帳戶的電子郵件地址。如果服務是在與 Container Registry 不同的專案中執行，請務必使用其他專案中的服務帳戶電子郵件地址。

      • ROLE 是您要授予的 Cloud Storage 角色。

        • objectViewer 可提取圖片
        • legacyBucketWriter 推送及提取圖片

   舉例來說，下列指令會授予服務帳戶 my-account@my-project.iam.gserviceaccount.com 權限，讓該帳戶能夠在值區 my-example-bucket 中推送及提取映像檔：

   gcloud storage buckets add-iam-policy-binding gs://my-example-bucket \
     --member=serviceAccount:my-account@my-project.iam.gserviceaccount.com \
     --role=roles/storage.objectUser
   

   gcloud storage buckets add-iam-policy-binding 指令會變更託管註冊資料庫所在儲存空間值區的身分與存取權管理 (IAM) 權限。如需其他範例，請參閱 gcloud CLI 說明文件。

3. 如果您要設定 Compute Engine VM 或 GKE 節點的存取權，以便將映像檔推送至 Container Registry，請參閱「設定 VM 和叢集」一文，瞭解其他設定步驟。

設定圖片的公開存取權

如果主機位置的基礎儲存空間值區可公開存取，則代表 Container Registry 也可公開存取。在專案中，每個主機位置的所有映像檔必須都是公開映像檔或不公開映像檔。在專案的主機中，您無法只公開提供特定的映像檔。如要公開特定的映像檔，您可以採取下列其中一種方式：

• 將這些映像檔謹慎保存在您開放公眾存取的個別主機位置
• 建立新專案以存放可公開存取的圖片

如要公開提供容器映像檔，您可以按照下列步驟來開放基礎儲存空間值區，以供公眾存取：

1. 確認已將映像檔推送至 Container Registry，這樣才會有基礎儲存空間值區。

2. 找出該註冊資料庫的 Cloud Storage 值區名稱。如要進行此操作，請列出值區：

   gcloud storage ls
   

   您的 Container Registry 值區網址將會以 gs://artifacts.PROJECT-ID.appspot.com 或 gs://STORAGE-REGION.artifacts.PROJECT-ID.appspot.com 的形式列出，其中：

   • PROJECT-ID 是您的 Google Cloud 專案 ID。網域範圍專案會將網域名稱當做專案 ID 的一部分。
   • STORAGE-REGION 是儲存空間值區的位置：
     • us，適用於 us.gcr.io 主機中的註冊資料庫
     • eu，適用於 eu.gcr.io 主機中的註冊資料庫
     • asia，適用於 asia.gcr.io 主機中的註冊資料庫

3. 執行下列指令，將 Container Registry 的儲存空間值區變更為可公開存取。這項指令會公開該值區中的所有映像檔以供公眾存取。

   gcloud storage buckets add-iam-policy-binding gs://BUCKET-NAME \
       --member=allUsers --role=roles/storage.objectViewer
   

   其中：

   • gs://BUCKET-NAME 是 Container Registry 的值區網址

移除圖片的公開存取權

撤銷權限

請按照下列步驟撤銷 IAM 權限。

gcloud storage bucket remove-iam-policy-binding gs://BUCKET-NAME \
    --member=PRINCIPAL --all

整合 Google Cloud 服務

對於大多數 Google Cloud 服務帳戶而言，只要授予適當的 IAM 權限，即可設定存取登錄的權限。

Google Cloud 服務的預設權限

Google Cloud Cloud Build 或 Google Kubernetes Engine 等服務會使用預設服務帳戶或服務代理程式與同一個專案中的資源互動。

如要設定或修改權限，請務必符合下列條件：

• Google Cloud 服務所在的專案與 Container Registry 不同。
• 預設權限無法滿足您的需求。舉例來說，預設的 Compute Engine 服務帳戶具有相同專案中儲存空間的唯讀存取權。如果您想將映像檔從 VM 推送至登錄，必須修改 VM 服務帳戶的權限，或是使用具有儲存空間寫入權限的帳戶，對登錄進行驗證。
• 您使用自訂服務帳戶與 Container Registry 互動

下列服務帳戶通常會存取 Container Registry。服務帳戶的電子郵件地址會包含服務執行專案的 Google Cloud 專案 ID 或專案編號。

設定 VM 和叢集以推送映像檔

Compute Engine 和任何使用 Compute Engine 的 Google Cloud 服務，都會將 Compute Engine 預設服務帳戶設為預設身分。

IAM 權限和存取範圍都會影響 VM 讀取及寫入儲存空間的能力。

• IAM 權限決定資源存取權。
• 存取權範圍會針對 VM 執行個體上透過 gcloud CLI 和用戶端程式庫發出的要求，定義預設的 OAuth 範圍。因此，透過應用程式預設憑證進行驗證時，存取權範圍可以進一步限制 API 方法的存取權。
  • 如要提取私人映像檔，VM 服務帳戶必須具備該映像檔儲存空間值區的 read 權限。
  • 如要推送私人映像檔，VM 服務帳戶必須具備映像檔儲存空間值區的 read-write、cloud-platform 或 full-control 存取權範圍。

Compute Engine 預設服務帳戶預設會具備「編輯者」角色，該角色具備權限，可為多數Google Cloud 服務建立及更新資源。不過，無論是預設服務帳戶或您與 VM 建立關聯的自訂服務帳戶，儲存空間值區的預設存取權範圍都是唯讀。這表示根據預設，VM 無法推送映像檔。

如果您只想將映像檔部署至 Compute Engine 和 GKE 等環境，則不需要修改存取範圍。如果您要在這些環境中執行應用程式，並將映像檔推送至登錄檔，則必須執行其他設定。

如要進行下列設定，您必須變更 IAM 權限或存取範圍設定。

從 VM 或叢集推送映像檔

如果您要推送映像檔，VM 執行個體服務帳戶必須具有 storage-rw 範圍，而非 storage-ro。

VM 和 Container Registry 位於不同的專案中

您必須授予服務帳戶 IAM 權限，才能存取 Container Registry 使用的儲存空間值區。

在 VM 上執行 gcloud 指令

服務帳戶必須具備 cloud-platform 範圍。這個範圍會授予推送及提取圖片的權限，以及執行 gcloud 指令的權限。

設定範圍的步驟請見下文。

設定 VM 的範圍

如要在建立 VM 時設定存取範圍，請使用 --scopes 選項。

gcloud compute instances create INSTANCE --scopes=SCOPE

地點

• INSTANCE 是 VM 執行個體名稱。
• SCOPE 是您要為 VM 服務帳戶設定的範圍：
  • 提取圖片：storage-ro
  • 提取及推送圖片：storage-rw
  • 提取及推送映像檔，執行 gcloud 指令：cloud-platform

如要變更現有 VM 執行個體的範圍：

使用 --scopes 選項設定存取權範圍。

1. 停止 VM 執行個體。請參閱「停止執行個體」一文。

2. 使用下列指令變更存取範圍。

   gcloud compute instances set-service-account INSTANCE --scopes=SCOPE
   

   地點

   • INSTANCE 是 VM 執行個體名稱。
   • SCOPE 是您要為 VM 服務帳戶設定的範圍：
     • 提取圖片：storage-ro
     • 提取及推送圖片：storage-rw
     • 提取及推送映像檔，執行 gcloud 指令：cloud-platform

3. 重新啟動 VM 執行個體。請參閱啟動已停止的執行個體。

如果您想為 VM 使用自訂服務帳戶，而非預設服務帳戶，可以在建立 VM或修改 VM 設定時，指定要使用的服務帳戶和存取權範圍。

為 Google Kubernetes Engine 叢集設定範圍

根據預設，新建的 GKE 叢集會具備 Cloud Storage 值區的唯讀權限。

如要在建立 Google Kubernetes Engine 叢集時設定 read-write 儲存空間範圍，請使用 --scopes 選項。舉例來說，下列指令會建立具備 bigquery、storage-rw 和 compute-ro 範圍的叢集：

gcloud container clusters create example-cluster \
--scopes=bigquery,storage-rw,compute-ro

如要進一步瞭解您在新建叢集時可以設定的範圍，請參閱 gcloud container clusters create 指令的說明文件。

Container Registry 服務帳戶

在與 Google Cloud 服務互動時，Container Registry 服務代理人會代表 Container Registry 執行動作。如果您是在 2020 年 10 月 5 日之後啟用 Container Registry API，服務代理程式就會具備必要的最低權限組合。服務代理先前具有「編輯者」角色。如要進一步瞭解服務代理和修改其權限，請參閱「Container Registry 服務帳戶」。