在 Artifact Registry 儲存 Go 模組

Artifact Registry Go 存放區可讓您在專案中儲存、控管版本及共用私人 Go 模組。在本快速入門導覽課程中，您將建立存放區、封裝並上傳範例模組，然後將模組匯入為依附元件。

事前準備

  1. 登入 Google 帳戶。

    如果還沒有帳戶，請 註冊新帳戶。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Artifact Registry API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  13. To initialize the gcloud CLI, run the following command: 

    gcloud init
  14. 安裝 Go 的最新主要版本或倒數第二個主要版本。系統不支援較舊版本。
  15. 安裝 package-go-module gcloud CLI 外掛程式： 
    gcloud components install package-go-module

必要的角色

如要取得建立及管理 Artifact Registry Go 模組存放區所需的權限，請要求管理員授予您專案的 Artifact Registry 管理員 (roles/artifactregistry.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

建立存放區

如要建立及設定新存放區，請按照下列步驟操作：

  1. 執行下列指令來建立新的存放區。

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=go \
    --location=LOCATION \
    --description=DESCRIPTION

    更改下列內容：

    • REPOSITORY 是存放區的名稱。專案中每個存放區位置的存放區名稱不得重複。
    • LOCATION 是存放區的區域或多區域位置。如果已設定預設值，則可省略這個旗標。如要查看支援的位置清單，請執行 gcloud artifacts locations list 指令。
    • DESCRIPTION 是存放區的選填說明。請勿輸入機密資料，因為存放區說明不會加密。

  2. 執行下列指令，查看存放區詳細資料。

      gcloud artifacts repositories describe --location=LOCATION REPOSITORY

    輸出結果會與下列內容相似：

      Encryption: Google-managed key
  Repository Size: 0.000MB
  createTime: '2022-06-03T20:20:01.644813Z'
  format: GO
  mode: STANDARD_REPOSITORY
  name: projects/my-project/locations/us-west1/repositories/my-repo
  updateTime: '2022-06-03T20:20:01.644813Z'

設定 gcloud 指令的預設值

您可以設定專案、存放區和位置值的預設值，簡化 gcloud CLI 指令。設定預設值後，就不需要 --project、--location 和 --repository 標記。

封裝及上傳 Go 模組

package-go-module gcloud CLI 外掛程式會封裝 Go 模組，讓您使用 gcloud 指令將模組加上版本並上傳至 Artifact Registry。

建立 Go 模組

首先，請建立簡單的 Go 模組，並上傳至存放區。

  1. 在主目錄中，為模組建立名為「foo」的目錄

    mkdir foo

  2. 將目錄變更為模組的目錄，然後執行 go mod init，為模組建立 go.mod 檔案。

      cd foo \
  go mod init example.com/foo

    將 example.com/foo 替換為模組路徑。詳情請參閱「Go 模組參考資料」。

  3. 在 foo 目錄中建立 foo.go 檔案，並加入以下內容：

    
package foo

const HelloWorld = "Hello World!"

封裝及上傳模組

將模組封裝並上傳至存放區：

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --version=VERSION \
      --source=SOURCE_LOCATION

更改下列內容：

  • PROJECT 替換為您的 Google Cloud 專案 ID。
  • REPOSITORY：儲存套件的存放區名稱。
  • LOCATION，並提供存放區的區域或多區域位置。
  • example.com/foo，並提供模組路徑。詳情請參閱 Go 模組參考資料。
  • VERSION，其中 vX.Y.Z 是模組的語意化版本，X 是主要版本，Y 是次要版本，Z 則是修補程式版本。
  • SOURCE_LOCATION，並提供 Go 模組根目錄的路徑。如果省略 --source 旗標，預設為目前目錄。

模組會上傳至 Artifact Registry。

如要進一步瞭解如何建立 Go 模組，請參閱這篇教學課程。

列出模組

設定預設值後，請執行下列指令，檢查預設專案、存放區和位置中上傳的 Go 模組：

  gcloud artifacts packages list

輸出結果會與下列內容相似：

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

查看模組版本詳細資料

設定預設值後，執行下列指令即可查看預設專案、存放區和位置中的模組版本：

  gcloud artifacts versions list --package=MODULE_PATH

輸出結果會與下列內容相似：

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

下載模組

如要匯入儲存在 Artifact Registry 中的模組，您必須指示 Go 從 Artifact Registry 尋找依附元件，並略過核對和資料庫。

設定 Go 環境

  1. 指示 Go 依序從 Artifact Registry、公開 Go 模組 Proxy 和來源下載模組：

      export GOPROXY=https://LOCATION-go.pkg.dev/PROJECT/REPOSITORY,https://proxy.golang.org,direct

    更改下列內容：

    • LOCATION 是存放區的單一區域或多區域位置。
    • PROJECT 是您的 Google Cloud 專案 ID。
    • REPOSITORY 是儲存套件的存放區名稱。

  2. 使用公開的總和檢查碼資料庫，排除要檢查的模組：

      export GONOSUMDB=MODULE_PATH_REGEX

    如要排除多個模組，請將 MODULE_PATH_REGEX 替換成模組路徑或規則運算式。

    如要排除模組 example.com/foo，不使用公開核對和資料庫檢查，請執行下列指令：

      export GONOSUMDB=example.com/foo

    如要排除所有模組路徑開頭為 example.com 的模組，不使用公開核對和資料庫檢查，請執行下列指令：

      export GONOSUMDB=example.com/*

向 Artifact Registry 進行驗證

從 Artifact Registry 下載封裝的 Go 模組做為依附元件時，Go 二進位檔會使用 netrc 檔案中的憑證向 Artifact Registry 進行驗證。如要簡化驗證程序，可以使用 Go 憑證輔助函式，更新 netrc 檔案中的權杖，以便向 Artifact Registry 進行驗證。

您可以使用 netrc 環境變數設定 netrc 檔案的位置。如果未設定 NETRC 變數，go 指令會在類 UNIX 平台讀取 $HOME/.netrc，或在 Windows 讀取 %USERPROFILE%\_netrc。

Artifact Registry 支援下列驗證方法。

短期憑證 (建議)
使用 Artifact Registry Go 憑證輔助函式工具，更新 netrc 檔案中的驗證權杖。
使用服務帳戶金鑰

如果無法在環境中使用憑證進行驗證，請選用這個選項。將未加密的服務帳戶金鑰新增至 .netrc 檔案。

將 Go 憑證輔助程式新增至 GONOPROXY

使用 Go 憑證輔助程式前，請先將其新增至 GONOPROXY 清單，強制 Go 直接從 GitHub 下載。如要直接從來源下載其他模組，可以將這些模組加入以半形逗號分隔的清單，如下例所示：

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

其中 MODULE_PATH1 和 MODULE_PATH2 是要從來源下載的模組路徑。

如要將 Go 憑證輔助程式新增至 GONOPROXY 清單，並執行該程式來設定憑證，請按照下列步驟操作：

  1. 將 Go 憑證輔助程式新增至 GONOPROXY

      export GONOPROXY=github.com/GoogleCloudPlatform/artifact-registry-go-tools

  2. 執行下列指令，使用 Go 模組套件工具將 Artifact Registry 憑證新增至 netrc 檔案：

      GOPROXY=proxy.golang.org \
      go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
      add-locations --locations=LOCATION \
      [--json_key=path/to/service/account/key.json]

    其中 LOCATION 是存放區的區域或多區域位置。如要新增多個地點，請以半形逗號分隔各個地點。

    Go 憑證輔助程式會在 netrc 檔案中新增設定，用於向 Artifact Registry 驗證。如果您傳遞 --json_key 旗標，金鑰會新增至 netrc 檔案，用於密碼驗證。

將模組做為依附元件

  1. 如果您使用短期憑證向 Artifact Registry 驗證，則必須執行下列指令，重新整理 OAuth 權杖：

      GOPROXY=proxy.golang.org \
  go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 refresh

  2. 在主目錄中，建立名為「bar」的目錄

      mkdir bar

  3. 將目錄變更為模組的目錄，然後執行 go mod init，為套件建立 go.mod 檔案。

      cd bar \
  go mod init example.com/bar

    將 example.com/bar 替換為模組路徑。詳情請參閱 Go 模組參考資料。

  4. 如要要求 Artifact Registry 中儲存的 foo 版本，請編輯 go.mod 檔案，使其類似下列內容：

    
module example.com/bar

go 1.19

require example.com/foo v0.1.0

    更改下列內容：

    • example.com/foo 是必要模組的模組路徑
    • v0.1.0 是儲存在 Artifact Registry 中的版本

  5. 在 bar 目錄中建立 main.go 檔案，並加入以下內容：

      
  package main

  import (
    "fmt"

    foo "example.com/foo"
  )

  func main() {
    fmt.Println(foo.HelloWorld)
  }

  6. 執行 go mod tidy 下載依附元件，包括 foo 套件：

      go mod tidy

  7. 執行 bar 模組：

      go run .

    輸出結果會與下列內容相似：

      Hello World!

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。

如要避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。移除存放區之前，請先確認要保留的模組均已存放於其他位置。

  1. 如要刪除存放區，請按照下列指示操作：

      gcloud artifacts repositories delete \
      --location=LOCATION \
      --project=PROJECT \
      REPOSITORY

    更改下列內容：

    • LOCATION：存放區的區域或多區域位置。
    • PROJECT 改成您的 Google Cloud 專案 ID。
    • REPOSITORY：存放區名稱。

  2. 如要移除您為使用中的 gcloud 設定建立的預設存放區和位置設定，請執行下列指令：

      gcloud config unset artifacts/repository
  gcloud config unset artifacts/location

後續步驟