建立虛擬存放區

本頁說明如何建立 Artifact Registry 虛擬存放區。

虛擬存放區可做為單一存取點，從一或多個上游存放區下載、安裝或部署相同格式的構件。上游存放區可以是 Artifact Registry 標準或遠端存放區。

其他存放區模式包括：

• 標準：預設存放區模式。您可以將私人套件等構件直接上傳或發布至標準存放區。雖然您可以直接從個別標準存放區下載，但透過虛擬存放區存取存放區群組，可簡化工具設定。
• 遠端 (僅限語言套件存放區)：從 Maven Central 或 PyPI 等公開存放區提取構件時，會透過快取。這個服務會做為公開存放區的 Proxy，讓您進一步控管外部依附元件。

如要進一步瞭解虛擬存放區的運作方式，請參閱「虛擬存放區總覽」。

事前準備

啟用 Artifact Registry，包括啟用 Artifact Registry API，以及安裝最新版 Google Cloud CLI。

必要的角色

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

• 建立虛擬存放區，並授予個別存放區的存取權： Artifact Registry 管理員 (roles/artifactregistry.admin) 在 Google Cloud 專案中
• 在專案層級授予存放區存取權： 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 在 Google Cloud 專案 Google Cloud 上
• 在資料夾層級授予存放區存取權： 資料夾的資料夾管理員 (roles/resourcemanager.folderAdmin)
• 在機構層級授予存放區存取權： 機構管理員 (roles/resourcemanager.organizationAdmin) 在 Google Cloud 機構 Google Cloud

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

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

如果上游存放區位於其他專案，則上游存放區所在專案的管理員必須具備管理這些存放區存取權的權限。

建立上游存放區

設定虛擬存放區前，請先建立要透過虛擬存放區提供的上游存放區。

1. 在上游存放區所在的相同 Google Cloud區域中，建立虛擬存放區。

   • 建立標準存放區
   • 建立遠端存放區

2. 虛擬存放區會使用 Artifact Registry 服務代理程式，向上游存放區進行驗證。您必須授予服務代理程式上游存放區的讀取權限。

   您可以在專案層級將 Artifact Registry Reader 角色授予 Artifact Registry 服務代理，這樣就不必授予個別上游存放區的存取權。

   在每個含有上游存放區的專案中，執行下列指令：

   gcloud projects add-iam-policy-binding UPSTREAM_PROJECT_ID \
       --member serviceAccount:service-VIRTUAL-REPO-PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com \
       --role roles/artifactregistry.reader
   

   地點

   • UPSTREAM_PROJECT_ID 是具有上游存放區的 Google Cloud 專案 ID。
   • VIRTUAL_REPO_PROJECT_NUMBER 是虛擬存放區專案的專案編號。 Google Cloud

   或者，如要授予服務代理範圍較窄的角色，請將 artifactregistry.repositories.readViaVirtualRepository 權限新增至自訂角色，然後將該角色授予服務代理。

   如要進一步瞭解如何授予權限，請參閱存取權控管說明文件。

建立虛擬存放區

建立存放區時，您必須設定下列設定，這些設定在存放區建立後就無法變更：

• 構件格式。
• 存放區模式 (如果所選格式有多種模式)。
• 存放區位置。
• 使用 Google 擁有及代管的 加密金鑰，或客戶管理的加密金鑰進行加密。Artifact Registry 預設會使用、Google 擁有及管理的 加密金鑰。

Artifact Registry 會強制執行機構政策限制，規定必須使用 CMEK 加密資源，或限制可用於 CMEK 保護措施的 Cloud KMS 金鑰。

使用 Google Cloud 控制台建立虛擬存放區

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

   開啟「存放區」頁面

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

3. 指定存放區名稱。專案中每個存放區位置的存放區名稱不得重複。

4. 選取存放區格式。

5. 在「Repository mode」(存放區模式) 下，選取「Virtual」(虛擬)。

6. 在「虛擬存放區上游」下方，按一下「新增上游」，即可新增上游存放區。

   • 上游存放區可以是標準、遠端或虛擬存放區。
   • 上游存放區必須與虛擬存放區位於相同位置，但可以位於不同 Google Cloud 專案。
   • 上游存放區的構件格式必須與虛擬存放區相同。

   請分別為每個上游存放區指定優先順序和政策名稱，優先順序值較高的項目會優先於值較低的項目。 優先順序值之間要留有空間，方便您新增優先順序介於現有值之間的上游存放區。

7. 在「位置類型」下方，選擇存放區的位置：

   1. 選擇位置類型：區域或多區域。地點清單會根據您的選取項目變更。

   2. 在「Region」(區域) 或「Multi-region」(多區域) 清單中選取位置。

   如要瞭解位置類型和支援的位置，請參閱「存放區位置」一文。

8. 為存放區新增說明。說明有助於識別存放區的用途，以及其中包含的構件類型。

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

9. 如要使用標籤整理存放區，請按一下「新增標籤」，然後輸入標籤的鍵/值組合。建立存放區後，您可以新增、編輯或移除標籤。

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

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

11. 點選「建立」。

Artifact Registry 會建立存放區，並將其新增至存放區清單。

建立存放區後，請按照下列步驟操作：

• 授予存放區存取權。

• 設定 Docker、套件管理員和其他第三方用戶端，以便向存放區進行驗證。

  • 容器映像檔：Docker、Helm
  • 語言套件：Java、Node.js、Python、Go
  • 其他：Kubeflow 管道範本

使用 gcloud CLI 建立虛擬存放區

如要建立虛擬存放區，請在政策檔案中定義上游存放區，然後使用政策檔案建立存放區。

1. 以 JSON 格式建立上游政策檔案，並採用下列設定：

   [{
   "id" : "POLICY_ID",
   "repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
   "priority" : PRIORITY
   }, {...}]
   

   • POLICY_ID 是政策的名稱。政策中的每個上游存放區都必須有不重複的政策 ID。

   • UPSTREAM_REPO_RESOURCE_NAME 是上游存放區的名稱，格式如下：

     projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY
     

     • 上游存放區可以是標準、遠端或虛擬存放區。
     • 上游存放區必須與虛擬存放區位於相同位置，但可以位於不同 Google Cloud 專案。
     • 上游存放區的構件格式必須與虛擬存放區相同。

   • PRIORITY 是一個整數，代表上游存放區的優先順序。優先順序值較大的項目會優先於值較小的項目。

   以下範例顯示名為 policies.json 的政策檔案，其中包含四個上游存放區。upstream1 的 priority 值最高， 因此 Artifact Registry 會優先搜尋這個值。upstream-test 的 priority 值最低，因此 Artifact Registry 會最後搜尋這個項目。upstream2 和 upstream3 的優先順序相同。如果 Artifact Registry 在優先順序相同的存放區中找到要求的套件，則可從任一存放區提供套件。

   [{
   "id" : "upstream1",
   "repository" : "projects/myproject/locations/us-west1/repositories/python-repo1",
   "priority" : 100
   }, {
   "id" : "upstream2",
   "repository" : "projects/myproject/locations/us-west1/repositories/python-repo2",
   "priority" : 80
   }, {
   "id" : "upstream3",
   "repository" : "projects/myproject/locations/us-west1/repositories/python-repo2",
   "priority" : 80
   }, {
   "id" : "upstream-test",
   "repository" : "projects/myproject/locations/us-west1/repositories/python-test-repo",
   "priority" : 20
   }]
   

   這個範例也會在優先順序值之間保留空格。這些間隙可彈性新增上游存放區，優先順序介於現有值之間。舉例來說，您可以新增優先順序為 70 的 upstream-3 存放區，讓 Artifact Registry 先搜尋該存放區，再搜尋 upstream-test。

   建議您將上游政策檔案儲存在來源控制系統中，以便日後重複使用，變更上游存放區設定及追蹤歷來變更。

2. 在上游政策檔案所在的目錄中，執行下列指令來建立虛擬存放區：

   gcloud artifacts repositories create VIRTUAL-REPOSITORY-NAME \
       --project=PROJECT_ID \
       --repository-format=FORMAT \
       --mode=virtual-repository \
       --location=LOCATION \
       --description="DESCRIPTION" \
       --upstream-policy-file=UPSTREAM_POLICY_FILE
   

   更改下列內容：

   • VIRTUAL-REPOSITORY-NAME 是虛擬存放區的名稱。
   • PROJECT_ID 是您要建立虛擬存放區的專案 ID。如果省略這個標記，系統會使用目前或預設專案。
   • FORMAT 是存放區的格式。可用的值如下：
     • apt (不公開預先發布版)
     • docker
     • go
     • maven
     • npm
     • python
     • yum (不公開預先發布版)

   • LOCATION 是存放區的區域或多區域位置。如果您設定 default，可以省略這個旗標。如要查看支援的位置清單，請執行下列指令：

     gcloud artifacts locations list
     

   • DESCRIPTION：(選用) 提供存放區說明。 請勿加入機密資料，因為存放區說明不會經過加密。

   • UPSTREAM_POLICY_FILE 是上游政策檔案的路徑。

   舉例來說，下列指令會在 us-west1 地區中，為 Python 套件建立名為 virtual-repo 的虛擬存放區，並使用 policies.json 中的設定。

   gcloud artifacts repositories create virtual-repo \
   --repository-format=python \
   --mode=virtual-repository \
   --location=us-west1 \
   --description="Python virtual repository" \
   --upstream-policy-file=policies.json
   

Artifact Registry 會建立虛擬存放區。

使用 Terraform 建立虛擬存放區

使用 google_artifact_registry_repository 資源建立存放區。 必須使用 terraform-provider-google 以上版本。5.0.0

如果您是初次使用 Terraform 搭配 Google Cloud，請參閱 HashiCorp 網站上的「Get Started - Google Cloud」(開始使用 - Google Cloud) 頁面。

下列範例定義了供應商、Terraform 資源名稱為 my-repo 的虛擬存放區，以及 Terraform 資源名稱為 my-repo-upstream 的上游存放區。

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "docker"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "docker"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "maven"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "maven"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

provider "google" {
project = "my-project"
}

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

location = "us-central1"
repository_id = "my-repo"
description = "Maven repository"
format = "MAVEN"
maven_config {
  version_policy = "RELEASE"
}
}

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "npm"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "npm"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "python"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "python"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

Artifact Registry 會建立存放區。執行下列指令，查看存放區的說明：

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

建立存放區後，請按照下列步驟操作：

• 授予存放區存取權。

• 設定 Docker、套件管理員和其他第三方用戶端，以便向存放區進行驗證。

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

更新上游存放區

您可以變更上游存放區清單，或調整上游存放區的優先順序。

編輯存放區說明

您可以透過 Google Cloud 控制台或 gcloud CLI 變更存放區說明。

gcloud artifacts repositories update REPOSITORY \
    --project=PROJECT \
    --location=LOCATION \
    --description="DESCRIPTION"