安装 Cloud Composer 的 Python 依赖项

Cloud Composer 1 | Cloud Composer 2

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

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

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

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

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

注意 ：如果您打算升级到更高的 Cloud Composer 版本，可以执行升级检查。此检查会报告您环境中的自定义 PyPI 软件包是否与新的 Cloud Composer 映像中的预安装软件包发生任何冲突。

用于管理 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 服务器上。此选项需要更多设置和维护工作。仅当其他选项都不起作用时，才考虑使用这种方法。

准备工作

• 您必须具有可以触发环境更新操作的角色。此外，环境的服务账号必须具有拥有足够权限来执行更新操作的角色。如需了解详情，请参阅访问权限控制。
• 如果您的环境受 VPC Service Controls 边界保护，则在安装 PyPI 依赖项之前，您必须向其他用户身份授予对服务边界保护的服务的访问权限，并启用对专用 PyPI 代码库的支持。
• 要求必须遵循 PEP-508 中指定的格式：每项要求均以小写形式指定，并且包含软件包名称（您还可以选择添加 extras 和版本说明符）。

• PyPI 依赖项更新会在 Artifact Registry 中生成 Docker 映像。

  警告 ：请勿修改或删除由 Cloud Composer 在 Artifact Registry 中构建的映像或代码库本身。请勿将您自己的图片上传到代码库中。请改为为映像创建和维护自己的代码库（例如，KubernetesPodOperator 使用的映像）。请勿自行删除此代码库。在您删除环境后，该代码库会被删除。

• 如果更新因某个依赖项冲突而失败，那么您的环境将继续使用其现有依赖项运行。如果操作成功，您可以开始在 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 软件包索引安装该软件包。

注意 ：您可以放宽针对已安装的自定义 PyPI 软件包的版本限制。例如，不要将版本指定为 ==1.0.1，而应将其指定为 >=1.0.1。

如需为您的环境添加、更新或删除 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 更新或安装 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 替换为软件包的名称。
• 带有可选版本和 extra 说明符的 EXTRAS_AND_VERSION。如需省略版本和 extra，请指定空值。

注意 ：根据执行环境，您可能需要对 > 等特殊字符进行转义。为避免潜在问题，请将软件包名称和版本括在引号中，例如："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. 在请求正文中，为版本和 extra 指定软件包和值：

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

   您需要在其中：

   • 将 PACKAGE_NAME 替换为软件包的名称。
   • 带有可选版本和 extra 说明符的 EXTRAS_AND_VERSION。如需省略版本和 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 替换为软件包的名称。
• 带有可选版本和 extra 说明符的 EXTRAS_AND_VERSION。如需省略版本和 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 工具可以安装它。

注意 ：Cloud Composer 不支持 pip 自定义，并且无法在默认 pip 工具提供的解析机制之外解决软件包依赖项和冲突。

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

1. 创建一个 pip.conf 文件，并在该文件中添加以下信息（如果适用）：

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

   示例：

   [global]
   index-url=https://example.com/
   

   如果要从多个代码库中提取软件包，请使用 Artifact Registry 虚拟代码库来控制 pip 搜索代码库的顺序。

2. 确定环境存储桶的 URI。

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

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

从 Artifact Registry 代码库安装软件包

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

注意 ：如果您使用 VPC Service Controls，则可以在 VPC 模式下创建 Artifact Registry PyPI 代码库。在这种情况下，请按照私有代码库的流程分配权限。

配置角色和权限：

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

注意 ：如果缺少 __init__.py 文件，则会发生导入错误。目录和文件名必须是有效的 Python 标识符。

使用依赖于共享对象库的软件包

某些 PyPI 软件包取决于系统级库。 虽然 Cloud Composer 不支持系统库，但您可以使用以下方法：

• 使用 KubernetesPodOperator。将 Operator 映像设置为自定义 build 映像。如果由于未满足系统依赖项而导致软件包在安装过程中失败，请使用此选项。

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

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

注意 ：plugins/ 文件夹中的文件会同步到本地文件系统。上传大型 .so 文件可能会影响您的环境和 Airflow Web 服务器的性能。

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

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

根据您配置项目的方式，您的环境可能无法访问公共互联网。

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

如果您的专用 IP 环境可以访问公共互联网，则可以使用公共 IP 环境对应的选项来安装软件包：

• 从 PyPI 安装。在这种情况下，无需特殊配置。按照从 PyPI 安装软件包中所述的步骤进行操作。
• 从具有公共 IP 地址的代码库安装。 按照从私有代码库安装软件包中所述的步骤进行操作。
• 从项目网络内托管的专用 PyPI 代码库安装。

无法访问互联网的专用 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 环境的指南。

后续步骤

• 排查软件包安装问题
• 排查更新和升级问题