解決 PyPI 套件安裝問題

Managed Airflow (第 3 代) | Managed Airflow (第 2 代) | Managed Airflow (舊版第 1 代)

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

在 Managed Airflow 中,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」(環境) 頁面。

      前往「Environments」(環境)

    2. 選取環境。

    3. 開啟「記錄」分頁。

    4. 依序選取「All logs」(所有記錄) >「Composer logs」(Composer 記錄) >「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 套件安裝期間逾時。

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

可能的解決方案:

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

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

與預先安裝的 PyPI 套件衝突

您安裝的自訂 PyPI 套件和預先安裝的套件之間,可能會發生一些套件衝突。

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

如要解決這個問題,您可以:

安裝 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 存放區安裝套件,則無法從預設套件索引安裝套件。

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

後續步驟