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 映像都包含特定于您所用 Cloud Composer 和 Airflow 版本的 PyPI 软件包。
自定义 PyPI 软件包是除了预安装软件包之外您可以在环境中安装的软件包。
用于管理 Cloud Composer 环境的 PyPI 软件包的选项
选项 | 使用条件 |
---|---|
从 PyPI 安装 | 在您的环境中安装软件包的默认方式 |
从具有公共 IP 地址的代码库安装 | 软件包托管在 PyPI 以外的软件包代码库中。 此代码库具有公共 IP 地址 |
从 Artifact Registry 制品库安装 | 软件包托管在 Artifact Registry 制品库中 |
从项目网络中的代码库安装 | 您的环境无法访问公共互联网。软件包 托管在您项目网络的软件包代码库中。 |
作为本地 Python 库进行安装 |
在 PyPI 中找不到该软件包,并且该库
没有任何外部依赖项,例如 dist-packages 。 |
安装插件 | 该软件包提供插件特有的功能,例如修改 Airflow 网页界面。 |
PythonVirtualenvOperator | 您不希望为所有 Airflow 工作器安装该软件包,或者 该依赖项与预安装的软件包冲突。软件包 可以在 PyPI 中找到,并且没有外部依赖项。 |
KubernetesPodOperator 和 GKE Operator |
您需要无法通过 pip 安装的外部依赖项,
例如 dist-packages 或位于内部 pip 服务器上。这个
需要进行更多的设置和维护。仅当其他选项不起作用时,才考虑使用此方法。 |
准备工作
- 您必须具有可以触发环境更新操作的角色。此外,环境的服务账号必须具有拥有足够权限来执行更新操作的角色。如需了解详情,请参阅访问权限控制。
- 如果您的环境受 VPC Service Controls 边界的保护,则在安装 PyPI 依赖项之前,您必须为其他用户身份授予访问权限,使其能够访问服务边界所保护的服务,并启用对私有 PyPI 代码库的支持。
- 要求必须遵循指定的格式 (位于 PEP-508) 其中每项要求均以小写形式指定,并包含软件包 名称(带有可选 extra 和版本说明符)。
PyPI 依赖项更新会在以下位置生成 Docker 映像: Artifact Registry。
如果更新因某个依赖项冲突而失败,那么您的环境将继续使用其现有依赖项运行。如果操作成功,您可以开始在 DAG 中使用新安装的 Python 依赖项。
如果您希望自己的构建 以通过自定义服务账号运行,您可以替换
COMPOSER_AGENT_BUILD_SERVICE_ACCOUNT
环境变量 与所选服务账号相关联您应配置此服务账号 (请参阅 Cloud Build 文档), 和环境的服务账号应具有iam.serviceAccounts.actAs
权限。在 2024 年 4 月 29 日或之后启用了 Cloud Composer API 的项目。除非您的组织替换了
constraints/cloudbuild.disableCreateDefaultServiceAccount
政策,否则新项目在启用该 API 后不会预配旧版 Cloud Build 服务账号。由于在 Cloud Composer 环境中安装自定义 PyPI 软件包时默认使用 Cloud Build,因此软件包安装可能会失败。默认情况下,系统会改用环境的服务账号,因此请务必向该服务账号授予访问您的私有软件包所需的所有其他权限。
查看 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 软件包
控制台
在 Google Cloud 控制台中,前往环境页面。
在环境列表中,点击您的环境名称。环境详情页面会打开。
前往 PyPI 软件包标签页。
gcloud
gcloud composer environments describe ENVIRONMENT_NAME \
--location LOCATION \
--format="value(config.softwareConfig.pypiPackages)"
替换:
ENVIRONMENT_NAME
替换为环境的名称。LOCATION
替换为环境所在的区域。
在 Cloud Composer 环境中安装自定义软件包
本部分介绍了在环境中安装自定义软件包的不同方法。
从 PyPI 安装软件包
如果软件包没有外部依赖项或与预安装的软件包冲突,则可以从 Python Package Index 安装。
如需为您的环境添加、更新或删除 Python 依赖项,请按如下所述操作:
控制台
在 Google Cloud 控制台中,前往环境页面。
在环境列表中,点击您的环境名称。环境详情页面会打开。
前往 PyPI 软件包标签页。
点击修改
点击添加软件包。
在 PyPI 软件包部分,指定软件包名称以及可选的版本说明符和 extras。
例如:
scikit-learn
scipy
,>=0.13.3
nltk
,[machine_learning]
点击保存。
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
替换为环境所在的区域。
安装一个软件包
更新您的环境,并在 --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
替换为可选的 version 和 extras 说明符。如需省略版本和 extras,请指定一个空值。
示例:
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 请求。
在此请求中:
在参数
updateMask
中,指定该掩码:- 使用
config.softwareConfig.pypiPackages
掩码替换所有现有掩码 包含指定软件包的软件包未指定的软件包会被删除。 - 使用
config.softwareConfig.envVariables.PACKAGE_NAME
添加或更新特定软件包。如需添加或更新多个软件包,请执行以下操作: 使用逗号分隔多个掩码。
- 使用
在请求正文中,为版本和 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
,其中包含可选的版本和 extra 说明符。如需省略版本和 extras,请指定一个空值。- 如需添加多个软件包,请在
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
工具可以安装。
pip
如需从具有公共地址的软件包代码库进行安装,请执行以下操作:
创建 pip.conf 文件,并在该文件中包含以下信息(如果适用):
- 代码库的网址(在
index-url
参数中) - 代码库的访问凭据
- 非默认
pip
安装选项
示例:
[global] index-url=https://example.com/
- 代码库的网址(在
(可选)在某些情况下,您可能需要从多个代码库提取软件包,例如,当公共代码库包含您要安装的某些特定软件包,而您又想从 PyPI 安装所有其他软件包时:
- 配置 Artifact Registry 虚拟代码库。
- 为多个代码库(包括 PyPI,如果需要)添加配置,并定义
pip
搜索代码库的顺序。 - 在
index-url
参数中指定虚拟代码库的网址。
将 pip.conf 文件上传到
/config/pip/
创建文件夹使用可用的方法之一安装软件包。
从 Artifact Registry 代码库安装软件包
您可以在项目中将软件包存储在 Artifact Registry 代码库中,并将环境配置为从中安装。
配置角色和权限:
您的环境的服务账号必须具有
iam.serviceAccountUser
角色。请确保该 Cloud Build 服务账号 从 Artifact Registry 代码库中读取的权限。
如果您的环境限制了对服务账号中其他服务的访问, 项目,例如,如果您使用 VPC Service Controls:
将访问 Artifact Registry 代码库的权限分配给环境的服务账号,而不是 Cloud Build 服务账号。
确保在项目中配置了与 Artifact Registry 代码库的连接。
如需从 Artifact Registry 代码库安装自定义 PyPI 软件包,请执行以下操作:
创建一个 pip.conf 文件,如果适用,在文件中包含以下信息:
- Artifact Registry 代码库的网址(在
index-url
参数中) - 代码库的访问凭据
- 非默认
pip
安装选项
对于 Artifact Registry 代码库,请将
/simple/
附加到代码库 网址:[global] index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
- Artifact Registry 代码库的网址(在
(可选)在某些情况下,您可能需要从多个代码库提取软件包,例如,当您的 Artifact Registry 代码库包含您要安装的某些特定软件包,而您又想从 PyPI 安装所有其他软件包时:
- 配置 Artifact Registry 虚拟代码库。
- 为多个代码库(包括 PyPI,如果需要)添加配置,并定义
pip
搜索代码库的顺序。 - 在
index-url
参数中指定虚拟代码库的网址。
将此 pip.conf 文件上传到环境的存储桶中的
/config/pip/
文件夹。例如:gs://us-central1-example-bucket/config/pip/pip.conf
。使用可用的方法之一安装软件包。
从私有代码库安装软件包
您可以在项目的网络中托管私有代码库,并配置环境以从中安装 Python 软件包。
配置角色和权限:
Cloud Composer 环境的服务账号必须 具有
iam.serviceAccountUser
角色。如果您从项目 并且此代码库没有公共 IP 地址:
向环境的服务账号分配访问此代码库的权限。
确保在项目中配置了与此代码库的连接。
如需从项目网络中托管的私有代码库安装软件包,请执行以下操作:
创建一个 pip.conf 文件,如果适用,在文件中包含以下信息:
- 项目网络中代码库的 IP 地址
- 代码库的访问凭据
- 非默认
pip
安装选项
示例:
[global] index-url=https://192.0.2.10/
(可选)在某些情况下,您可能需要从多个代码库提取软件包,例如,当私有代码库包含您要安装的某些特定软件包,而您又想从 PyPI 安装所有其他软件包时:
- 配置 Artifact Registry 虚拟仓库。
- 为多个代码库(包括 PyPI,如果需要)添加配置,并定义
pip
搜索代码库的顺序。 - 在
index-url
参数中指定虚拟代码库的网址。
(可选)在 2.2.1 及更高版本的 Cloud Composer 中,您可以在从私有代码库安装软件包时使用自定义证书。为此,请执行以下操作:
将证书文件上传到
/config/pip/
文件夹。在 pip.conf 中,在
cert
参数中指定证书文件的名称。请勿更改/etc/pip/
文件夹。示例:
[global] cert =/etc/pip/example-certificate.pem
将 pip.conf 文件上传到环境存储桶中的
/config/pip/
文件夹。例如:gs://us-central1-example-bucket/config/pip/pip.conf
。使用可用的方法之一安装软件包。
安装本地 Python 库
如需安装内部或本地 Python 库,请执行以下操作:
将依赖项放在环境存储桶的
dags/
文件夹的子目录中。如需从子目录导入某个模块,该模块的路径中的每个子目录都必须包含一个__init__.py
软件包标记文件。在以下示例中,依赖项为
coin_module.py
:dags/ use_local_deps.py # A DAG file. dependencies/ __init__.py coin_module.py
从 DAG 定义文件导入该依赖项。
例如:
使用依赖于共享对象库的软件包
某些 PyPI 软件包取决于系统级库。 虽然 Cloud Composer 不支持系统库,但您可以使用以下方法:
使用 KubernetesPodOperator。将操作节点映像设置为自定义构建映像。如果您在安装过程中遇到软件包因以下原因而安装失败的问题: 不符合要求的系统依赖项,请使用此选项。
将共享对象库上传到环境的存储桶。如果您的 PyPI 包已成功安装,但在运行时失败,请使用此选项。
- 手动查找 PyPI 依赖项的共享对象库 (.so 文件)。
- 将共享对象库上传到以下位置的
/plugins
文件夹: 环境的存储桶中。 - 设置以下环境变量:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins
在专用 IP 环境中安装软件包
本部分介绍了如何在专用 IP 环境中安装软件包。
根据您配置项目的方式,您的环境可能无法访问公共互联网。
具有公共互联网访问权限的专用 IP 环境
如果您的专用 IP 环境可以访问公共互联网,则可以使用适用于公共 IP 环境的选项安装软件包:
- 从 PyPI 安装。在这种情况下,无需特殊配置。 请按照 从 PyPI 安装软件包。
- 从具有公共 IP 地址的代码库进行安装。 按照从私有代码库安装软件包中所述的过程操作。
- 从 Google Cloud 控制台中托管的私有 PyPI 代码库中安装 项目的网络。
无法访问互联网的专用 IP 环境
如果您的专用 IP 环境无法访问公共互联网,您可以使用以下任一方法安装软件包:
- 使用托管在项目网络中的私有 PyPI 代码库。
- 使用您项目网络中的代理服务器虚拟机进行连接
发布到公共互联网上的 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 环境的指南 无法连接互联网的情况。