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

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本部分介绍了如何使用 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 .

根据 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.11.1-airflow-2.10.2 \
  example-local-environment

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

系统只会从 Cloud Composer 环境中获取以下信息：

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

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

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

如需基于现有 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 环境的配置参数（例如环境变量和 PyPI 软件包要求）存储在本地环境的目录 (./composer/<local_environment_name>) 中。

在启动本地 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 软件包，请修改环境目录中的 requirements.txt 文件：./composer/<local_environment_name>/requirements.txt。

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

如需应用更改，请重启本地 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 本地开发 CLI 工具下载的所有映像，请运行以下命令：

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

问题排查

本部分介绍了常见问题的解决方案。

无法在 macOS 上启动本地环境

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

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

在这种情况下，Composer 本地开发 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。

后续步骤