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

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

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

Artifact Registry 支援下列 Python 套件存放區的驗證方法：

• 存取權杖： 在自動化、CI/CD 管道、容器建構作業或不支援安裝金鑰環程式庫的環境中，使用存取權杖。
• Python 金鑰環程式庫 (建議用於本機開發)： 在開發人員工作站上使用這個選項，自動處理憑證重新整理作業。
• 密碼驗證： 如果應用程式不支援應用程式預設憑證，但支援使用使用者名稱和密碼進行驗證，請使用這個選項。

事前準備

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

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

   gcloud init

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

   注意：如果您已經安裝 gcloud CLI，請務必執行 gcloud components update，確認您安裝的是最新版本。
5. (選用) 設定 gcloud CLI 指令的預設值。

產生驗證權杖

如要在 Artifact Registry 中驗證套件，必須先產生驗證權杖。接著，您就能在從套件向 Artifact Registry 提出要求時使用這個權杖。

您可以使用 oauth2 權杖或 Google Cloud 權杖，在 oauth2l 外部產生存取權杖 Google Cloud。

存取權杖的效期為 60 分鐘。請在執行與存放區互動的指令前不久，產生存取權杖。如果存取權杖已過期，您必須產生新的存取權杖。

使用 gcloud 產生權杖

如要使用 Google Cloud產生 oauth2 存取權杖，請執行下列指令：

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

現在，從 Python 套件向 Artifact Registry 提出要求時，可以參照 ACCESS_TOKEN。

產生權杖 (不使用 gcloud)

如要只使用 oauth2l CLI 產生存取權杖，請執行下列操作：

1. 執行下列指令，安裝最新版 oauth2l：

   go install github.com/google/oauth2l@latest
   

2. 執行下列指令：

   export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"
   

   Google Cloud 會產生 SHA256 雜湊權杖，並儲存在 ACCESS_TOKEN 變數中。現在從 Python 套件向 Artifact Registry 發出要求時，可以參照 ACCESS_TOKEN。

使用 pip 進行驗證

匯出 ACCESS_TOKEN 後，您可以將其傳遞至 pip 來安裝套件：

pip install PACKAGE --index-url https://$[e-mail]/PROJECT/REPOSITORY/simple/

使用金鑰環驗證

Python keyring 程式庫可讓應用程式存取 keyring 後端，也就是作業系統和第三方憑證儲存空間。Artifact Registry 提供 keyrings.google-artifactregistry-auth 金鑰環後端，可處理 Artifact Registry 存放區的驗證作業。

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

憑證搜尋順序

使用 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 等工具參照該 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

注意： Artifact Registry 會依特定順序搜尋憑證。如果系統先找到服務帳戶憑證，就會使用這些憑證，而非使用者憑證。

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

設定金鑰環後，即可設定服務帳戶進行驗證。

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:[e-mail]/PROJECT/REPOSITORY/simple/
   

   • KEY 服務帳戶金鑰檔案中的私密金鑰。
   • 存放區路徑結尾的 /simple/ 字串表示存放區實作了 Python Simple Repository API。

後續步驟

• 設定存放區的存取權
• 瞭解如何管理存放區
• 瞭解如何管理套件