为 Cloud Composer 安装 Python 依赖项

Cloud Composer 1 |Cloud Composer 2 |Cloud Composer 3

本页介绍如何为您的 Google Cloud 项目安装 Python 软件包， Cloud Composer 环境。

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

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

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

• 自定义 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） 其中每项要求均以小写形式指定，并包含软件包 名称（带有可选 extra 和版本说明符）。

• PyPI 依赖项更新会在以下位置生成 Docker 映像： Artifact Registry。

  警告： 请勿修改或删除 Cloud Composer 构建的映像 或代码库本身请勿自行上传 代码库您应改为创建和维护自己的代码库， 您的映像（例如，对于 KubernetesPodOperator 使用的映像）。错误做法 删除这个代码库在您删除代码库后，该代码库也会被删除 您的环境。

• 如果更新因某个依赖项冲突而失败，那么您的环境将继续使用其现有依赖项运行。如果操作成功，您可以开始在 DAG 中使用新安装的 Python 依赖项。

• 符合以下条件的项目： Cloud Composer API 于 2024 年 4 月 29 日或之后启用。 除非您的组织覆盖 constraints/cloudbuild.disableCreateDefaultServiceAccount 政策, 新项目, policy, new projects 不会预配旧版 Cloud Build 服务账号 到这里就结束了由于系统默认使用 Cloud Build 在 Cloud Composer 中安装自定义 PyPI 软件包 环境中，软件包安装可能会失败。默认情况下， 环境的服务账号。 请务必授予您访问您所需的任何其他权限 私有软件包也发布到该服务账号如果您希望自己的构建 以便使用其他账号运行，则可以覆盖 COMPOSER_AGENT_BUILD_SERVICE_ACCOUNT 环境变量 与所选服务账号相关联您应配置此服务账号 （请参阅 Cloud Build 文档）， 和环境的服务账号应具有 iam.serviceAccounts.actAs 权限。

查看 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 环境中安装自定义软件包

本部分介绍了在 Google Cloud 控制台中安装自定义软件包的不同方法， 环境

从 PyPI 安装软件包

软件包可从 Python Package Index（如果没有外部文件） 依赖项或与预安装的软件包冲突。

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

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

控制台

1. 在 Google Cloud 控制台中，前往环境页面。

   转到“环境”

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

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

4. 点击修改

5. 点击添加软件包。

6. 在 PyPI 软件包部分中，指定软件包名称（可选） 版本说明符和附加信息。

   例如：

   • 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]

更新您的环境，并在以下位置指定 requirements.txt 文件： --update-pypi-packages-from-file 参数。

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

您需要将其中的：

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

安装一个软件包

请更新您的环境，并在以下位置指定软件包、版本和 extra： --update-pypi-package 参数。

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

您需要将其中的：

• ENVIRONMENT_NAME 替换为环境的名称。
• LOCATION 替换为环境所在的区域。
• 将 PACKAGE_NAME 替换为软件包的名称。
• 将 EXTRAS_AND_VERSION 替换为可选的 version 和 extras 说明符。接收者 省略版本和 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 替换为软件包的名称。
   • 将 EXTRAS_AND_VERSION 替换为可选的 version 和 extras 说明符。接收者 省略版本和 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" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

您需要将其中的：

• ENVIRONMENT_NAME 替换为环境的名称。
• LOCATION 替换为环境所在的区域。
• 将 PACKAGE_NAME 替换为软件包的名称。
• 将 EXTRAS_AND_VERSION 替换为可选的 version 和 extras 说明符。接收者 省略版本和 extra，则指定空值。
• 如需添加多个软件包，请为软件包添加额外的条目 发送至 pypi_packages。

示例：

resource "google_composer_environment" "example" {
  provider = google-beta
  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 文件，并在该文件中包含以下信息（如果适用）：

   • 代码库的网址（在 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 代码库中 并将您的环境配置为从该环境进行安装。

注意 ：如果您使用 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 代码库的网址（在 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. Cloud Composer 环境的服务账号必须 具有 iam.serviceAccountUser 角色。

2. 如果您从项目 并且此代码库没有公共 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. （可选）在 Cloud Composer 2.2.1 版及更高版本中，您可以 从私有发行版安装软件包时，请使用自定义证书 存储库为此，请执行以下操作：

   1. 将证书文件上传到 /config/pip/ 文件夹。

      注意 ：请勿上传私钥。仅上传一个公开视频 PEM 格式的证书文件包。验证证书 软件包中包含正确的根 CA。

   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

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

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

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

• 使用 KubernetesPodOperator。将运营商映像设置为自定义 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 地址的代码库安装。 请按照 从私有代码库安装软件包。
• 从 Google Cloud 控制台中托管的私有 PyPI 代码库中安装 项目的网络。

无法访问互联网的专用 IP 环境

如果您的专用 IP 环境无法访问公共互联网， 您可以通过以下方式之一安装软件包：

• 使用托管在您项目的 。
• 使用您项目网络中的代理服务器虚拟机进行连接 发布到公共互联网上的 PyPI 代码库。在以下位置指定代理地址： 您的环境存储桶中的 /config/pip/pip.conf 文件。
• 使用 Artifact Registry 代码库作为唯一来源 多个软件包为此，请按照说明重新定义 index-url 参数。
• 如果您的安全政策允许从您的 VPC 网络，您可以允许从代码库安装软件包 在公共互联网上配置 Cloud NAT。
• 将 Python 依赖项放入环境存储桶的 /dags 文件夹中 将其安装为本地库。这可能不是 如果依赖关系树很大，那么这是个不错的选择。

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

保证项目符合资源位置限制要求，禁止使用某些工具。具体而言，Cloud Build 无法用于软件包安装，会阻止直接访问 存储代码库

要在此类环境中安装 Python 依赖项，请遵循 专用 IP 环境 无法连接互联网的情况。

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

使用 VPC Service Controls 边界 会导致进一步的安全限制。具体而言，Cloud Build 无法用于软件包安装，会阻止直接访问 存储代码库

要为边界内的专用 IP 环境安装 Python 依赖项，请执行以下操作： 遵循适用于专用 IP 环境的指南 无法连接互联网的情况。

后续步骤

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