為 Go 設定驗證

使用 Artifact Registry 驗證用戶端環境,即可儲存私人 Go 模組,並擷取這些模組做為建構依附元件。

驗證選項

上傳和下載套件的驗證設定不同。

上傳內容驗證

將 Go 模組封裝並上傳至 Artifact Registry 時,gcloud CLI 工具會依下列順序在環境中尋找憑證,以便設定驗證機制,除非您傳遞 --json_key 旗標來使用服務帳戶金鑰。

  1. 應用程式預設憑證 (ADC):這項策略會依下列順序尋找憑證:

    1. GOOGLE_APPLICATION_CREDENTIALS 環境變數中定義的憑證。

    2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Run functions 的預設服務帳戶提供的憑證。

  2. Google Cloud CLI 提供的憑證,包括 gcloud auth application-default login 指令的使用者憑證。

GOOGLE_APPLICATION_CREDENTIALS 變數可明確指定用於驗證的帳戶,讓疑難排解更輕鬆。如果不使用變數,請確認 ADC 可能使用的任何帳戶都具備必要權限。舉例來說,Compute Engine VM、Google Kubernetes Engine 節點和 Cloud Run 修訂版本的預設服務帳戶,具備存放區的唯讀存取權。如要使用預設服務帳戶從這些環境上傳,請務必修改權限。

下載驗證

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

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

使用 netrc 檔案中的憑證時,Artifact Registry 支援下列驗證方式:

短期憑證 (建議)
使用 Artifact Registry Go 憑證輔助工具,以環境中的憑證更新 netrc 檔案中的驗證權杖,或手動將 Artifact Registry 憑證新增至 netrc 檔案。
使用服務帳戶金鑰
如果無法使用環境中的憑證進行驗證,請選用這個選項。您可以使用 Artifact Registry Go 憑證輔助工具,將未加密的服務帳戶金鑰新增至 netrc 檔案,或手動新增至檔案。

事前準備

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

    gcloud components install package-go-module

設定 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 憑證新增至 netrc 檔案

  1. 執行下列指令,使用 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_JSON_KEY
    

    其中:

    • LOCATION 是存放區的區域或多區域位置。如要新增多個位置,請以逗號分隔清單。
    • PATH_TO_JSON_KEY 選用。服務帳戶金鑰的路徑。

      Go 憑證輔助程式會將設定新增至 netrc 檔案,以便向 Artifact Registry 進行驗證。如果傳遞 --json_key 旗標,系統會將金鑰新增至 netrc 檔案,用於密碼驗證。

  2. 如果您使用短期憑證向 Artifact Registry 驗證,則必須先執行下列指令重新整理 OAuth 權杖,才能將模組做為依附元件使用:

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

使用服務帳戶金鑰進行驗證

如果需要使用使用者名稱和密碼進行驗證,請採用這個方法。

服務帳戶金鑰是長效憑證。請按照下列規範限制存放區存取權:

  • 建議您使用專屬服務帳戶與存放區互動。
  • 授予服務帳戶所需的最低 Artifact Registry 角色。例如,將 Artifact Registry 讀取者角色指派給僅下載構件的服務帳戶。
  • 如果貴組織中的群組需要特定存放區的不同存取層級,請在存放區層級 (而非專案層級) 授予存取權。
  • 遵循管理憑證的最佳做法。

如要設定驗證機制,請按照下列步驟操作:

  1. 建立服務帳戶,代表應用程式執行操作,或選擇用於自動化的現有服務帳戶。

    您需要服務帳戶金鑰檔案的位置,才能設定 Artifact Registry 驗證。如果是現有帳戶,您可以在「Service Accounts」(服務帳戶) 頁面查看金鑰及建立新金鑰。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 授予服務帳戶適當的 Artifact Registry 角色,提供存放區存取權。

  3. 執行下列指令,使用 Go 憑證輔助程式將服務帳戶憑證新增至 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_JSON_KEY
    

    其中:

    • LOCATION 是存放區的區域或多區域位置。如要新增多個位置,請以逗號分隔清單。
    • PATH_TO_JSON_KEY 是服務帳戶 JSON 金鑰檔案的路徑。

      Go 憑證輔助程式會將服務帳戶金鑰新增至 netrc 檔案,用於密碼驗證。

您也可以手動將服務帳戶金鑰新增至 netrc 檔案,格式如下:

machine LOCATION.pkg.dev
login _json_key_base64
password KEY

更改下列內容:

  • LOCATION:存放區的區域或多區域位置。
  • KEY 替換為服務帳戶金鑰檔案中以 Base64 編碼的金鑰。

將 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 檔案,用於密碼驗證。

後續步驟