解決 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」頁面。

      前往「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. 開啟「Logs」分頁。

    4. 依序選取「All Logs」 >「Composer Logs」 >「Builds」 >「Worker & Scheduler image」。

    5. 在「Severity」下拉式清單中，選取「Info」。

  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 檔案因重新定義的 index-url 參數，而只允許從自訂 Artifact Registry 存放區安裝套件，就無法從預設套件索引安裝套件。

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

後續步驟