使用 Composer 本地开发 CLI 工具运行本地 Airflow 环境

Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3

本部分介绍如何使用 Composer 本地开发 CLI 工具创建、配置和运行本地 Airflow 环境。

Composer 本地开发 CLI 工具简介

Composer 本地开发 CLI 工具通过在本地运行 Airflow 环境来简化 Cloud Composer 的 Apache Airflow DAG 开发流程。此本地 Airflow 环境使用特定 Cloud Composer 版本的映像。

您可以基于现有的 Cloud Composer 环境创建本地 Airflow 环境。在这种情况下，本地 Airflow 环境会从 Cloud Composer 环境中获取已安装 PyPI 软件包的列表以及环境变量名称。

您可以将此本地 Airflow 环境用于测试和开发目的，例如测试新 DAG 代码、PyPI 软件包或 Airflow 配置选项。

准备工作

  • Composer 本地开发 CLI 工具会在您运行 composer-dev create 命令的目录中创建本地 Airflow 环境。如需稍后访问本地 Airflow 环境，请在最初创建本地环境的路径中运行工具命令。本地环境的所有数据都存储在您创建本地环境的路径下的一个子目录中：./composer/<local_environment_name>。

  • 您的计算机必须有足够的磁盘空间来存储 Cloud Composer 图片。Composer 本地开发 CLI 工具会为每个 Cloud Composer 版本存储一个图片文件。例如，如果您有两个具有不同 Cloud Composer 版本的本地 Airflow 环境，Composer 本地开发 CLI 工具会存储两个 Cloud Composer 映像。

  • Composer 本地开发 CLI 工具使用彩色输出。您可以使用 NO_COLOR=1 变量 NO_COLOR=1 composer-dev <other commands> 停用着色输出。

  • 如果只有一个本地环境，则可以在所有 composer-dev 命令中省略本地环境的名称（run-airflow-cmd 除外）。

  • 安装 Composer 本地开发 CLI 工具依赖项：

  • 安装 Docker。Docker 必须在本地系统中安装并运行。如需验证 Docker 是否正在运行，您可以运行任何 Docker CLI 命令，例如 docker ps。

配置凭据

请获取用于应用默认凭据的新用户凭据（如果尚未执行此操作）：

gcloud auth application-default login

使用您的 Google 账号登录 gcloud CLI：

gcloud auth login

Composer 本地开发 CLI 工具和 DAG 执行的所有 API 调用都是通过您在 gcloud CLI 中使用的帐号执行。例如，如果本地 Airflow 环境中的 DAG 读取 Cloud Storage 存储桶的内容，则此帐号必须具有访问该存储桶的权限。这与 Cloud Composer 环境不同，在 Cloud Composer 环境中，环境的服务帐号会发出调用。

安装 Composer 本地开发 CLI 工具

克隆 Composer 本地开发 CLI 代码库：

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

在克隆代码库的顶级目录中，运行以下命令：

pip install .

该工具的安装路径可能不在 PATH 变量中，具体取决于您的 pip 配置。在这种情况下，pip 会显示警告消息。您可以使用此警告消息中的信息将此目录添加到操作系统中的 PATH 变量。

使用特定 Cloud Composer 版本创建本地 Airflow 环境

如需列出 Cloud Composer 的可用版本，请运行以下命令：

composer-dev list-available-versions --include-past-releases --limit 10

如需使用默认参数创建本地 Airflow 环境，请运行以下命令：

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

其他参数：

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

您需要在其中：

  • 将 IMAGE_VERSION 替换为 Cloud Composer 映像的名称。
  • 将 PROJECT_ID 替换为项目 ID。
  • 将 WEB_SERVER_PORT 替换为 Airflow Web 服务器必须监听的端口。
  • 将 LOCAL_DAGS_PATH 替换为 DAG 文件所在本地目录的路径。
  • 将 LOCAL_ENVIRONMENT_NAME 替换为此本地 Airflow 环境的名称。

示例：

composer-dev create \
  --from-image-version composer-2.8.3-airflow-2.7.3 \
  example-local-environment

通过 Cloud Composer 环境创建本地 Airflow 环境

仅以下信息来自 Cloud Composer 环境：

  • 映像版本（您的环境中使用的 Cloud Composer 和 Airflow 版本）。
  • 您的环境中安装的自定义 PyPI 软件包列表。

  • 在您的环境中设置的环境变量名称列表（带注释）。

该环境中的其他信息和配置参数（例如 DAG 文件、DAG 运行历史记录、Airflow 变量和连接）不会从 Cloud Composer 环境中复制。

如需基于现有 Cloud Composer 环境创建本地 Airflow 环境，请执行以下操作：

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

您需要在其中：

  • 将 LOCAL_ENVIRONMENT_NAME 替换为本地 Airflow 环境的名称。
  • 将 ENVIRONMENT_NAME 替换为 Cloud Composer 环境的名称。
  • 将 LOCATION 替换为 Cloud Composer 环境所在的区域。
  • 将 PROJECT_ID 替换为项目 ID。
  • 将 WEB_SERVER_PORT 替换为本地 Airflow Web 服务器的端口。
  • 将 LOCAL_DAGS_PATH 替换为 DAG 所在的本地目录的路径。

示例：

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

启动本地 Airflow 环境

如需启动本地 Airflow 环境，请运行以下命令：

composer-dev start LOCAL_ENVIRONMENT_NAME

您需要在其中：

  • 将 LOCAL_ENVIRONMENT_NAME 替换为本地 Airflow 环境的名称。

停止或重启本地 Airflow 环境

重启本地 Airflow 环境时，Composer 本地开发 CLI 工具会重启运行该环境的 Docker 容器。所有 Airflow 组件都会停止并重新启动。因此，在重启期间执行的所有 DAG 运行都会被标记为失败。

如需重启或启动已停止的本地 Airflow 环境，请运行以下命令：

composer-dev restart LOCAL_ENVIRONMENT_NAME

您需要在其中：

  • 将 LOCAL_ENVIRONMENT_NAME 替换为本地 Airflow 环境的名称。

如需停止本地 Airflow 环境，请运行以下命令：

composer-dev stop LOCAL_ENVIRONMENT_NAME

添加和更新 DAG

DAG 存储在创建本地 Airflow 环境时在 --dags-path 参数中指定的目录中。默认情况下，此目录为 ./composer/<local_environment_name>/dags。您可以使用 describe 命令获取您的环境使用的目录。

如需添加和更新 DAG，请更改此目录中的文件。您无需重启本地 Airflow 环境。

查看本地 Airflow 环境日志

您可以查看运行本地 Airflow 环境的 Docker 容器的近期日志。通过这种方式，您可以监控与容器相关的事件，并检查 Airflow 日志中是否存在错误，例如 PyPI 软件包安装导致的依赖项冲突。

如需查看运行本地 Airflow 环境的 Docker 容器的日志，请运行以下命令：

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

若要跟踪日志流，请省略 --max-lines 参数：

composer-dev logs LOCAL_ENVIRONMENT_NAME

运行 Airflow CLI 命令

您可以在本地 Airflow 环境中运行 Airflow CLI 命令。

如需运行 Airflow CLI 命令，请执行以下操作：

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

示例：

composer-dev run-airflow-cmd example-local-environment dags list -o table

配置本地 Airflow 环境

Composer 本地开发 CLI 工具将本地 Airflow 环境的配置参数存储在本地环境的目录 (./composer/<local_environment_name>) 中，例如环境变量和 PyPI 软件包要求。

配置会在本地 Airflow 环境启动时应用。例如，如果您添加了存在冲突的 PyPI 软件包要求，当您启动本地环境时，Composer 本地开发 CLI 工具会报告错误。

Airflow 连接存储在本地 Airflow 环境的数据库中。您可以运行 Airflow CLI 命令或将连接参数存储在环境变量中，以对它们进行配置。如需详细了解创建和配置连接的方法，请参阅 Airflow 文档中的管理连接。

获取本地 Airflow 环境的列表和状态

如需列出所有可用的本地 Airflow 环境并显示其状态，请使用以下命令：

composer-dev list

如需描述特定环境并获取详细信息，例如该环境的映像版本、DAG 路径和 Web 服务器网址，请执行以下操作：

composer-dev describe LOCAL_ENVIRONMENT_NAME

您需要在其中：

  • 将 LOCAL_ENVIRONMENT_NAME 替换为本地 Airflow 环境的名称。

列出本地 Airflow 环境使用的映像

如需列出 Composer 本地开发 CLI 工具使用的所有映像，请运行以下命令：

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

安装插件和更改数据

本地 Airflow 环境的插件和数据取自本地环境的目录：./composer/<local_environment_name>/data 和 ./composer/<local_environment_name>/plugins。

如需更改 /data 和 /plugins 目录的内容，请添加或移除这些目录中的文件。Docker 会自动将文件更改传播到本地 Airflow 环境。

Composer 本地开发 CLI 工具不支持为数据和插件指定其他目录。

配置环境变量

如需配置环境变量，请修改环境目录中的 variables.env 文件：./composer/<local_environment_name>/variables.env。

variables.env 文件必须包含键值对定义，每个环境变量占一行。如需更改 Airflow 配置选项，请使用 AIRFLOW__SECTION__KEY 格式。如需详细了解可用的环境变量，请参阅 Airflow 配置参考文档。

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

如需应用更改，请重启本地 Airflow 环境。

安装或移除 PyPI 软件包

如需安装或移除 PyPI 软件包，请修改环境目录 ./composer/<local_environment_name>/requirements.txt 中的 requirements.txt 文件。

要求必须遵循 PEP-508 中指定的格式，其中每项要求均以小写形式指定，并且包含软件包名称（可选 extra 和版本说明符）。

如需应用更改，请重启本地 Airflow 环境。

切换到其他 Cloud Composer 映像

您可以将任何 Cloud Composer 映像与 Composer 本地开发 CLI 工具搭配使用，并在映像之间切换。此方法与升级 Cloud Composer 环境不同，因为系统会在本地 Airflow 环境启动时应用其配置参数。

例如，在新的 Cloud Composer 版本发布后，您可以将环境切换为使用新版本，并保留现有的本地 Airflow 环境配置。再举一例，您可以在特定 Cloud Composer 版本中的不同 Airflow 版本之间切换。

如需更改本地 Airflow 环境使用的环境映像，请执行以下操作：

  1. 修改本地环境配置文件：./composer/<local_environment_name>/config.json。

  2. 更改 composer_image_version 参数的值。如需查看可用值，您可以列出可用的 Cloud Composer 版本。

  3. 如需应用更改，请重启本地 Airflow 环境。

删除本地 Airflow 环境

注意：请务必保存环境中的所有必需数据，例如日志和配置。

如需删除本地 Airflow 环境，请运行以下命令：

composer-dev remove LOCAL_ENVIRONMENT_NAME

如果环境正在运行，请添加 --force 标志以强制移除该环境。

删除 Docker 映像

如需删除 Composer Local Development CLI 工具下载的所有映像，请运行以下命令：

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

问题排查

本部分提供了常见问题的解决方案。

无法在 MacOS 上启动本地环境

如果您将 composer-dev 软件包安装到 Docker 无法访问的目录中，则本地环境可能无法启动。

例如，如果 Python 安装在 /opt 目录中（例如在 MacOS 上使用默认 Homebrew 配置安装时），composer-dev 软件包也会安装在 /opt 目录中。由于 Docker 符合 Apple 的沙盒规则，因此 /opt 目录默认不可用。此外，您无法通过界面（设置 > 资源 > 文件共享）添加该文件。

在这种情况下，Composer Local Development CLI 工具会生成类似于以下示例的错误消息：

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

您可以使用以下解决方案之一：

  • 将 Python 或 composer-dev 软件包安装到其他目录，以便 Docker 可以访问该软件包。
  • 手动修改 ~/Library/Group\ Containers/group.com.docker/settings.json 文件并将 /opt 添加到 filesharingDirectories。

后续步骤