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

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

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

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

事前準備

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

  4. 安裝 Google Cloud CLI。 安裝完成後，執行下列指令初始化 Google Cloud CLI： 

    gcloud init

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

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

總覽

Artifact Registry 支援下列驗證方法。

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

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

使用 Keyring 進行驗證

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. 安裝 keyring 程式庫。

    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 等工具參照該 ID。
    • 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 Simple Repository API。

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

使用使用者憑證進行金鑰圈驗證

設定金鑰環後，您可以在 gcloud CLI 中搭配使用者憑證使用金鑰環。連線至 Python 套件存放區前，請先登入 Google Cloud CLI。

執行下列指令：

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 會先尋找 VM 服務帳戶憑證，再尋找 gcloud CLI 中的憑證。

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

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

使用服務帳戶金鑰驗證

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

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

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

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

  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 等工具參照該 ID。
    • 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 Simple Repository API。

後續步驟