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

Cloud Composer 1 |Cloud Composer 2 |Cloud Composer 3

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

Composer 本地开发 CLI 工具简介

Composer Local Development CLI 工具可简化 Apache Airflow DAG 开发流程 在本地运行 Airflow 环境来实现 Cloud Composer 部署。这个 本地 Airflow 环境使用特定 Cloud Composer 的映像 版本。

您可以根据现有的 Cloud Composer 环境。在此示例中，本地 环境获取已安装 PyPI 软件包和环境变量的列表 Cloud Composer 环境中的名称。

您可以使用以下本地 Airflow 环境进行测试和开发 例如测试新的 DAG 代码、PyPI 软件包或 Airflow 配置 选项。

准备工作

  • Composer Local Development CLI 工具 运行 composer-dev create 命令所在的目录。要访问您的 在本地 Airflow 环境中， 您最初创建的是本地环境。以下时间段的所有数据： 本地环境存储在您所创建的路径下的子目录中 本地环境：./composer/<local_environment_name>。

  • 您的计算机必须有足够的磁盘空间来存储 Cloud Composer 图片。Composer 本地开发 CLI 工具会针对每个 API 存储一个图片文件 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 Local Development CLI 工具和 DAG 完成的所有 API 调用 通过您在 gcloud CLI 中使用的账号执行。对于 例如，如果本地 Airflow 环境中的 DAG 读取 Cloud Storage 存储桶，则此账号必须拥有以下权限： 访问该存储桶。这与 Cloud Composer 不同 环境，即环境的服务账号在其中进行调用。

安装 Composer 本地开发 CLI 工具

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

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

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

pip install .

该工具的安装路径取决于您的 pip 配置 可能不在 PATH 变量中。如果出现这种情况，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.5-airflow-2.7.3 \
  example-local-environment

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

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

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

  • 注释了您在命令行中设置的环境变量的名称列表 环境

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

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

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 系统会停止并重新启动组件因此 会被标记为“失败”。

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

composer-dev restart LOCAL_ENVIRONMENT_NAME

您需要将其中的：

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

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

composer-dev stop LOCAL_ENVIRONMENT_NAME

添加和更新 DAG

DAG 存储在您在 --dags-path 中指定的目录中 参数。默认情况下， 目录为 ./composer/<local_environment_name>/dags。您可以使用 describe 命令在您的环境所用的目录中。

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

查看本地 Airflow 环境日志

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

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

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

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

composer-dev logs LOCAL_ENVIRONMENT_NAME

运行 Airflow CLI 命令

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

如需运行 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 环境，例如环境变量和 PyPI 软件包 本地环境的目录中的 (./composer/<local_environment_name>).

配置会在本地 Airflow 环境启动时应用。对于 例如，如果您添加了存在冲突的 PyPI 软件包要求，请使用 Composer Local 当您启动本地环境时，开发 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 软件包，请修改requirements.txt 环境目录：./composer/<local_environment_name>/requirements.txt。

要求必须遵循 PEP-508，其中每项要求都是 以小写形式指定，包含软件包名称和可选 extra 和版本说明符

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

切换到其他 Cloud Composer 映像

您可以将任何 Cloud Composer 映像与 Composer 本地开发搭配使用 CLI 工具，以及在映像之间切换。这种方法不同于 升级 Cloud Composer 环境，因为 本地 Airflow 环境的配置参数会在 。

例如，在部署了新的 Cloud Composer 版本后， 您可以切换环境以使用新版本，并 现有的本地 Airflow 环境配置。再举一例，您可以 在特定的 Cloud Composer 版本。

如需更改本地 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 目录不 默认可用此外，您无法通过界面（设置）进行添加。 &gt; 资源 &gt; 文件共享）。

在这种情况下，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。

后续步骤