在 Artifact Registry 中儲存 Go 模組

在 Artifact Registry 中儲存 Go 模組

設定私有 Artifact Registry Go 存放區、將模組上傳至該存放區，並將模組做為依附元件使用。

事前準備

Sign in to your Google Account.

If you don't already have one, sign up for a new account.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

1. 安裝 Go 1.15 以上版本。
2. 安裝 package-go-module gcloud CLI 外掛程式：
   

   gcloud components install package-go-module

建立存放區

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

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. 在 GONOPROXY 中新增 Go 憑證輔助程式

     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
   

後續步驟

• 進一步瞭解如何設定驗證機制。
• 瞭解如何管理存放區。
• 瞭解如何管理 Go 模組。
• 參閱DevOps相關資源，並探索開發運作研究與評估研究計畫。