安装 Python 依赖项

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Cloud Composer 1 | Cloud Composer 2

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

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

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

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

管理 Python 软件包的选项

选项 使用条件
从 PyPI 安装 在您的环境中安装软件包的默认方式
从具有公共 IP 地址的代码库中安装 该软件包托管在 PyPI 以外的软件包代码库中。此代码库具有公共 IP 地址
从 Artifact Registry 代码库安装 软件包托管在 Artifact Registry 代码库中
从项目网络中的代码库进行安装 您的环境无权访问公共互联网。该软件包托管在项目网络的软件包代码库中。
作为本地 Python 库安装 在 PyPI 中找不到软件包,并且该库没有任何外部依赖项,例如 dist-packages
安装插件 软件包提供了插件专用功能,例如修改 Airflow 网页界面。
PythonVirtualenvOperator 您不希望为所有 Airflow 工作器安装软件包,或者依赖项与预安装的软件包冲突。该软件包可在 PyPI 中找到,并且没有外部依赖项。
KubernetesPodOperatorGKE 运算符 您需要无法从 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
    • scipy>=0.13.3
    • nltk[machine_learning]

gcloud

gcloud CLI 有几项功能,可用于自定义 PyPI 软件包:

  • --update-pypi-packages-from-file 会将所有现有的自定义 PyPI 软件包替换为指定的软件包。系统会移除您未指定的软件包。
  • --update-pypi-package 会更新或安装 1 个软件包。
  • --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 代码块中的 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 替换为可选的版本和 extra 说明符。如需省略版本和 extra,请指定空值。
  • 如需添加多个软件包,请将软件包的额外条目添加到 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 工具可以安装。

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

  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

  3. 使用某一可用方法安装软件包。

从 Artifact Registry 代码库安装

您可以将软件包存储在项目中的 Artifact Registry 代码库中,并配置环境以从软件包进行安装。

配置角色和权限:

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

  2. 确保 Cloud Build 服务帐号具有从 Artifact Registry 代码库中读取内容的权限

  3. 如果您的环境限制了对您项目中的其他服务的访问权限,例如,如果您使用的是 VPC Service Controls:

    1. 向环境的服务帐号(而不是 Cloud Build 服务帐号)分配访问 Artifact Registry 代码库的权限。

    2. 确保在项目中配置了与 Artifact Registry 代码库的连接。

如需从 Artifact Registry 代码库安装自定义 PyPI 软件包,请执行以下操作:

  1. 创建一个 pip.conf 文件,并在该文件中添加以下信息(如果适用):

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

    对于 Artifact Registry 代码库,请将 /simple/ 附加到代码库网址:

    [global]
    extra-index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
    
  2. 将此 pip.conf 文件上传到您环境的存储桶中的 /config/pip/ 文件夹。例如:gs://us-central1-example-bucket/config/pip/pip.conf

  3. 使用某一可用方法安装软件包。

从私有代码库安装

您可以在项目的网络中托管私有代码库,并将环境配置为从其中安装 Python 软件包。

配置角色和权限:

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

  2. 如果您从项目网络中的代码库安装自定义 PyPI 软件包,并且此代码库没有公共 IP 地址,请执行以下操作:

    1. 向环境的服务帐号分配访问此代码库的权限。

    2. 请确保在项目中配置了与此代码库的连接。

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

  1. 创建一个 pip.conf 文件,并在该文件中添加以下信息(如果适用):

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

    示例:

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

  3. 使用某一可用方法安装软件包。

安装本地 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

在专用 IP 环境中安装软件包

本部分介绍如何在专用 IP 环境中安装软件包。

您的环境可能无法访问公共互联网,具体取决于您配置项目的方式。

具有公共互联网访问权限的专用 IP 环境

如果您的专用 IP 环境可以访问公共互联网,那么您可以使用适用于公共 IP 环境的选项安装软件包:

未连接到互联网的专用 IP 环境

如果您的专用 IP 环境无法访问公共互联网,那么您可以通过以下某种方式安装软件包:

  • 使用托管在项目网络中的专用 PyPI 代码库
  • 使用您项目的网络中的代理服务器虚拟机连接到公共互联网上的 PyPI 代码库。在您环境的存储桶的 /config/pip/pip.conf 文件中指定代理地址。
  • 如果您的安全政策允许从外部 IP 地址访问项目的网络,您可以通过配置 Cloud NAT 来允许安装软件包。
  • 将 Python 依赖项放入环境的存储桶中的 /dags 文件夹,以将其安装为本地库。如果依赖项树很大,那么这样做可能不太合适。

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

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

如需在此类环境中安装 Python 依赖项,请按照未连接到互联网的专用 IP 环境的相关指南操作。

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

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

如需为边界内的专用 IP 环境安装 Python 依赖项,请按照没有互联网访问权限的专用 IP 环境指南操作。

后续步骤