为 Cloud Composer 安装 Python 依赖项

Cloud Composer 1 | Cloud Composer 2

本页面介绍如何为 Cloud Composer 环境安装 Python 软件包。

关于 Cloud Composer 映像中的预安装 PyPI 软件包和自定义 PyPI 软件包

Cloud Composer 映像包含预安装和自定义 PyPI 软件包。

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

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

用于管理 Cloud Composer 环境的 PyPI 软件包的选项

选项 适用情况
从 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 依赖项。

查看 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 控制台中,转到环境页面。

    转到“环境”

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

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

gcloud

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

您需要将其中的:

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

在 Cloud Composer 环境中安装自定义软件包

本部分介绍了在环境中安装自定义软件包的不同方法。

从 PyPI 安装软件包

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

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

控制台

  1. 在 Google Cloud 控制台中,转到环境页面。

    转到“环境”

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

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

  4. 点击修改

  5. 点击添加软件包

  6. PyPI 软件包部分,指定软件包名称以及可选的版本说明符和 extra。

    例如:

    • 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 参数中指定软件包、版本和 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. 确定环境存储桶的 URI

  3. 将 pip.conf 文件上传到环境存储桶中的 /config/pip/ 文件夹。

  4. 使用可用的方法之一安装软件包。

从 Artifact Registry 代码库安装软件包

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

配置角色和权限:

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

  2. 请确保 Cloud Build 服务帐号具有从 Artifact Registry 代码库读取数据的权限

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

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

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

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

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

    • Artifact Registry 代码库的网址
    • 代码库的访问凭据
    • 非默认 pip 安装选项
    • 如果您只想将 Artifact Registry 代码库用作软件包来源,请重新定义 index-url 参数。否则,除了默认的 PyPI 软件包索引 (pypi.python.org),还会使用您在 extra-index-url 参数中指定的代码库。

    对于 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。将 Operator 映像设置为自定义 build 映像。如果在安装期间由于未满足系统依赖项而遇到软件包安装失败,请使用此选项。

  • 将共享对象库上传到环境的存储桶。如果您的 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 文件中指定代理地址。
  • 使用 Artifact Registry 代码库作为唯一的软件包来源。为此,请按照说明重新定义 index-url 参数。
  • 如果您的安全政策允许从 VPC 网络访问外部 IP 地址,则可以通过配置 Cloud NAT 来允许从公共互联网上的代码库安装软件包。
  • 将 Python 依赖项放入环境存储桶的 /dags 文件夹中,以便将它们作为本地库安装。如果依赖项树很大,这可能不是个好选择。

安装到受资源位置限制的专用 IP 环境

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

如需在此类环境中安装 Python 依赖项,请遵循无法访问互联网的专用 IP 环境的相关指南。

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

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

如需为边界内的专用 IP 环境安装 Python 依赖项,请遵循无法访问互联网的专用 IP 环境的指南。

后续步骤