安裝 Python 依附元件

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本頁面說明如何為 Cloud Composer 環境安裝 Python 套件。

Cloud Composer 中的套件簡介

本節說明 PyPI 套件在 Cloud Composer 中的運作方式。

Cloud Composer 映像檔中預先安裝和自訂的 PyPI 套件

Cloud Composer 映像檔包含預先安裝和自訂的 PyPI 套件。

• 預先安裝的 PyPI 套件是指環境的 Cloud Composer 映像檔中包含的套件。每個 Cloud Composer 映像檔都包含適用於特定 Cloud Composer 和 Airflow 版本的 PyPI 套件。

• 自訂 PyPI 套件是指您可以在環境中安裝的套件，預先安裝的套件除外。

注意： 如果您打算升級環境，可以進行升級檢查。這項檢查會回報環境中的自訂 PyPI 套件，是否與後續 Airflow 建構版本中預先安裝的套件有任何衝突。

管理 Cloud Composer 環境的 PyPI 套件的選項

選項	適用情況
從 PyPI 安裝	在環境中安裝套件的預設方式
從具有公開 IP 位址的存放區安裝	套件託管在 PyPI 以外的套件存放區。 這個存放區有公開 IP 位址
從 Artifact Registry 存放區安裝	套件託管在 Artifact Registry 存放區中
從專案網路中的存放區安裝	您的環境無法存取公用網際網路。套件會託管在專案網路的套件存放區中。
以本機 Python 程式庫的形式安裝	PyPI 中找不到該套件，且程式庫沒有任何外部依附元件，例如 dist-packages。
安裝外掛程式	這個套件提供外掛程式專屬功能，例如修改 Airflow 網頁介面。
PythonVirtualenvOperator	您不想為所有 Airflow 工作站安裝套件，或是依附元件與預先安裝的套件相衝突。該套件可在 PyPI 中找到，且沒有任何外部依附元件。
KubernetesPodOperator 和 GKE 運算子	您需要無法透過 pip 安裝的外部依附元件 (例如 dist-packages)，或是您需要位在內部 pip 伺服器的外部依附元件。這個選項需要更多設定和維護作業。只有在其他選項無效時才考慮使用。

事前準備

• 您必須具備可觸發環境更新作業的角色。此外，環境的服務帳戶必須具備角色，且該角色有足夠的權限可執行更新作業。

  重要事項： 在環境中安裝 PyPI 套件時，Airflow 會執行已安裝套件中的 Python 程式碼。請務必安裝來自可信來源的套件。如果使用者擁有 composer.environments.update 權限，就能在環境中安裝套件時，代表環境的服務帳戶執行 Python 程式碼。詳情請參閱存取權控管。

• 如果您的環境受到 VPC Service Controls 範圍保護，您必須先授予其他使用者身分存取服務範圍保護的服務權限，並啟用私人 PyPI 存放區的支援功能，才能安裝 PyPI 依附元件。

• 需求必須遵循 PEP-508 中指定的格式，其中每項需求都要以小寫指定，且包含套件名稱和選用的額外項目和版本指定碼。

• 如果依附元件衝突導致更新失敗，您的環境會繼續以現有依附元件運作。如果作業成功，您就可以在 DAG 中開始使用新安裝的 Python 依附元件。

• PythonVirtualenvOperator 不會使用環境 pip.conf 檔案中的設定。如要使用特定依附元件 (包括從自訂索引安裝)，請在 requirements 參數中以字串清單的形式傳遞需求條件。如要進一步瞭解格式，請參閱 pip 說明文件中的「需求檔案格式」。

查看 PyPI 套件清單

您可以取得環境的套件清單，格式不限。

查看預先安裝的套件

如要查看環境的預先安裝套件清單，請參閱環境的 Cloud Composer 映像檔套件清單。

查看所有套件

如要查看環境中的所有套件 (包括預先安裝和自訂套件)：

gcloud

下列 gcloud CLI 指令會傳回環境中 Airflow 工作人員的 python -m pip list 指令結果。您可以使用 --tree 引數取得 python -m pipdeptree --warn 指令的結果。

gcloud beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

取代：

• 將 ENVIRONMENT_NAME 替換為環境的名稱。
• LOCATION 改成環境所在的地區。

查看自訂 PyPI 套件

主控台

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

   前往「環境」

2. 在環境清單中，按一下環境名稱。 「環境詳細資料」頁面隨即開啟。

3. 前往「PyPI Packages」(PyPI 套件) 分頁。

gcloud

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

取代：

• 將 ENVIRONMENT_NAME 替換為環境的名稱。
• LOCATION 改成環境所在的地區。

在 Cloud Composer 環境中安裝自訂套件

本節說明在環境中安裝自訂套件的不同方法。

從 PyPI 安裝套件

如果套件沒有外部依附元件，或與預先安裝的套件發生衝突，則可以從 Python Package Index 安裝。

注意： 您可以放寬已安裝自訂 PyPI 套件的版本限制。舉例來說，請指定 >=1.0.1，而不是 ==1.0.1。

如何為環境新增、更新或刪除 Python 依附元件：

主控台

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

   前往「環境」

2. 在環境清單中，按一下環境名稱。 「環境詳細資料」頁面隨即開啟。

3. 前往「PyPI packages」(PyPI 套件) 分頁。

4. 按一下 [編輯]

5. 按一下「新增套件」。

6. 在「PyPI packages」(PyPI 套件) 部分，指定套件名稱，並可選擇加入版本指定碼和額外項目。

   例如：

   • scikit-learn
   • scipy、>=0.13.3
   • nltk、[machine_learning]

7. 按一下 [儲存]。

gcloud

gcloud CLI 提供多個引數，可處理自訂 PyPI 套件：

• --update-pypi-packages-from-file 會將所有現有的自訂 PyPI 套件替換為指定套件。系統會移除您未指定的套件。
• --update-pypi-package 更新或安裝一個套件。
• --remove-pypi-packages 會移除指定套件。
• --clear-pypi-packages 會移除所有套件。

從檔案安裝需求

requirements.txt 檔案中的每個需求指定碼都必須獨立成行。

例如：

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

更新環境，並在 --update-pypi-packages-from-file 引數中指定 requirements.txt 檔案。

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

取代：

• 將 ENVIRONMENT_NAME 替換為環境的名稱。
• LOCATION 改成環境所在的地區。

安裝一個套件

更新環境，並在 --update-pypi-package 引數中指定套件、版本和額外項目。

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

取代：

• 將 ENVIRONMENT_NAME 替換為環境的名稱。
• LOCATION 改成環境所在的地區。
• PACKAGE_NAME 替換為套件名稱。
• EXTRAS_AND_VERSION，並視需要提供版本和額外項目指定碼。如要省略版本和額外項目，請指定空白值。

注意： 視執行環境而定，您可能需要逸出特殊字元，例如 >。為避免發生潛在問題，請將套件名稱和版本放在引號中，例如："scipy>=0.13.0"。

範例：

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package "scipy>=0.13.3"

移除套件

更新環境，並在 --remove-pypi-packages 引數中指定要刪除的套件：

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

取代：

• 將 ENVIRONMENT_NAME 替換為環境的名稱。
• LOCATION 改成環境所在的地區。
• PACKAGE_NAMES，並以半形逗號分隔套件。

範例：

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

API

建構 environments.patch API 要求。

在這個要求中：

1. 在 updateMask 參數中指定遮罩：

   • 使用 config.softwareConfig.pypiPackages 遮罩將所有現有套件替換為指定套件。系統會刪除您未指定的套件。
   • 使用 config.softwareConfig.envVariables.PACKAGE_NAME 新增或更新特定套件。如要新增或更新多個套件，請以半形逗號分隔指定多個遮罩。

2. 在要求內文中，指定版本和額外項目的套件和值：

   {
     "config": {
       "softwareConfig": {
         "pypiPackages": {
           "PACKAGE_NAME": "EXTRAS_AND_VERSION"
         }
       }
     }
   }
   

   取代：

   • PACKAGE_NAME 替換為套件名稱。
   • EXTRAS_AND_VERSION，並視需要提供版本和額外項目指定碼。如要省略版本和額外項目，請指定空白值。
   • 如要新增多個套件，請在 pypiPackages 中新增套件的額外項目。

範例：

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "EXAMPLE_PACKAGE": "",
        "ANOTHER_PACKAGE": ">=1.10.3"
      }
    }
  }
}

Terraform

software_config 區塊中的 pypi_packages 區塊會指定套件。

resource "google_composer_environment" "example" {
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

取代：

• 將 ENVIRONMENT_NAME 替換為環境的名稱。
• LOCATION 改成環境所在的地區。
• PACKAGE_NAME 替換為套件名稱。
• EXTRAS_AND_VERSION，並視需要提供版本和額外項目指定碼。如要省略版本和額外項目，請指定空白值。
• 如要新增多個套件，請在 pypi_packages 中新增套件的額外項目。

範例：

resource "google_composer_environment" "example" {
  name = "example-environment"
  region = "us-central1"

  config {

    software_config {
      pypi_packages = {
          scipy = ">=1.10.3"
          scikit-learn = ""
          nltk = "[machine_learning]"
      }
    }
  }
}

從公開存放區安裝套件

您可以安裝其他存放區中託管的套件，這些存放區具有公開 IP 位址。

套件必須正確設定，預設 pip 工具才能安裝。

注意： Cloud Composer 不支援自訂 pip，也不會解決預設 pip 工具提供的解決機制以外的套件依附元件和衝突。

如要從具有公開位址的套件存放區安裝套件，請按照下列步驟操作：

1. 建立 pip.conf 檔案，並在檔案中加入下列資訊 (如適用)：

   • 存放區網址 (位於 index-url 參數中)
   • 存放區的存取憑證
   • 非預設 pip 安裝選項

   範例：

   [global]
   index-url=https://example.com/
   

2. (選用) 在某些情況下，您可能會想從多個存放區擷取套件，例如公開存放區包含您想安裝的特定套件，而您想從 PyPI 安裝所有其他套件：

   1. 設定 Artifact Registry 虛擬存放區。
   2. 為多個存放區 (包括 PyPI，視需要) 新增設定，並定義 pip 搜尋存放區的順序。
   3. 在 index-url 參數中指定虛擬存放區的網址。

3. 判斷環境值區的 URI。

4. 將 pip.conf 檔案上傳至環境值區的 /config/pip/ 資料夾。

5. 使用其中一種可用方法安裝套件。

從 Artifact Registry 存放區安裝套件

您可以在專案的 Artifact Registry 存放區中儲存套件，並設定環境從中安裝套件。

注意： 如果您使用 VPC Service Controls，則可以在 VPC 模式下建立 Artifact Registry PyPI 存放區。在這種情況下，請按照私人存放區的程序指派權限。

設定角色和權限：

1. 請確認 Cloud Build 服務帳戶具備從 Artifact Registry 存放區讀取的權限。

2. 如果您的環境限制存取專案中的其他服務 (例如使用 VPC Service Controls)：

   1. 將存取 Artifact Registry 存放區的權限指派給環境的服務帳戶，而非 Cloud Build 服務帳戶。

   2. 確認專案中已設定 Artifact Registry 存放區的連線。

如要從 Artifact Registry 存放區安裝自訂 PyPI 套件，請按照下列步驟操作：

1. 建立 pip.conf 檔案，並在檔案中加入下列資訊 (如適用)：

   • Artifact Registry 存放區的網址 (位於 index-url 參數中)
   • 存放區的存取憑證
   • 非預設 pip 安裝選項

   如果是 Artifact Registry 存放區，請在存放區網址後方附加 /simple/：

   [global]
   index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
   

2. (選用) 在某些情況下，您可能想從多個存放區擷取套件，例如當 Artifact Registry 存放區包含您想安裝的特定套件，而您想從 PyPI 安裝所有其他套件時：

   1. 設定 Artifact Registry 虛擬存放區。
   2. 為多個存放區 (包括 PyPI，視需要) 新增設定，並定義 pip 搜尋存放區的順序。
   3. 在 index-url 參數中指定虛擬存放區的網址。

3. 將這個 pip.conf 檔案上傳至環境值區的 /config/pip/ 資料夾。例如：gs://us-central1-example-bucket/config/pip/pip.conf。

4. 使用其中一種可用方法安裝套件。

從私人存放區安裝套件

您可以在專案的網路中代管私人存放區，並設定環境以從中安裝 Python 套件。

設定角色和權限：

1. 如果您從專案網路中的存放區安裝自訂 PyPI 套件，且該存放區沒有公開 IP 位址，請按照下列步驟操作：

   1. 將存取這個存放區的權限指派給環境的服務帳戶。

   2. 請確認專案中已設定這個存放區的連線。

如要從專案網路中代管的私人存放區安裝套件，請按照下列步驟操作：

1. 建立 pip.conf 檔案，並在檔案中加入下列資訊 (如適用)：

   • 專案網路中存放區的 IP 位址
   • 存放區的存取憑證
   • 非預設 pip 安裝選項

   範例：

   [global]
   index-url=https://192.0.2.10/
   

2. (選用) 在某些情況下，您可能想從多個存放區擷取套件，例如私人存放區包含您想安裝的特定套件，而您想從 PyPI 安裝所有其他套件：

   1. 設定 Artifact Registry 虛擬存放區。
   2. 為多個存放區 (包括 PyPI，視需要) 新增設定，並定義 pip 搜尋存放區的順序。
   3. 在 index-url 參數中指定虛擬存放區的網址。

3. (選用) 安裝私人存放區的套件時，可以使用自訂憑證。方法如下：

   1. 上傳憑證檔案至環境值區的 /config/pip/ 資料夾。

      注意： 請勿上傳私密金鑰。請只上傳 PEM 格式的公開憑證套件。確認憑證組合包含正確的根 CA。

   2. 在 pip.conf 中，於 cert 參數中指定憑證檔案名稱。請勿變更 /etc/pip/ 資料夾。

      範例：

      [global]
      cert =/etc/pip/example-certificate.pem
      

4. 將 pip.conf 檔案上傳至環境值區的 /config/pip/ 資料夾。例如：gs://us-central1-example-bucket/config/pip/pip.conf。

5. 使用其中一種可用方法安裝套件。

安裝本機 Python 程式庫

如何安裝內部或本機 Python 程式庫：

1. 將依附元件放在環境值區的 dags/ 資料夾子目錄中。如要從子目錄匯入模組，模組路徑中的每個子目錄都必須包含 __init__.py 套件標記檔案。

   在以下範例中，依附元件為 coin_module.py：

   dags/
     use_local_deps.py  # A DAG file.
     dependencies/
       __init__.py
       coin_module.py
   

2. 從 DAG 定義檔匯入依附元件。

   例如：

from dependencies import coin_module

注意： 如果缺少 __init__.py 檔案，就會發生匯入錯誤。目錄和檔案名稱必須為有效的 Python ID。

使用依附於共用物件程式庫的套件

部分 PyPI 套件依附於系統層級的程式庫。Cloud Composer 不支援系統程式庫，但您可以採取下列做法：

• 使用 KubernetesPodOperator。將運算子映像檔設為自訂建構映像檔。如果安裝套件時因系統依附元件不符而失敗，請使用這個選項。

• 將共用物件程式庫上傳至環境的 bucket。如果 PyPI 套件已成功安裝，但執行階段失敗，請使用這個選項。

  1. 手動找出 PyPI 依附元件的共用物件程式庫 (.so 檔案)。
  2. 將共用物件程式庫上傳至環境 bucket 中的 /plugins 資料夾。
  3. 設定下列環境變數： LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

注意： plugins/ 資料夾中的檔案會同步至本機檔案系統。上傳大型 .so 檔案可能會影響環境和 Airflow 網路伺服器的效能。

在私人 IP 環境中安裝套件

視專案的設定方式而定，您的環境可能無法存取公共網路。

根據預設，Cloud Composer 3 環境在安裝 PyPI 套件時可以存取網際網路。這項功能適用於所有環境的網路類型 (私人和公開 IP)。舉例來說，您可以在私人 IP 環境中安裝 Python Package Index 的套件。

詳情請參閱「安裝 PyPI 套件時設定網際網路存取權」。

可存取公用網際網路的私人 IP 環境

如果私人 IP 環境可以存取公開網際網路，您可以使用公開 IP 環境的選項安裝套件：

• 從 PyPI 安裝。在這種情況下，不需要進行特殊設定。 按照「從 PyPI 安裝套件」一文所述的程序操作。
• 從具有公開 IP 位址的存放區安裝。 按照「從私人存放區安裝套件」一文所述的程序操作。
• 從專案網路中代管的私人 PyPI 存放區安裝。

無法存取網際網路的私人 IP 環境

如果您的私人 IP 環境無法存取公用網際網路，可以透過下列任一方式安裝套件：

• 使用專案網路中代管的私人 PyPI 存放區。
• 在專案的網路中使用Proxy 伺服器 VM，連線至公開網際網路上的 PyPI 存放區。在環境值區的 /config/pip/pip.conf 檔案中指定 Proxy 位址。
• 使用 Artifact Registry 存放區做為套件的唯一來源。如要執行此操作，請重新定義 index-url 參數，如說明所示。
• 如果安全政策允許從 VPC 網路存取外部 IP 位址，您可以設定 Cloud NAT，啟用從公開網際網路上的存放區安裝套件的功能。
• 將 Python 依附元件放入環境的 bucket 中的 /dags 資料夾，將其安裝為本機程式庫。如果依附元件樹狀結構很大，這可能不是好方法。

在資源位置限制下安裝至私人 IP 環境

如果專案符合資源位置限制規定，就無法使用部分工具。具體來說，Cloud Build 無法用於安裝套件，因此無法直接存取公開網際網路上的存放區。

如要在這類環境中安裝 Python 依附元件，請按照無法存取網際網路的私人 IP 環境指南操作。

在 VPC Service Controls 範圍的私人 IP 環境中安裝 Python 依附元件

使用 VPC Service Controls 範圍保護專案會導致更多安全限制。具體來說，Cloud Build 無法用於安裝套件，因此無法直接存取公開網際網路上的存放區。

如要在邊界內的私人 IP 環境安裝 Python 依附元件，請按照沒有網際網路存取權的私人 IP 環境指南操作。

後續步驟

• 排解套件安裝問題
• 排解更新和升級問題