一个用于简化Apache Airflow™入门和管理多个Airflow项目的命令行工具。
项目描述
airflowctl
airflowctl 是一个用于管理Apache Airflow™项目的命令行工具。它提供了一系列命令来初始化、构建、启动、停止和管理Airflow项目。使用 airflowctl，您可以轻松地设置和管理您的Airflow项目，安装特定版本的Apache Airflow，并管理虚拟环境。
airflowctl 的主要目标是让首次使用Airflow的用户通过单个命令安装和设置Airflow，并让现有Airflow用户在同一个机器上管理不同版本的Airflow项目。
功能
- 带有连接和变量的项目初始化： 使用可定制的项目名称、Apache Airflow版本和Python版本初始化新的Airflow项目。它还允许您管理Airflow连接和变量。
- 自动虚拟环境管理： 自动为您的Airflow项目创建和管理虚拟环境，即使您的系统上未安装Python版本也是如此。
- Airflow版本管理： 安装和管理特定版本的Apache Airflow。
- 后台进程管理： 具有进程管理功能，在后台启动和停止Airflow。
- 实时日志显示： 使用可选的日志过滤，持续显示后台Airflow进程的实时日志。
目录
安装
pip install airflowctl
快速入门
要使用最新版本的 airflow 初始化新项目，构建虚拟环境并运行项目，请运行以下命令：
airflowctl init my_airflow_project --build-start
这将启动 Airflow 并在终端中显示日志。您可以在 https://:8080 访问 Airflow UI。要停止 Airflow，按 Ctrl+C。
使用方法
步骤 1：初始化新项目
要创建新的 Apache Airflow 项目，请使用 init 命令。此命令设置基本项目结构，包括配置文件、目录和示例 DAG。
airflowctl init <project_name> --airflow-version <version> --python-version <version>
示例
airflowctl init my_airflow_project --airflow-version 2.6.3 --python-version 3.8
这将创建具有以下结构的新项目目录：
my_airflow_project
├── .env
├── .gitignore
├── dags
│ └── example_dag_basic.py
├── plugins
├── requirements.txt
└── settings.yaml
文件和目录说明
.env文件包含项目的环境变量。.gitignore文件包含默认的 gitignore 设置。dags目录包含示例 DAG。plugins目录包含示例插件。requirements.txt文件包含项目的依赖项。settings.yaml文件包含项目设置，包括项目名称、Airflow 版本、Python 版本和虚拟环境路径。
在我们的示例中，settings.yaml 文件看起来可能如下所示：
# Airflow version to be installed
airflow_version: "2.6.3"
# Python version for the project
python_version: "3.8"
# Path to a virtual environment to be used for the project
mode:
name: "uv"
config:
venv_path: "PROJECT_DIR/.venv"
# Airflow connections
connections:
# Example connection
# - conn_id: example
# conn_type: http
# host: http://example.com
# port: 80
# login: user
# password: pass
# schema: http
# extra:
# example_extra_field: example-value
# Airflow variables
variables:
# Example variable
# - key: example
# value: example-value
# description: example-description
编辑 settings.yaml 文件以自定义项目设置。
步骤 2：构建项目
build 命令创建虚拟环境，安装指定的 Apache Airflow 版本，并设置项目依赖项。
在项目目录中运行 build 命令。
cd my_airflow_project
airflowctl build
CLI 依赖于 uv 或 pyenv 下载和安装 Python 版本（如果尚未安装）。
例如，如果您已安装 Python 3.8，但在 settings.yaml 文件中指定了 Python 3.7，CLI 将使用 uv 或 pyenv 安装 Python 3.7，并首先创建一个使用 Python 3.7 的虚拟环境。
可选地，如果您已安装 apache-airflow 软件包和其他依赖项，可以选择自定义虚拟环境路径。使用 --venv_path 选项将现有虚拟环境路径传递给 init 命令或在 settings.yaml 文件中。确保现有的虚拟环境与 settings.yaml 文件中声明的 airflow 和 Python 版本相同。
步骤 3：启动 Airflow
要启动 Airflow 服务，请使用 start 命令。此命令激活虚拟环境并启动 Airflow 网络服务器和调度程序。
示例
airflowctl start my_airflow_project
您也可以使用 --background 标志在后台启动 Airflow。
airflowctl start my_airflow_project --background
步骤 4：监控日志
要监控后台 Airflow 进程的日志，请使用 logs 命令。此命令显示实时日志并提供选项以过滤特定组件的日志。
示例
airflowctl logs my_airflow_project
要过滤特定组件的日志
# Filter logs for scheduler
airflowctl logs my_airflow_project -s
# Filter logs for webserver
airflowctl logs my_airflow_project -w
# Filter logs for triggerer
airflowctl logs my_airflow_project -t
# Filter logs for scheduler and webserver
airflowctl logs my_airflow_project -s -w
步骤 5：停止 Airflow
如果 Airflow 服务仍在运行，请使用 stop 命令停止服务。
示例
airflowctl stop my_airflow_project
步骤 6：列出 Airflow 项目
要列出所有 Airflow 项目，请使用 list 命令。
示例
airflowctl list
步骤 7：显示项目信息
要显示项目信息，请使用 info 命令。
示例
# From the project directory
airflowctl info
# From outside the project directory
airflowctl info my_airflow_project
步骤 8：运行 Airflow 命令
要运行 Airflow 命令，请使用 airflowctl airflow 命令。所有在 airflowctl airflow 之后的所有命令都将传递给 Airflow CLI。
# From the project directory
airflowctl airflow <airflow_command>
示例
$ airflowctl airflow version
2.6.3
您也可以运行 airflowctl airflow --help 来查看可用命令的列表。
$ airflowctl airflow --help
Usage: airflowctl airflow [OPTIONS] COMMAND [ARGS]...
Run Airflow commands.
Positional Arguments:
GROUP_OR_COMMAND
Groups:
celery Celery components
config View configuration
connections Manage connections
dags Manage DAGs
db Database operations
jobs Manage jobs
kubernetes Tools to help run the KubernetesExecutor
pools Manage pools
providers Display providers
roles Manage roles
tasks Manage tasks
users Manage users
variables Manage variables
Commands:
cheat-sheet Display cheat sheet
dag-processor Start a standalone Dag Processor instance
info Show information about current Airflow and environment
kerberos Start a kerberos ticket renewer
plugins Dump information about loaded plugins
rotate-fernet-key
Rotate encrypted connection credentials and variables
scheduler Start a scheduler instance
standalone Run an all-in-one copy of Airflow
sync-perm Update permissions for existing roles and optionally DAGs
triggerer Start a triggerer instance
version Show the version
webserver Start a Airflow webserver instance
Options:
-h, --help show this help message and exit
示例
# Listing dags
$ airflowctl airflow dags list
dag_id | filepath | owner | paused
==================+======================+=========+=======
example_dag_basic | example_dag_basic.py | airflow | True
# Running standalone
$ airflowctl airflow standalone
或者，您首先激活虚拟环境，然后运行以下命令。
示例
# From the project directory
source .venv/bin/activate
# Source all the environment variables
source .env
airflow version
要将新的 DAG 添加到项目中，请将 DAG 文件添加到 dags 目录。
要编辑现有的 DAG，请编辑 dags 目录中的 DAG 文件。更改将在 Airflow 网络服务器中反映出来。
步骤 9：更改空气流量配置
airflowctl 默认使用 SQLite 作为后端数据库，并使用 SequentialExecutor 作为执行器。但是，如果您想使用其他数据库或执行器，可以停止项目并执行以下操作之一：a) 编辑 airflow.cfg 文件或 b) 在 .env 文件中添加环境变量。
示例
# Stop the project
airflowctl stop my_airflow_project
# Changing the executor to LocalExecutor
# Change the database to PostgreSQL if you already have it installed
echo "AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://airflow:airflow@localhost:5432/airflow" >> .env
echo "AIRFLOW__CORE__EXECUTOR=LocalExecutor" >> .env
# Start the project
airflowctl start my_airflow_project
请参阅Airflow 文档以获取所有可用的 Airflow 配置。
使用 SQLite 与本地执行器
对于 Airflow >= 2.6，您可以通过在 .env 文件中添加以下环境变量来使用 LocalExecutor 和 sqlite 作为后端数据库：
_AIRFLOW__SKIP_DATABASE_EXECUTOR_COMPATIBILITY_CHECK=1
AIRFLOW__CORE__EXECUTOR=LocalExecutor
[!WARNING] SQLite 不建议在生产环境中使用。仅用于开发和测试。
其他命令
有关更多信息和使用选项，您可以在每个命令中使用 --help 标志。
与其他 Airflow 工具一起使用
airflowctl 可以与其他具有相同项目结构的 Airflow 项目一起使用。
Astro CLI
airflowctl 也可以与Astro CLI项目一起使用。
虽然 airflowctl 是一个允许您在虚拟环境中本地运行 Airflow 的工具，但 Astro CLI 允许您使用 docker 本地运行 Airflow。
airflowctl 可以读取 Astro CLI 生成的 airflow_settings.yaml 文件以读取连接和变量。然后，它将重新用作 airflowctl 的 settings 文件。
例如，如果您有一个 Astro CLI 项目
- 在项目目录中运行
airflowctl init . --build-start命令以初始化airflowctl。当提示时，按y继续操作。 - 它将询问您 Airflow 版本，输入您正在使用的版本，默认使用最新版本的 Airflow，按回车键继续
- 它将使用已安装的 Python 版本作为项目的 Python 版本。如果您想使用不同的 Python 版本，您可以在
airflow_settings.yaml文件中的python_version字段中指定它。
# From the project directory
$ cd astro_project
$ airflowctl init . --build-start
Directory /Users/xyz/astro_project is not empty. Continue? [y/N]: y
Project /Users/xyz/astro_project added to tracking.
Airflow project initialized in /Users/xyz/astro_project
Detected Astro project. Using Astro settings file (/Users/kaxilnaik/Desktop/proj1/astro_project/airflow_settings.yaml).
'airflow_version' not found in airflow_settings.yaml file. What is the Airflow version? [2.6.3]:
Virtual environment created at /Users/xyz/astro_project/.venv
...
...
如果您看到以下错误，请从项目目录中删除 airflow.cfg 文件，如果存在，请从 .env 文件中删除 AIRFLOW_HOME 并再次尝试。
Error: there might be a problem with your project starting up.
The webserver health check timed out after 1m0s but your project will continue trying to start.
Run 'astro dev logs --webserver | --scheduler' for details.
许可证
本项目根据Apache 2.0 许可协议许可
