排解 PyPI 套件安裝問題

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本頁說明如何排解安裝自訂 PyPI 套件時的依附元件衝突問題。

您在 Cloud Composer 中使用 PyPI 套件時，最常遇到的問題是依附元件衝突。

指定要安裝新的自訂 PyPI 套件時，這個套件或其版本可能會與環境中的其他自訂 PyPI 套件或預先安裝的套件發生依附元件衝突。在這種情況下，環境更新作業會失敗並顯示錯誤。

Cloud Build 和叢內建構錯誤

如果套件發生問題，您會透過兩種方式收到相關錯誤訊息，具體取決於環境的部署方式：

  • Cloud Build。錯誤訊息和 Cloud Build 記錄的連結。例如：

    UPDATE operation on this environment failed 25 minutes ago with the
following error message:
Failed to install PyPI packages.  Check the Cloud Build log at ...

  • 叢集內建構。錯誤訊息和建構記錄的位置。例如：

    UPDATE operation on this environment failed 17 minutes ago with the
following error message:
Failed to install PyPI packages.  Check the in-cluster build logs for
details. They can be found in the Environment logs under the build-log-*
log name.

查看詳細錯誤訊息

如果套件安裝失敗，pip 會回報詳細錯誤訊息。 您可以在建構記錄中找到這則錯誤訊息。

在 Cloud Build 記錄檔中找出 pip 錯誤

您可以點選 Cloud Build 錯誤訊息中的連結，或找出建構記錄：

  1. 找出建構作業記錄：

    1. 前往 Google Cloud 控制台的「建構記錄」頁面。

      前往「Build history」(建構記錄)

    2. 選取失敗的建構作業，即可查看記錄。

  2. 在建構記錄中，找出 pip 的錯誤訊息。例如：

    ERROR: apache-airflow-backport-providers-google 2021.2.5 has requirement
google-cloud-logging<3.0.0,>=2.1.1, but you'll have google-cloud-logging
1.15.0 which is incompatible.

在叢集內建構記錄中找出 pip 錯誤

  1. 找出建構作業記錄：

    1. 前往 Google Cloud 控制台的「Environments」頁面。

      前往「環境」

    2. 選取環境。

    3. 開啟「記錄」分頁。

    4. 依序選取「所有記錄」>「Composer 記錄」>「版本」> 「Worker 和 Scheduler 映像檔」。

    5. 在「嚴重性」下拉式清單中，選取「資訊」。

  2. 在顯示的記錄中：

    1. 找出 installer.sh 錯誤訊息。例如：

      The command '/bin/sh -c bash installer.sh $COMPOSER_PYTHON_VERSION
fail' returned a non-zero code: 1

    2. 先前的資訊訊息會顯示詳細的 pip 錯誤。例如：

      apache-airflow-backport-providers-google 2021.2.5 has requirement
google-cloud-logging<3.0.0,>=2.1.1, but you have
google-cloud-logging 1.15.0.

Python 套件安裝期間發生逾時

在近期的版本中，pip 公用程式嘗試滿足依附元件時，行為有所改變。如果無法滿足指定的依附元件，pip 會檢查套件的所有可用版本。

安裝套件時，會發生下列情況：

  1. 如果環境中已預先安裝套件，且您指定的 Python 依附元件不需要任何變更，套件就會維持原狀。

    範例：已安裝 aiodebug==2.3.0，且您指定 aiodebug 或 aiodebug>=2。

  2. 如果套件尚未安裝在環境中，或不符合您指定的 Python 依附元件，pip 會嘗試使用符合依附元件的最新版本。如果未指定版本，系統會使用最新版本的套件；如果指定限制，系統會使用符合限制的最新版本套件。

    範例：如果您指定 aiodebug，系統會安裝最新版本 (2.*.*)。如果您指定 aiodebug<2，系統會安裝 1.*.*。

    如果這個版本與預先安裝的套件發生依附元件衝突，pip 會檢查所有可用版本的套件，嘗試滿足指定的依附元件。發生這種情況時，您會在建構記錄中看到下列訊息：

    INFO: pip is looking at multiple versions of PYTHON_PACKAGE_NAME
to determine which version is compatible with other requirements.
This could take a while.

    變更前，pip 會因依附元件衝突而失敗，且不會檢查其他版本。

瀏覽所有可用版本可能需要相當長的時間，而且可能會導致套件降級，或在安裝 Python 套件時發生逾時。

基於安全考量，Cloud Composer 中預先安裝的套件會定期更新至最新版本。因此，將環境升級至較新版本的 Cloud Composer 時，也可能會發生逾時問題。

可能的解決方法：

  • 定期更新自訂 Python 依附元件。

  • 使用 PythonVirtualenvOperator 隔離需要衝突套件的程式碼片段。

與預先安裝的 PyPI 套件發生衝突

您安裝的自訂 PyPI 套件與預先安裝的套件之間，可能會發生套件衝突。

如要查看 Cloud Composer 版本預先安裝的完整套件清單，請前往「Cloud Composer 版本」頁面。

如要解決這個問題，可以採取下列行動：

安裝 PyPI 套件時，中繼資料伺服器無法使用

如果環境使用自訂 pip.conf 檔案，當環境無法安裝任何新的 PyPI 套件時，您可能會遇到問題。在與套件安裝錯誤相關的 Cloud Build 記錄中，您會看到下列警告訊息：

WARNING: Compute Engine Metadata server unavailable on attempt 3 of 3. Reason:
timed out
WARNING: Authentication failed using Compute Engine authentication due to
unavailable metadata server.

這個問題是由 pip.conf 檔案所致，該檔案不允許存取 https://pypi.org/simple 的預設套件索引。舉例來說，如果您的 pip.conf 檔案只允許從自訂 Artifact Registry 存放區安裝套件 (因為重新定義了 index-url 參數)，就無法從預設套件索引安裝套件。

如要解決這個問題，請確認 https://pypi.org/simple 套件索引已新增至 pip.conf 檔案。舉例來說，如果主要套件索引是在 index-url 參數中定義，請在 extra-index-url 參數中新增 https://pypi.org/simple 索引。

後續步驟