安裝 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 套件。

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

事前準備

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

• 如果您的環境受到 VPC Service Controls 範圍保護，則在安裝 PyPI 依附元件之前，您必須授予額外使用者身分，讓這些使用者能存取服務範圍保護的服務，並啟用私人 PyPI 存放區支援功能。

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

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

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

查看 PyPI 套件清單

您可以透過多種格式取得環境的套件清單。

查看預先安裝的套件

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

查看所有套件

如要查看環境中的所有套件 (預先安裝和自訂套件)，請按照下列步驟操作：

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

查看自訂 PyPI 套件

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

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

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

從 PyPI 安裝套件

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

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

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

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

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

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

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

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

// 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"
      }
    }
  }
}

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

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

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 工具安裝。

如要從含有公開位址的套件存放區安裝：

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 存放區，並設定環境以便從該存放區安裝。

設定角色和權限：

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/ 資料夾。

   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

使用依賴共用物件程式庫的套件

某些 PyPI 套件會依附系統層級程式庫。雖然 Cloud Composer 不支援系統程式庫，但您可以使用下列選項：

• 使用 KubernetesPodOperator。將 Operator 映像檔設為自訂建構映像檔。如果套件在安裝期間因未滿足系統依附元件而失敗，請使用這個選項。

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

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

在私人 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 環境指南操作。

後續步驟

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