跳转到主要内容

一个用于简化Apache Airflow™入门和管理多个Airflow项目的命令行工具。

项目描述

airflowctl

PyPI License Python PyPI - Downloads Code style: black pre-commit.ci status

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 依赖于 uvpyenv 下载和安装 Python 版本(如果尚未安装)。

例如,如果您已安装 Python 3.8,但在 settings.yaml 文件中指定了 Python 3.7,CLI 将使用 uvpyenv 安装 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 文件中添加以下环境变量来使用 LocalExecutorsqlite 作为后端数据库:

_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 文件以读取连接和变量。然后,它将重新用作 airflowctlsettings 文件。

例如,如果您有一个 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 许可协议许可

项目详情


下载文件

下载适用于您的平台的文件。如果您不确定选择哪个,请了解有关安装软件包的更多信息。

源分布

airflowctl-0.2.11.tar.gz (27.5 kB 查看哈希)

上传时间:

构建分布

airflowctl-0.2.11-py3-none-any.whl (29.4 kB 查看哈希)

上传时间: Python 3

由以下支持