安装 Python 依赖项

Cloud Composer 1 | Cloud Composer 2

本页面介绍如何将 Python 软件包安装到您的环境。

关于预安装和自定义 PyPI 软件包

预安装的 PyPI 软件包是环境的 Cloud Composer 映像中包含的软件包。每个 Cloud Composer 映像都包含适用于您的 Cloud Composer 和 Airflow 版本的 PyPI 软件包。

自定义 PyPI 软件包是除了预安装的软件包之外,您还可以在环境中安装的软件包。

管理 Python 软件包的方法

选项 使用条件
从 PyPI 安装 软件包没有外部依赖项,并且不与 Cloud Composer 依赖项冲突。
从私有代码库安装 该软件包托管在互联网上的私有软件包代码库中。
安装为本地 Python 库 在 Python 软件包索引中找不到该软件包,并且该库没有任何外部依赖项,例如 dist-packages
安装插件 该软件包提供特定于插件的功能,例如修改 Airflow 网页界面。
PythonVirtualenvOperator 您不希望为所有工作器安装软件包,否则依赖项与预安装的软件包冲突。该软件包可在 Python Package Index 中找到,并且没有外部依赖项。
KubernetesPodOperator 您需要通过 pip 等外部依赖项(如 dist-packages)进行安装,或者这些外部依赖项位于内部 pip 服务器上。此选项需要更多设置和维护,通常只有在其他选项都不起作用时才应考虑此选项。

准备工作

  • 您必须具有可以触发环境更新操作的角色。此外,环境的服务帐号必须具有拥有足够权限来执行更新操作的角色。如需了解详情,请参阅访问权限控制
  • 如果您的环境受 VPC Service Controls 边界的保护,则在安装 PyPI 依赖项之前,您必须授予更多用户身份,使其可以访问服务边界所保护的服务,并启用对私有 PyPI 代码库的支持。
  • 要求必须遵循 PEP-508 中指定的格式:每项要求均以小写形式指定,并且包含软件包名称(您还可以选择添加 extras 和版本说明符)。
  • PyPI 依赖项更新在 Artifact Registry 中生成 Docker 映像。请勿修改或删除图片。
  • 如果更新因某个依赖项冲突而失败,那么您的环境将继续使用其现有依赖项运行。如果操作成功,您可以开始在 DAG 中使用新安装的 Python 依赖项。

查看软件包列表

您可以获取多种格式的环境软件包列表。

预安装的软件包

如需查看您的环境的预安装软件包列表,请参阅您的环境的 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 Console 中,转到环境页面。

    转到“环境”

  2. 在环境列表中,点击您的环境名称。环境详情页面会打开。

  3. 转到 PYPI 软件包标签页。

gcloud

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

替换:

  • ENVIRONMENT_NAME 替换为环境的名称。
  • LOCATION 替换为环境所在的区域。

从 PyPI 安装软件包

如果软件包没有外部依赖项或与预安装的软件包冲突,则可以从 Python 软件包索引安装。

如需为您的环境添加、更新或删除 Python 依赖项,请按如下所述操作:

控制台

  1. 在 Google Cloud Console 中,转到环境页面。

    转到“环境”

  2. 在环境列表中,点击您的环境名称。环境详情页面会打开。

  3. 转到环境配置标签页。

  4. 点击修改

  5. PyPI 软件包部分,使用可选的说明符和 extra 指定软件包名称。

    例如:

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

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 参数中指定软件包、版本和 extra:

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

替换:

  • ENVIRONMENT_NAME 替换为环境的名称。
  • LOCATION 替换为环境所在的区域。
  • PACKAGE_NAME 替换为软件包的名称。
  • EXTRAS_AND_VERSION 替换为可选版本和 extra 说明符。如需省略版本和 extra,请指定空值。

示例:

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. 在请求正文中,指定版本和 extra 的软件包和值:

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

    替换:

    • PACKAGE_NAME 替换为软件包的名称。
    • EXTRAS_AND_VERSION 替换为可选版本和 extra 说明符。如需省略版本和 extra,请指定空值。
    • 如需添加多个软件包,请向 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 块中的 env_variables 块可用于指定环境变量。

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

  config {

    software_config {

      env_variables = {
        VAR_NAME = "VAR_VALUE"
      }

    }
  }
}

替换:

  • ENVIRONMENT_NAME 替换为环境的名称。
  • LOCATION 替换为环境所在的区域。
  • VAR_NAME 替换为环境变量的名称。
  • VAR_VALUE 替换为环境变量的值。
  • 如需添加多个变量,请在 env_variables 中添加变量的额外条目。

示例:

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

  config {

      env_variables = {
        EXAMPLE_VARIABLE = "True"
        ANOTHER_VARIABLE = "test"
      }

  }
}

从私有代码库安装

您可以安装托管在公共互联网上软件包代码库中的软件包。

软件包必须正确配置,以便默认的 pip 工具可以安装。

如需从具有公开地址的私有软件包代码库进行安装,请执行以下操作:

  1. 如果适用,请创建一个 pip.conf 文件,并在该文件中包含以下信息:

    • 代码库的网址
    • 代码库的访问凭据
    • 非默认 pip 安装选项

    示例:

    [global]
    extra-index-url=https://example.com/
    
  2. 将此 pip.conf 文件上传到您环境的存储分区中的 /config/pip/ 文件夹。例如:gs://us-central1-example-bucket/config/pip/pip.conf

安装到专用 IP 环境

专用 IP 环境限制对公共互联网的访问,因此安装 Python 依赖项可能需要执行其他步骤。

从 PyPI 代码库安装依赖项时,不需要任何特殊配置。按照从 PyPI 安装软件包中所述的步骤进行操作。您还可以从具有公开地址的私有代码库请求软件包。

作为替代方案,您可以在项目的网络中托管专用 PyPI 代码库。安装依赖项时,Cloud Composer 会在托管环境的集群内运行该操作,而无需通过 Cloud Build 访问任何公共 IP 地址。

如需从项目网络中托管的私有代码库安装软件包,请执行以下操作:

  1. 您的 Cloud Composer 环境的服务帐号必须具有 iam.serviceAccountUser 角色。

  2. 如果适用,请创建一个 pip.conf 文件,并在该文件中包含以下信息:

    • 项目网络中代码库的 IP 地址
    • 代码库的访问凭据
    • 非默认 pip 安装选项

    示例:

    [global]
    extra-index-url=https://192.0.2.10/
    
  3. 将此 pip.conf 文件上传到您环境的存储分区中的 /config/pip/ 文件夹。例如:gs://us-central1-example-bucket/config/pip/pip.conf

在资源位置限制下安装到专用 IP 环境

保证项目符合资源位置限制要求,禁止使用某些工具。具体而言,Cloud Build 不能用于安装软件包,以防止直接访问公共互联网上的代码库。

如需在此类环境中安装 Python 依赖项,请按照使用 VPC Service Controls 边界的专用 IP 环境指南操作。

在 VPC Service Controls 边界中将 Python 依赖项安装到专用 IP 环境

使用 VPC Service Controls 边界保护项目将导致进一步的安全限制。具体而言,Cloud Build 不能用于安装软件包,以防止直接访问公共互联网上的代码库。

如需为边界内的专用 IP 环境安装 Python 依赖项,您可以执行以下操作:

  • 使用托管在 VPC 网络中的专用 PyPI 代码库
  • 使用 VPC 网络中的代理服务器虚拟机连接到公共互联网上的 PyPI 代码库。请在环境存储分区的 /config/pip/pip.conf 文件中指定代理地址。
  • 如果您的安全政策允许从外部 IP 地址访问 VPC 网络,则可以通过配置 Cloud NAT 来启用此功能。
  • 将 Python 依赖项放入 Cloud Storage 存储分区的 dags 文件夹中,以将其安装为本地库。如果依赖项树较大,那么这不是一个好的选择。

安装本地 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。将运营商映像设置为自定义构建映像。如果您在安装期间遇到因未满足系统依赖项而失败的软件包,请使用此选项。

  • 将共享对象库上传到您的环境的存储分区。如果您的 PyPI 软件包已成功安装,但在运行时失败,请使用此选项。

    1. 手动查找 PyPI 依赖项的共享对象库(.so 文件)。
    2. 将共享对象库上传到环境存储分区中的 /plugins 文件夹。
    3. 设置以下环境变量LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

后续步骤