Cloud Composer 1 处于维护后模式。Google 无法发布 Cloud Composer 1 的进一步更新，包括新版 Airflow、问题修复和安全更新。我们建议您规划迁移到 Cloud Composer 2。

此页面由 Cloud Translation API 翻译。

使用 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 本地开发 CLI 工具会在您运行 composer-dev create 命令的目录中创建本地 Airflow 环境。要访问您的在本地 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 工具依赖项：
- 带有 pip 的 Python 3.7 - 3.10 版
- Google Cloud 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 不同环境，即环境的服务账号在其中进行调用。

安装 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.9.7-airflow-2.9.3 \
  example-local-environment

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

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

映像版本（您的环境中使用的 Cloud Composer 和 Airflow 版本）。
在您的 SDK 中安装的自定义 PyPI 软件包的列表环境
注释了您在命令行中设置的环境变量名称列表环境

重要提示 ：Cloud Composer 不会复制 环境变量您可以手动取消注释环境变量并根据需要设置其值。

环境中的其他信息和配置参数，例如 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 容器中的近期日志。通过这种方式，您可以监控与容器相关的事件并检查关于错误（例如由 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 本地开发 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 环境使用的环境映像，请执行以下操作：

修改本地环境配置文件：./composer/<local_environment_name>/config.json。
更改 composer_image_version 参数的值。如需查看可用值，您可以列出可用的 Cloud Composer 版本。
如需应用更改，请重启本地 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。

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

Composer 本地开发 CLI 工具简介

准备工作

配置凭据

安装 Composer 本地开发 CLI 工具

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

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

启动本地 Airflow 环境

停止或重启本地 Airflow 环境

添加和更新 DAG

查看本地 Airflow 环境日志

运行 Airflow CLI 命令

配置本地 Airflow 环境

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

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

安装插件和更改数据

配置环境变量

安装或移除 PyPI 软件包

切换到其他 Cloud Composer 映像

删除本地 Airflow 环境

删除 Docker 映像

问题排查

无法在 MacOS 上启动本地环境

后续步骤