安裝 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 worker 傳回 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 套件」分頁。

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 套件」分頁。

4. 按一下 [編輯]

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

6. 在「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。將 Operator 映像檔設為自訂建構映像檔。如果套件在安裝期間因未滿足系統依附元件而失敗，請使用這個選項。

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

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

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

在私人 IP 環境中安裝套件

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

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

詳情請參閱「安裝 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 依附元件放入環境儲存桶的 /dags 資料夾中，即可將這些元件當作本機程式庫安裝。如果依附元件樹狀圖很大，這可能不是理想的做法。

在資源位置限制下，將應用程式安裝到私人 IP 環境

請注意，如果專案符合「資源位置限制」規定，就無法使用某些工具。特別是，Cloud Build 無法用於套件安裝作業，因此無法直接存取公開網際網路上的存放區。

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

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

使用 VPC Service Controls 範圍保護專案會導致進一步的安全限制。特別是，Cloud Build 無法用於套件安裝作業，因此無法直接存取公開網際網路上的存放區。

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

後續步驟

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