使用 IAM 控管存取權

本頁面說明如何在 Artifact Registry 中使用 Identity and Access Management (IAM) 控管存取權。

實作 CI/CD 管道時，Artifact Registry 的預設權限可減少設定工作量。您也可以將 Artifact Registry 與第三方 CI/CD 工具整合，並設定存放區存取權和驗證機制。

事前準備

1. 啟用 Artifact Registry，包括啟用 API 和安裝 Google Cloud CLI。
2. 如要套用存放區專屬權限，請為套件建立 Artifact Registry 存放區。

總覽

IAM 權限和角色會決定您是否可以在 Artifact Registry 存放區中建立、查看、編輯或刪除資料。

角色是一組權限。您無法直接授予主體權限，而是授予角色。將角色授予主體後，主體就會取得該角色具備的所有權限。您可以為相同的主體授予多個角色。

Google Cloud 預設權限

根據預設，下列權限會套用至與 Artifact Registry 位於同一個專案的 CI/CD 服務： Google Cloud

• Cloud Build 權限包括上傳和下載構件檔案的權限。

• Compute Engine、支援的 Google Kubernetes Engine 版本和 Cloud Run 會使用 Compute Engine 預設服務帳戶，該帳戶具有儲存空間的唯讀存取權。

如果所有服務都位於同一個 Google Cloud 專案中，且預設權限符合您的需求，則不需要設定權限。

如要設定這些服務的 Artifact Registry 權限，必須符合下列條件：

• 您想使用這些服務存取其他專案中的 Artifact Registry。在使用 Artifact Registry 的專案中，請授予每項服務的工作負載身分集區或服務帳戶所需的角色。如果要連線至 Cloud Run，請將必要角色授予 Cloud Run 服務代理人。

• 您使用的 GKE 版本沒有內建支援從 Artifact Registry 提取映像檔的功能。如需設定操作說明，請參閱 GKE 專區。
• 您希望預設服務帳戶具備存放區的讀取和寫入權限。詳情請參閱下列資訊：
  • Compute Engine
  • GKE
• 您在執行階段環境中使用的是使用者提供的服務帳戶，而非預設服務帳戶。在使用 Artifact Registry 的專案中，授予服務帳戶所需的角色。

第三方整合

針對第三方用戶端，您必須同時設定權限和驗證。

傳統上，在 Google Cloud 外執行的應用程式會使用服務帳戶金鑰存取 Google Cloud 資源。不過，服務帳戶金鑰是功能強大的憑證，如果管理不當就會帶來安全風險。

有了 Workload Identity 聯盟，您就可以使用身分與存取權管理功能，授予外部身分 IAM 角色，包括模擬服務帳戶的權限。這種做法可免除服務帳戶金鑰的維護和安全負擔。

使用 Workload Identity 聯盟：

1. 建立工作負載身分聯合體集區。
2. 建立 Workload Identity Federation 提供者。
3. 授予工作負載身分資料集合適當的 Artifact Registry 角色，以便存放區存取權。詳情請參閱「允許外部工作負載存取 Google Cloud 資源」。
4. 如果您需要在較長的時間內存取 Artifact Registry，請在憑證設定中將 OIDC 權杖到期時間設定為較長的時間。

5. 設定第三方用戶端，以便透過 Artifact Registry 進行驗證。

   • 容器映像檔：Docker、Helm
   • 語言套件： Java, Node.js, Python, Go
   • 作業系統套件：Debian、RPM
   • 其他：Kubeflow Pipeline 範本

使用服務帳戶：

1. 建立服務帳戶，以便代表應用程式執行動作，或選擇現有服務帳戶，用於 CI/CD 自動化作業。
2. 授予服務帳戶適當的 Artifact Registry 角色，以便提供存放區存取權。

3. 設定第三方用戶端，以便透過 Artifact Registry 進行驗證。

   • 容器映像檔：Docker、Helm
   • 語言套件： Java, Node.js, Python, Go
   • 作業系統套件：Debian、RPM
   • 其他：Kubeflow Pipeline 範本

Google Cloud上的 GitLab

GitLab on Google Cloud 整合功能會使用 Workload Identity 聯盟，為 GitLab on Google Cloud 的工作負載授權和驗證，不必使用服務帳戶或服務帳戶金鑰。如要進一步瞭解這項合作夥伴關係中如何使用 Workload Identity 聯盟，請參閱 Google Cloud Workload Identity 聯盟和 IAM 政策。

如要為 Google Cloud上的 GitLab 設定工作負載身分聯盟和必要的 IAM 角色，請參閱 GitLab 教學課程：Google Cloud 工作負載身分聯盟和 IAM 政策。

如要連結 Artifact Registry 存放區，請按照 GitLab 教學課程 Google Artifact Registry 操作。

角色和權限

凡是需要帳戶發送 API 要求的 Artifact Registry API 方法，都具備使用該項資源的適當權限。您可以設定政策，為主體授予資源上的預先定義角色，藉此授予主體權限。

您可以授予 Google Cloud 專案或 Artifact Registry 存放區的角色。

預先定義的 Artifact Registry 角色

IAM 提供預先定義的角色，這些角色會授予特定 Google Cloud 資源的存取權。

基本身分與存取權管理角色

基本角色是權限過高的角色，在 IAM 推出前就存在。請勿在正式上線環境中授予基本角色，但可以在開發或測試環境中授予這些角色。

盡可能使用預先定義的角色來存取存放區，讓使用者和服務帳戶只具備必要的權限。

如要進一步瞭解基本角色，請參閱 IAM 基本角色和預先定義角色參考資料。

正在授予角色

如果相同角色適用於專案中的所有存放區，請在專案層級授予角色。如果部分帳戶需要不同層級的存取權，請在存放區層級授予角色。

如果您使用 gcloud 指令授予角色，可以為單一授權者指定單一角色繫結，也可以取得資源的允許政策、修改該政策，然後設定修改後的允許政策，藉此進行大規模政策變更。詳情請參閱「以程式輔助方式授予或撤銷多個角色」。

授予整個專案的角色

如果專案中的所有存放區都適用相同權限，請在專案層級授予角色。

如要在專案中新增使用者或服務帳戶，並授予該帳戶 Artifact Registry 角色，請按照下列步驟操作：

授予存放區專屬角色

如要讓使用者或服務帳戶在專案中的每個存放區中擁有不同層級的存取權，請授予存放區層級角色。

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo"     {
  provider = google-beta

  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = "DESCRIPTION"
  format = "FORMAT"
}

resource "google_service_account" "repo-account" {
  provider = google-beta

  account_id   = "ACCOUNT-ID"
  display_name = "Repository Service Account"
}

resource "google_artifact_registry_repository_iam_member" "repo-iam" {
  provider = google-beta

  location = google_artifact_registry_repository.my-repo.location
  repository = google_artifact_registry_repository.my-repo.name
  role   = "roles/artifactregistry.reader"
  member = "serviceAccount:${google_service_account.repo-account.email}"
}

設定存放區的公開存取權

如果您有不需要驗證就能供網際網路上的任何人存取的構件，請將這些構件儲存在公開的存放區中。

如要設定可供大眾存取的唯讀存放區，請將「Artifact Registry Reader」角色授予主體 allUsers。我們也建議限制使用者要求配額，以免單一使用者耗盡專案的整體配額。

正在撤銷角色

如要撤銷存放區的存取權，請從授權主體清單中移除主體。

如要移除存放區的公開存取權，請移除 allUsers 主體。

使用標記授予條件存取權

專案管理員可以為 Google Cloud中的資源建立標記，並在 Resource Manager 中管理這些標記。將標記附加至 Artifact Registry 存放區後，管理員就能使用標記和 IAM 條件，授予存放區的條件存取權。

您無法將標記附加至個別構件。

如需更多資訊，請參閱下列說明文件：

• 管理員設定代碼和存取權控管
  • 建立及管理標記
  • 標記和存取權控管。
• 開發人員將標記附加至存放區
  • 標記存放區

與 Google Cloud 服務整合

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

Google Cloud 服務的預設服務帳戶

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

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

• Google Cloud 服務位於 Artifact Registry 以外的專案。
• 預設權限無法滿足您的需求。
• 您使用的是使用者提供的服務帳戶，而非預設服務帳戶，與 Artifact Registry 互動。
• 您的機構政策設定會禁止為預設服務帳戶授予自動角色。

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

根據貴機構的政策設定，系統可能會自動為預設服務帳戶授予專案的編輯者角色。強烈建議您 套用 iam.automaticIamGrantsForDefaultServiceAccounts 機構政策限制，停用自動角色授予功能。如果您是在 2024 年 5 月 3 日之後建立機構，系統預設會強制執行這項限制。

如果您停用自動角色授予功能，就必須決定要將哪些角色授予預設服務帳戶，然後自行授予這些角色。

如果預設服務帳戶已具有「編輯者」角色，建議您將「編輯者」角色替換為權限較低的角色。如要安全地修改服務帳戶的角色，請使用政策模擬器查看變更的影響，然後授予及撤銷適當的角色。

授予 Compute Engine 執行個體的存取權

存取存放區的 VM 執行個體必須同時具備 Artifact Registry 權限和儲存空間存取權範圍。

服務帳戶的存取層級取決於授予服務帳戶的 IAM 角色，但 VM 執行個體的存取權範圍會根據執行個體上透過 gcloud CLI 和用戶端程式庫發出的要求，定義預設的 OAuth 範圍。因此，透過應用程式預設憑證驗證時，存取權範圍可能會進一步限制 API 方法的存取。

Compute Engine 會使用下列預設值：

• Compute Engine 預設服務帳戶是 VM 執行個體的身分。服務帳戶電子郵件地址的後置字串為 @developer.gserviceaccount.com。
• 如果您尚未停用這項行為，預設服務帳戶就會具備 IAM 基本編輯者角色。
• 您使用預設服務帳戶建立的執行個體具有 Compute Engine 預設存取權範圍，包括儲存空間的唯讀存取權。雖然「編輯者」角色通常會授予寫入存取權，但 read-only 儲存空間存取範圍會限制執行個體服務帳戶，僅可從同一個專案中的任何存放區下載構件。

如要設定服務帳戶的存取權範圍，請在下列情況下進行：

• VM 服務帳戶需要存取其他專案中的存放區。
• VM 服務帳戶需要執行的動作，除了讀取存放區中的構件外，還包括這項操作通常會在需要推送映像檔或執行 Artifact Registry gcloud 指令的 VM 上套用第三方工具。

如要設定角色並設定存取範圍，請按照下列步驟操作：

1. 在含有 VM 執行個體的專案中，取得 Compute Engine 預設服務帳戶的名稱。服務帳戶電子郵件地址的後置字串為 @developer.gserviceaccount.com。

2. 在含有存放區的專案中，授予權限，讓服務帳戶可以存取存放區。

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

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

   2. 使用下列指令設定存取範圍：

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

      將 SCOPE 替換為適當的值。

      • Docker 支援下列選項：

        • storage-ro：只授予提取圖片的讀取權限。
        • storage-rw - 授予推送或提取圖片的讀取和寫入權限。
        • cloud-platform：查看及管理Google Cloud 服務中的資料 (包括中繼資料)。

      • 如要使用其他格式，您必須使用 cloud-platform 範圍。

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

授予 Google Kubernetes Engine 叢集的存取權

只要符合下列所有要求，GKE 叢集和節點集區就能在不需要任何額外設定的情況下，提取容器：

• GKE 與 Artifact Registry 位於同一專案
• 節點使用預設服務帳戶，即 Compute Engine 預設服務帳戶
• 節點是透過以下方式建立，並具備儲存空間的讀取權限：
  • 使用 Compute Engine 的預設存取範圍。
  • 授予 cloud-platform 存取範圍或其他範圍，其中包含對儲存空間的讀取存取權。
• 您執行的是支援的版本 GKE

如果您的 GKE 環境不符合這些規定，則授予存取權的指示會視您是否使用 Compute Engine 預設服務帳戶或使用者提供的服務帳戶做為節點的 ID 而定。

預設服務帳戶

下列設定要求適用於 Compute Engine 預設服務帳戶：

1. 如果 GKE 位於與 Artifact Registry 不同的專案中，請授予服務帳戶必要權限。

2. 如要推送映像檔、與容器以外格式的存放區互動，或從叢集執行 gcloud 指令，您必須在建立叢集或節點集區時，為服務帳戶設定存取權範圍。

3. 如果您未使用支援的版本，請設定 imagePullSecrets。

使用者提供的服務帳戶

如果您想使用使用者提供的服務帳戶做為叢集的身份識別資訊，必須：

1. 授予服務帳戶所需權限，該服務帳戶位於執行 Artifact Registry 的Google Cloud 專案中。

2. 根據預設，使用使用者提供的服務帳戶建立叢集或節點集區時，會授予 cloud-platform 存取權範圍。

   如果您將 --scopes 標記與 gcloud container clusters create 或 gcloud container node-pools create 指令搭配使用，必須加入適當的存取範圍，以便與 Artifact Registry 搭配使用。

設定存取權範圍

存取權範圍是指定 Compute Engine VM 授權的傳統方法。如要從 Artifact Registry 存放區提取映像檔，GKE 節點必須具備儲存空間唯讀存取範圍，或其他包含儲存空間讀取存取權的儲存空間存取範圍。

您只能在建立叢集或節點集區時設定存取權範圍。您無法變更現有節點的存取權範圍。

• 如果您使用 Compute Engine 預設服務帳戶，GKE 會使用 Compute Engine 預設存取範圍建立節點，其中包括儲存空間的唯讀存取權。
• 如果您使用使用者提供的服務帳戶，GKE 會使用 cloud-platform 範圍建立節點，這是大多數Google Cloud 服務所需的範圍。

如要在建立叢集時指定存取範圍，請執行下列指令：

gcloud container clusters create NAME --scopes=SCOPES

如要在建立節點集區時指定存取範圍，請執行下列指令：

gcloud container node-pools create NAME --scopes=SCOPES

替換下列值：

• NAME 是叢集或節點集區的名稱。

• SCOPES 是以逗號分隔的清單，列出要授予的存取範圍。

  • 如要存取 Docker 存放區，請使用下列其中一個權限範圍：

  • storage-ro：授予提取圖片的唯讀權限。

  • storage-rw - 授予推送或提取圖片的讀取和寫入權限。

  • cloud-platform：查看及管理Google Cloud 服務中的資料 (包括中繼資料)。

  • 如要存取其他存放區，您必須使用 cloud-platform 範圍。

  如需範圍的完整清單，請參閱 gcloud container clusters create 或 gcloud container node-pools create 的說明文件。

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

設定 imagePullSecret

如何設定 imagePullSecret：

1. 在使用 GKE 的專案中，找出 Compute Engine 預設服務帳戶。帳戶電子郵件地址的後置字串為 @developer.gserviceaccount.com。

2. 下載服務帳戶金鑰。

3. 在含有存放區的專案中，請確認您已授予存放區權限。

4. 在叢集專案中，使用服務帳戶金鑰建立名為 artifact-registry 的 imagePullSecret 機密。

   kubectl create secret docker-registry artifact-registry \
   --docker-server=https://LOCATION-docker.pkg.dev \
   --docker-email=SERVICE-ACCOUNT-EMAIL \
   --docker-username=_json_key \
   --docker-password="$(cat KEY-FILE)"
   

   更改下列內容：

   • LOCATION 是存放區的地區或多地區位置。
   • SERVICE-ACCOUNT-EMAIL 是 Compute Engine 服務帳戶的電子郵件地址。
   • KEY-FILE 是服務帳戶金鑰檔案的名稱。例如 `key.json`。

5. 開啟預設服務帳戶：

   kubectl edit serviceaccount default --namespace default

   Kubernetes 叢集中的每個命名空間都有一個名為 default 的預設服務帳戶。這個預設服務帳戶用於提取容器映像檔。

6. 將新建立的 imagePullSecret 機密金鑰新增至預設服務帳戶：

   imagePullSecrets:
   - name: artifact-registry
   

   您的服務帳戶現在應如下所示：

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: default
     namespace: default
     ...
   secrets:
   - name: default-token-zd84v
   # The secret you created:
   imagePullSecrets:
   - name: artifact-registry
   

從現在起，在目前 default 命名空間中建立的任何新 Pod 都會定義 imagePullSecret 密鑰。

Artifact Registry 服務帳戶

Artifact Registry 服務代理是 Google 代管的服務帳戶，可在與 Google Cloud服務互動時代表 Artifact Registry 執行操作。如要進一步瞭解該帳戶及其權限，請參閱「Artifact Registry 服務帳戶」。

後續步驟

設定權限後，請進一步瞭解如何處理構件。

• 容器映像檔：Docker、Helm
• 語言套件：Java、Node.js、Python、Go
• 作業系統套件：Debian、RPM