為 Python 套件存放區設定 Artifact Registry 驗證機制

本頁面說明如何透過 Artifact Registry Python 套件存放區設定驗證機制。

使用第三方應用程式連線至存放區時，必須對 Artifact Registry 進行驗證。

您不需要為 Cloud Build 或 Google Cloud執行階段環境 (例如 Google Kubernetes Engine 和 Cloud Run) 設定驗證程序，但應確認已設定必要的權限。

事前準備

  1. 如果目標存放區不存在，請建立新的 Python 套件存放區。
  2. 確認是否已安裝 Python 3。如需安裝操作說明，請參閱Google Cloud Python 設定教學課程。
  3. 確認您使用的使用者帳戶或服務帳戶具備存取存放區所需的權限。

  4. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

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

  5. (選用) 設定 gcloud CLI 指令的預設值。

總覽

Artifact Registry 支援下列驗證方法。

Python 鑰匙圈程式庫 (建議)
Artifact Registry 提供鑰匙圈後端，可儲存用於連線至 Artifact Registry 存放區的憑證。
密碼驗證
如果您無法使用鑰匙圈，且需要支援基本密碼驗證的選項，請使用這個選項。

本文件中的操作說明說明如何將 pip 設為 pip 搜尋套件的唯一套件索引。建議您使用虛擬存放區，在 Artifact Registry 中的私人套件和 PyPI 中的公開套件中搜尋套件，而不要在 pip 設定檔中設定多個套件索引。pip 工具不會以任何特定順序搜尋套件索引，因此使用者可能會誤下載或安裝與私人套件名稱相同的公開套件。虛擬存放區可讓您為上游來源設定優先順序，以降低這種依附元件混淆的風險。

使用鑰匙圈進行驗證

Python keyring 程式庫可讓應用程式存取keyring 後端，也就是作業系統和第三方憑證儲存庫。

Artifact Registry 提供 keyrings.google-artifactregistry-auth 密鑰圈後端，用於處理 Artifact Registry 存放區的驗證作業。

憑證搜尋順序

使用 Artifact Registry 密鑰圈後端時，憑證不會儲存在 Python 專案中。相反地，Artifact Registry 會依照以下順序搜尋憑證：

  1. 應用程式預設憑證 (ADC)：這種策略會依照以下順序尋找憑證：

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

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

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

GOOGLE_APPLICATION_CREDENTIALS 變數會明確指出用於驗證的帳戶，方便排解問題。如果您未使用變數，請確認 ADC 可能會使用的任何帳戶都具備必要的權限。舉例來說，Compute Engine VM、Google Kubernetes Engine 節點和 Cloud Run 修訂版本的預設服務帳戶，對存放區只有唯讀存取權。如果您打算使用預設服務帳戶從這些環境上傳資料，就必須修改權限。

設定鑰匙圈

如要設定 Artifact Registry 密鑰圈後端的驗證機制，請按照下列步驟操作：

  1. 安裝鑰匙圈程式庫。

    pip install keyring

  2. 安裝 Artifact Registry 後端。

    pip install keyrings.google-artifactregistry-auth

  3. 列出後端，確認安裝作業。

    keyring --list-backends

    清單應包含

    • ChainerBackend(priority:10)
    • GooglePythonAuth(priority: 9)

  4. 執行下列指令，顯示存放區設定，以便新增至 Python 專案。

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

    替換下列值：

    • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
    • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令中省略這個旗標時，系統就會使用該存放區。
    • LOCATION 是存放區的位置 (單一區域或多區域)。

  5. 在 .pypirc 檔案中新增下列設定。預設位置如下：

    • Linux 和 macOS：$HOME/.pypirc
    • Windows：%USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    替換下列值：

    • PYTHON-REPO-ID 是存放區的 ID，可透過 Twine 等工具參照。
    • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
    • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令中省略這個旗標時，系統就會使用該存放區。
    • LOCATION 是存放區的位置 (單一區域或多區域)。

  6. 將存放區新增至 pip 設定檔。檔案位置取決於您要更新的是每位使用者檔案，還是特定虛擬環境的檔案。

    針對與作業系統使用者相關聯的檔案：

    • Unix：$HOME/.config/pip/pip.conf 或 $HOME/.pip/pip.conf
    • macOS：/Library/Application Support/pip/pip.conf 或 $HOME/.config/pip/pip.conf
    • Windows：%APPDATA%\pip\pip.ini 或 %USERPROFILE%\pip\pip.ini

    虛擬環境：

    • Unix 和 macOS：$VIRTUAL_ENV/pip.conf
    • Windows：%VIRTUAL_ENV%\pip.ini

    如要設定 pip 只搜尋存放區，請使用 index-url 設定，並確認沒有其他套件索引已設定 extra-index-url 設定。

    [global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

    存放區路徑結尾的 /simple/ 字串表示存放區實作 Python 簡易存放區 API。

Python 環境現在已設定為透過 Artifact Registry 進行驗證。

使用鑰匙圈驗證使用者憑證

設定鑰匙圈後，您就可以在 gcloud CLI 中使用鑰匙圈和使用者憑證。請先登入 Google Cloud CLI，再連線至 Python 套件存放區。

執行下列指令：

gcloud auth login

使用服務帳戶憑證進行鑰匙圈驗證

設定鑰匙圈後，您可以設定服務帳戶進行驗證。

  1. 建立服務帳戶，或選擇用於自動化功能的現有服務帳戶。
  2. 授予服務帳戶特定的 Artifact Registry 角色，以便提供存放區存取權。

  3. 請使用下列其中一種方式，以服務帳戶進行驗證：

    • 應用程式預設憑證 (建議)

      將服務帳戶金鑰檔案位置指派給 GOOGLE_APPLICATION_CREDENTIALS 變數，這樣 Artifact Registry 憑證輔助程式就能在連線至存放區時取得您的金鑰。

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • gcloud CLI 憑證

      連線至存放區之前，請先以服務帳戶登入。如果您是透過 Compute Engine VM 連線至存放區，請避免使用這個選項，因為 Artifact Registry 會先在 gcloud CLI 中找到 VM 服務帳戶憑證。

      gcloud auth activate-service-account --key-file=KEY-FILE

    將 KEY-FILE 替換為服務帳戶金鑰檔案的路徑。

使用服務帳戶金鑰驗證

如需使用者名稱和密碼驗證，請採用這種方法。

服務帳戶金鑰是長效憑證。請遵循下列規範，限制存放區的存取權：

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

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

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

    您需要服務帳戶金鑰檔案的位置，才能設定 Artifact Registry 的驗證機制。如要查看現有帳戶的金鑰，或建立新的金鑰，請前往「服務帳戶」頁面。

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

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

  3. 執行下列指令，顯示存放區設定，以便新增至 Python 專案。

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    替換下列值：

    • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
    • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令中省略這個旗標時，系統就會使用該存放區。
    • LOCATION 是存放區的位置 (單一區域或多區域)。
    • KEY-FILE 是服務帳戶 JSON 金鑰檔案的路徑。

  4. 在 .pypirc 檔案中新增下列設定。每位使用者的 pip 設定檔預設位置如下：

    • Linux 和 macOS：$HOME/.pypirc
    • Windows：%USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY

    替換下列值：

    • PYTHON-REPO-ID 是存放區的 ID，可透過 Twine 等工具參照。
    • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
    • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令中省略這個旗標時，系統就會使用該存放區。
    • LOCATION 是存放區的位置 (單一區域或多區域)。
    • KEY 是服務帳戶金鑰檔案中以 Base64 編碼的金鑰。

  5. 將存放區新增至 pip 設定檔。pip 設定檔位置取決於您要更新的是每位使用者檔案，還是特定虛擬環境的檔案。

    針對與作業系統使用者相關聯的檔案：

    • Unix：$HOME/.config/pip/pip.conf 或 $HOME/.pip/pip.conf
    • macOS：/Library/Application Support/pip/pip.conf 或 $HOME/.config/pip/pip.conf
    • Windows：%APPDATA%\pip\pip.ini 或 %USERPROFILE%\pip\pip.ini

    虛擬環境：

    • Unix 和 macOS：$VIRTUAL_ENV/pip.conf
    • Windows：%VIRTUAL_ENV%\pip.ini

    在 pip 設定檔中新增下列行：

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY 服務帳戶金鑰檔案中的私密金鑰。
    • 存放區路徑結尾的 /simple/ 字串表示存放區實作 Python 簡易存放區 API。

後續步驟