業界・業務から探す
導入目的・課題から探す
データ・AIについて学ぶ
News
Hakkyについて
ウェビナーコラム
◆トップ【データ基盤】
データハブとは
Ajust
データの保守運用
AI

執筆者:Hakky AI

Airflow|ローカル環境構築でハマらない!手順と注意点

tip
記事のポイント
  • DockerでAirflowのローカル環境を構築する手順を解説。設定から動作確認までを網羅的に説明。
  • airflow.cfgや環境変数の設定方法、DAGファイルの配置場所など、初期設定と環境構築を解説。
  • Docker Composeによるコンテナ化、UIでのDAG実行、トラブルシューティング、本番環境への移行を解説。

はじめに

本記事では、Airflowをローカル環境に構築し、動作確認を行うための手順を解説します。DockerとDAGファイルを使用し、Airflowの環境設定からセットアップ、動作確認までを網羅的に説明します。

Airflowの初期設定ファイルの作成、必要なツールのインストール、依存関係の確認を行い、Docker Desktopの設定やDAGファイルの配置方法、Airflowの設定ファイルの作成について詳しく解説します。

また、Docker Composeを用いたコンテナ化、トラブルシューティング、ローカル環境でのDAG開発についても触れ、本番環境への移行を見据えた応用方法も紹介します。

Airflowローカル環境構築の前提条件

Airflowをローカル環境で構築する前に、必要なツールと環境が整っているかを確認しましょう。Docker、Docker Compose、Pythonがインストールされていることを前提に、具体的な手順を解説します。

Docker Desktopのインストールと設定

Airflowをローカル環境で動作させるためには、Docker Desktopのインストールが不可欠です。まず、Docker公式サイトからDocker Desktopをダウンロードし、インストールしてください。

インストール後、Airflowのスムーズな動作のために、Docker Desktopの設定を最適化する必要があります。特に、メモリ割り当ては重要で、Airflowには少なくとも4GBのメモリが必要です。macOS環境では、Dockerに4GB以上、できれば8GBのメモリを割り当てることを推奨します。

Windows環境では、.wslconfigファイルを編集してメモリ割り当てを設定します。設定変更後、Docker Desktopを終了し、コマンドプロンプトでwsl --shutdownを実行後、Docker Desktopを手動で再起動してください。

macOSでは、以下のコマンドでメモリ容量を確認できます。

docker run --rm "debian:bookworm-slim" bash -c 'numfmt --to iec $(echo $(($(getconf _PHYS_PAGES) * $(getconf PAGE_SIZE))))'

このコマンドを実行することで、Dockerコンテナに割り当てられたメモリ容量を正確に把握し、必要に応じて調整できます。適切なメモリ設定を行うことで、Airflowの安定した動作を保証し、予期せぬエラーやパフォーマンスの低下を防ぐことができます。

Docker Desktopの設定は、Airflowのローカル環境構築において非常に重要なステップです。Dockerのバージョンが古い場合は、最新バージョンにアップデートすることを推奨します。最新バージョンでは、パフォーマンスの改善やセキュリティの強化が行われているため、より快適にAirflowを利用できます。

また、Docker Composeも合わせてインストールしておくと、複数のコンテナを連携させてAirflowを構築する際に便利です。Docker Composeを使用することで、Airflowの環境構築をより効率的に行うことができます。

Pythonとpipのバージョン確認

Airflowをローカル環境で動作させるためには、適切なPythonバージョンが必要です。Airflowの各バージョンは特定のPythonバージョンに対応しており、互換性のないバージョンを使用すると、インストールや実行時にエラーが発生する可能性があります。

Airflowの公式ドキュメントを参照し、使用するAirflowバージョンに必要なPythonバージョンを確認してください。Pythonのバージョンは、コマンドラインでpython --versionまたはpython3 --versionを実行することで確認できます。

もし必要なバージョンがインストールされていない場合は、pyenvなどのツールを使用して、複数のPythonバージョンを管理することを推奨します。

次に、pipのバージョンを確認します。pipはPythonのパッケージ管理ツールであり、Airflowの依存関係をインストールするために使用されます。pipのバージョンが古い場合は、最新バージョンにアップデートしてください。アップデートは、コマンドラインでpip install --upgrade pipを実行することで行えます。

Airflowの依存関係は開放されており、異なるバージョンのライブラリのインストールが可能です。しかし、特定のバージョンとの互換性がある制約ファイルを使用することで、より安定した環境を構築できます。

例えば、constraints-mainconstraints-2-0という制約ファイルがあり、それぞれ異なるPythonバージョンに対応しています。pipはインストールするかどうかはともかく、すでにインストールされているパッケージとの依存関係を調べる機能を持っています。

具体例として、protobufのインストールや更新は行われません (3.1.0のまま)。指定されたバージョン範囲に当てはまるバージョンが入っている場合は何もしてくれません。適合したバージョンの入力を行う必要があります。

Airflowのドキュメントには具体的なPythonやpipのバージョン範囲が詳細に記載されていません。制約ファイルの使用を推奨しており、pipの具体的なバージョン制約は示されていません。

Airflow初期設定と環境変数の設定

Airflowをローカル環境で効率的に利用するためには、初期設定と環境変数の適切な設定が不可欠です。ここでは、[airflow.cfg](https://book.st-hakky.com/data-platform/airflow-doc-md)の設定、環境変数の設定方法、そして設定ファイルの配置場所について詳しく解説します。

airflow.cfgの設定

airflow.cfgはAirflowの動作を左右する重要な設定ファイルであり、データベース接続や基本設定のカスタマイズが可能です。ローカル環境でのAirflow利用においては、SQLiteをデフォルトで使用できますが、より安定した運用のためにはPostgreSQLなどのデータベースを推奨します。

データベース接続の設定は、airflow.cfg内の[database](https://book.st-hakky.com/data-platform/what-is-ddl-database-management)セクションで行います。例えば、PostgreSQLを使用する場合、以下のように設定します。 sql_alchemy_conn = postgresql+psycopg2://airflow:airflow@localhost:5432/airflow

この設定により、Airflowは指定されたPostgreSQLデータベースに接続し、メタデータを管理します。また、coreセクションでは、dags_folderを設定することで、DAGファイルが配置されているディレクトリを指定できます。

例:dags_folder = /opt/airflow/dags。executorの設定も重要で、ローカル環境ではLocalExecutorが適しています。executor = LocalExecutor

これらの設定を適切に行うことで、Airflowはローカル環境でスムーズに動作し、DAGの実行やタスクの管理が容易になります。設定を変更した後は、Airflowを再起動して変更を適用してください。

環境変数の設定方法

Airflowの動作をカスタマイズするためには、環境変数の設定が不可欠です。最も重要な環境変数の一つがAIRFLOW_HOMEであり、Airflowが設定ファイルやログファイルを保存する基本ディレクトリを指定します。

AIRFLOW_HOMEを設定するには、ターミナルで以下のコマンドを実行します。 export AIRFLOW_HOME=/path/to/your/airflow/home

この設定により、Airflowは指定されたディレクトリをホームディレクトリとして認識し、関連ファイルを配置します。また、AIRFLOW__CORE__DAGS_FOLDER環境変数を設定することで、DAGファイルが配置されているディレクトリを明示的に指定できます。

例:export AIRFLOW__CORE__DAGS_FOLDER=/path/to/your/dags。さらに、データベース接続に関する環境変数も重要です。例えば、AIRFLOW__DATABASE__SQL_ALCHEMY_CONNを設定することで、データベース接続文字列を環境変数から指定できます。

例:export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://airflow:airflow@localhost:5432/airflow。これらの環境変数を適切に設定することで、Airflowはローカル環境での動作に必要な情報を取得し、柔軟なカスタマイズが可能になります。環境変数の設定後は、Airflowを再起動して変更を適用してください。

設定ファイルの配置場所

Airflowの設定ファイルを適切に配置することは、ローカル環境での安定した動作に不可欠です。airflow.cfgファイルは、通常$AIRFLOW_HOMEディレクトリに配置されます。

$AIRFLOW_HOMEが設定されていない場合、デフォルトでは~/airflowディレクトリが使用されます。設定ファイルを配置する際には、ディレクトリ構造を整理し、管理しやすいようにすることが重要です。

例えば、$AIRFLOW_HOMEディレクトリ内にairflow.cfgdagslogsなどのサブディレクトリを作成し、それぞれのファイルを適切に配置します。DAGファイルは$AIRFLOW_HOME/dagsディレクトリに、ログファイルは$AIRFLOW_HOME/logsディレクトリに配置します。

設定ファイルの配置場所を変更する場合は、AIRFLOW_HOME環境変数を適切に設定し、Airflowが正しい場所を参照するようにする必要があります。設定ファイルの配置場所が誤っていると、Airflowが設定を読み込めず、正常に動作しない可能性があります。

したがって、設定ファイルの配置場所は慎重に決定し、常に正しい場所にあることを確認してください。

設定項目設定例説明
sql_alchemy_connpostgresql+psycopg2://airflow:airflow@localhost:5432/airflowPostgreSQLデータベースへの接続文字列
dags_folder/opt/airflow/dagsDAGファイルが配置されているディレクトリ
executorLocalExecutorローカル環境でのExecutorの設定
AIRFLOW_HOME/path/to/your/airflow/homeAirflowのホームディレクトリ
AIRFLOW__CORE__DAGS_FOLDER/path/to/your/dagsDAGファイルが配置されているディレクトリ(環境変数)
AIRFLOW__DATABASE__SQL_ALCHEMY_CONNpostgresql+psycopg2://airflow:airflow@localhost:5432/airflowデータベース接続文字列(環境変数)

DAGファイルの配置と動作確認

Airflowで作成したDAGファイルを所定の場所に配置し、Airflow UIを通じて正常に動作するかを確認する手順について解説します。

DAGファイルの作成

Airflowで実行するワークフローを定義したDAGファイルを作成します。ここでは、簡単なサンプルDAGファイルを作成し、その基本的な構造を説明します。

まず、以下のPythonコードを記述してsample_dag.pyという名前で保存します。from airflow import DAGから始まるこのコードは、AirflowのDAGを定義するために必要なライブラリをインポートし、datetimeモジュールを使用してタスクの開始日時を設定します。

print_hello関数は、タスクが実行された際にコンソールにメッセージを出力するシンプルな関数です。with DAG(...) as dag:のブロック内で、DAGのID、開始日時、スケジュール設定、およびタスクの定義を行います。

PythonOperatorは、Python関数を実行するためのオペレーターであり、task_idでタスクを識別し、python_callableで実行する関数を指定します。この例では、hello_taskというIDを持つタスクがprint_hello関数を実行します。

このDAGは、Airflowによってスケジュールされ、定義されたタスクが実行されます。

from airflow import DAG
from airflow.operators.python import PythonOperator
from datetime import datetime

def print_hello():
    print("こんにちは! Airflow!")

with DAG(
    "sample_dag",
    start_date=datetime(2024, 1, 1),
    schedule=None,
    catchup=False,
) as dag:
    task = PythonOperator(
        task_id="hello_task",
        python_callable=print_hello,
    )

DAGファイルの配置場所

作成したDAGファイルをAirflowが認識できるように、適切なディレクトリに配置します。Airflowは、設定ファイルで指定されたdags_folderディレクトリを監視し、そのディレクトリに配置されたDAGファイルを自動的に読み込みます。

デフォルトでは、$AIRFLOW_HOME/dagsがDAGファイルの配置場所として設定されています。AIRFLOW_HOMEは通常/opt/airflowに設定されていますが、環境変数を通じて任意のパスに変更可能です。

DAGファイルを配置後、Airflow UIにアクセスしてDAGが正常に認識されているか確認します。もしDAGがUIに表示されない場合は、Airflowの設定ファイルairflow.cfgを確認し、dags_folderの設定が正しいことを確認してください。

また、AirflowスケジューラーがDAGファイルを正しく解析できるように、ファイル権限が適切に設定されていることを確認してください。配置したDAGファイルがAirflowによって認識され、UIに表示されれば、配置は成功です。

Docker環境を使用している場合は、Dockerコンテナ内の/opt/airflow/dagsディレクトリにDAGファイルをマウントする必要があります。これにより、コンテナ内でもAirflowがDAGファイルを読み取ることができます。

Airflow UIでのDAG実行

Airflow UIにアクセスして、配置したDAGが正常に動作するかを確認します。Airflow UIは、通常http://localhost:8080でアクセスできます。

UIにアクセスしたら、DAGの一覧から先ほど配置したsample_dagを探し、DAGの状態を確認します。DAGが有効になっていることを確認し、右側の▶️ボタンをクリックしてDAGを手動でトリガーします。

DAGが実行されると、タスクの状態が変化し、ログが生成されます。タスクの実行ログを確認するには、DAGの詳細画面からタスクを選択し、「View Log」をクリックします。

ログには、タスクが実行された際に出力されたメッセージやエラー情報が表示されます。もしタスクが失敗した場合は、ログを詳細に確認し、エラーの原因を特定して修正します。

正常にタスクが完了した場合、ログにはこんにちは! Airflow!というメッセージが表示されます。Airflow UIを通じてDAGの実行状況を監視し、必要に応じて設定を調整することで、安定したワークフローの実行を実現できます。

Hakkyのデータ基盤構築支援とは | 詳細はこちら

Docker ComposeによるAirflowのコンテナ化

AirflowをDocker Composeでコンテナ化することで、環境構築が容易になり、再現性が高まります。ここでは、docker-compose.ymlの基本構造から、コンテナの起動、停止、ログの確認方法までを解説します。

docker-compose.ymlの基本構造

docker-compose.ymlは、Airflow環境を構成するコンテナの設定を記述するファイルです。基本的な構造は、versionservicesの2つの要素で構成されます。versionにはDocker Composeのバージョンを指定し、servicesにはAirflowやPostgreSQLなどのサービスを定義します。

Airflowサービスの設定では、imageにAirflowのDockerイメージを指定し、portsでポートフォワーディングを設定します。例えば、以下のようになります。version: '3'services:web:image: apache/airflow:2.0.0container_name: airflowports:- 8080:8080volumes:- ./opt/airflow:/opt/airflowcommand: db init

この設定では、Airflowのコンテナはポート8080でアクセス可能になり、/opt/airflowにデータが保存されるよう指定されています。PostgreSQLサービスの設定では、Airflowのメタデータデータベースとして使用するPostgreSQLコンテナを定義します。imageにPostgreSQLのDockerイメージを指定し、environmentで環境変数を設定します。volumesでデータを永続化するためのボリュームを設定します。

これにより、Airflowのローカル環境構築が容易になり、開発やテストが効率的に行えます。

コンテナの起動と停止

Docker Composeを使用してAirflowコンテナを起動するには、docker-compose upコマンドを使用します。このコマンドは、docker-compose.ymlファイルに定義されたすべてのサービスを起動します。バックグラウンドで起動する場合は、-dオプションを追加します。

例えば、docker-compose up -dと入力することで、コンテナがバックグラウンドで起動し、ターミナルを他の作業に使用できます。コンテナの起動状態を確認するには、docker-compose psコマンドを使用します。このコマンドは、起動中のコンテナの状態を表示します。

コンテナを停止するには、docker-compose stopコマンドを使用します。このコマンドは、docker-compose.ymlファイルに定義されたすべてのサービスを停止します。特定のコンテナのみを停止する場合は、docker-compose stop <container_name>コマンドを使用します。

コンテナを完全に削除するには、docker-compose downコマンドを使用します。このコマンドは、コンテナ、ネットワーク、ボリュームを削除します。開発環境では、コンテナを停止せずに再起動したい場合があります。その場合は、docker-compose restartコマンドを使用します。このコマンドは、コンテナを停止してから再起動します。

コンテナログの確認

Airflowコンテナのログを確認することで、問題の特定やデバッグが容易になります。コンテナのログを確認するには、docker-compose logsコマンドを使用します。このコマンドは、docker-compose.ymlファイルに定義されたすべてのサービスのログを表示します。

特定のコンテナのログのみを表示する場合は、docker-compose logs <container_name>コマンドを使用します。例えば、docker-compose logs airflowと入力することで、Airflowコンテナのログが表示されます。リアルタイムでログを追跡する場合は、-fオプションを追加します。例えば、docker-compose logs -f airflowと入力することで、Airflowコンテナのログがリアルタイムで表示されます。

エラーが発生した場合、ログを確認することで原因を特定できます。例えば、DAGファイルの構文エラーや、依存関係の欠如などがログに記録されます。ログに記録されたエラーメッセージを参考に、問題を解決してください。

ログは、/opt/airflow/logsディレクトリにも保存されます。このディレクトリには、DAGの実行ログやタスクの実行ログなどが保存されています。これらのログファイルを確認することで、より詳細な情報を得ることができます。

Airflowローカル環境構築のトラブルシューティング

Airflowのローカル環境構築では、UIへのアクセス、DAGファイルの認識、タスクの実行など、さまざまな問題が発生する可能性があります。ここでは、これらの問題に対する具体的なトラブルシューティング方法を解説します。

Airflow UIにアクセスできない場合

Airflow UIにアクセスできない場合、いくつかの原因が考えられます。まず、ポートの競合が発生していないかを確認してください。Airflowが使用するポート(通常は8080番)が、他のアプリケーションによって使用されている可能性があります。その場合は、airflow.cfgファイルでポート番号を変更し、コンテナを再起動してください。

次に、Dockerコンテナが正常に起動しているかを確認します。docker psコマンドを実行し、AirflowのコンテナがRunning状態になっているかを確認してください。もしコンテナが停止している場合は、docker logs <コンテナID>コマンドでログを確認し、エラーの原因を特定します。

また、ネットワーク設定も確認してください。特に、Docker Desktopを使用している場合、コンテナに割り当てられたIPアドレスがホストマシンからアクセス可能であることを確認してください。ファイアウォールがAirflow UIへのアクセスをブロックしていないかも確認が必要です。これらの確認と修正を行うことで、Airflow UIへのアクセス問題を解決できるはずです。

DAGファイルが認識されない場合

DAGファイルがAirflowによって認識されない場合、最も一般的な原因は配置場所の間違いです。Airflowは、設定ファイルで指定されたdags_folder内のDAGファイルを自動的に読み込みます。デフォルトでは、このフォルダは~/airflow/dagsに設定されています。DAGファイルを正しい場所に配置したか確認してください。

次に、Airflowの設定ファイル(airflow.cfg)を確認し、dags_folderの設定が正しいことを確認します。設定が間違っている場合は、正しいパスに修正し、Airflowを再起動してください。

また、DAGファイル自体に構文エラーがないかも確認が必要です。Pythonの構文エラーがあると、AirflowはDAGファイルを読み込むことができません。Airflow UIまたはコンテナのログでエラーメッセージを確認し、DAGファイルの修正を行ってください。

最後に、AirflowのWebサーバーとスケジューラーが正常に動作していることを確認してください。これらのサービスが停止している場合、DAGファイルは認識されません。これらの確認を行うことで、DAGファイルが認識されない問題を解決できるでしょう。

タスクが失敗する場合

Airflowのタスクが失敗する場合、原因を特定するためにまずログを確認することが重要です。Airflow UIからタスクの実行ログを確認し、エラーメッセージやスタックトレースを分析します。ログには、タスクが失敗した原因に関する詳細な情報が含まれているはずです。

次に、タスクが依存する外部サービスやリソースが利用可能であることを確認します。例えば、データベースへの接続が確立されているか、APIエンドポイントが正常に動作しているかなどを確認します。

また、タスクの実行に必要なPythonの依存関係が正しくインストールされているかも確認してください。requirements.txtファイルに記載されたライブラリがすべてインストールされていることを確認し、不足している場合はpip install -r requirements.txtコマンドでインストールします。

さらに、タスクの実行に使用されるAirflowの接続設定(Connections)が正しいことも確認してください。特に、データベースやAPIへの接続情報が誤っていると、タスクは失敗します。これらの確認と修正を行うことで、タスクの失敗問題を解決できるはずです。

問題原因解決策
Airflow UIにアクセスできないポートの競合、Dockerコンテナの停止、
ネットワーク設定の問題、ファイアウォールのブロック
airflow.cfgでポート番号を変更、コンテナを再起動、
docker psでコンテナの状態を確認、
docker logs <コンテナID>でログを確認、
コンテナのIPアドレスがホストマシンからアクセス可能か確認、
ファイアウォール設定を確認
DAGファイルが認識されない配置場所の間違い、airflow.cfgの設定ミス、
DAGファイルの構文エラー、Webサーバーとスケジューラーの停止
DAGファイルをdags_folderに配置、
airflow.cfgdags_folderの設定を確認、
Airflow UIまたはコンテナのログでエラーメッセージを確認し、
DAGファイルを修正、Webサーバーとスケジューラーが正常に動作しているか確認
タスクが失敗するログの確認不足、外部サービスやリソースの利用不可、
Pythonの依存関係の未インストール、
Airflowの接続設定の間違い
Airflow UIからタスクの実行ログを確認、
外部サービスやリソースが利用可能か確認、
requirements.txtに記載されたライブラリがすべてインストールされているか確認、
pip install -r requirements.txtコマンドでインストール、
Airflowの接続設定(Connections)が正しいか確認

Airflowローカル環境の応用

Airflowのローカル環境を構築したら、次はDAG開発と本番環境への移行について見ていきましょう。

ローカル環境でのDAG開発

ローカル環境でのDAG開発は、効率的な開発とテストに不可欠です。DAGファイルのバージョン管理とテスト環境の構築について解説します。

まず、DAGファイルの変更履歴を追跡し、異なるバージョン間での比較やロールバックを容易にするために、バージョン管理システムを導入しましょう。Gitは、DAGファイルのバージョン管理に広く利用されており、変更履歴の追跡や共同開発を支援します。

次に、ローカル環境でDAGをテストするための環境を構築します。これには、Airflow CLIサブコマンドを利用して、DAGの実行コンテキストと同じコンテキストでDAGコードを解析する方法があります。airflow test <DAG_ID> <TASK_ID>コマンドを使用すると、特定のタスクの実行をテストできます。

また、Dockerコンテナ内でAirflowを実行することで、本番環境に近い環境でのテストが可能です。さらに、テストの自動化も重要です。GitHub ActionsやCircleCIなどのCI/CDツールを使用し、DAGコードの変更がプッシュされるたびに自動的にテストを実行するように設定します。

これにより、早期にエラーを発見し、修正することができます。テストには、ユニットテスト、インテグレーションテスト、システムテストなどがあり、これらを組み合わせることで、DAGの品質を確保します。ローカル環境でのテストを徹底することで、本番環境での予期せぬ問題を大幅に削減できます。

本番環境への移行

ローカル環境で十分にテストされたDAGを本番環境へ移行する際には、いくつかの重要な考慮事項があります。環境変数の設定とデータベースの移行について説明します。

まず、本番環境でのみ異なる設定が必要な場合は、環境変数を使用します。これらの変数は、環境ファイル(例:.envファイル)に格納し、Secret ManagerやKubernetes ConfigMapなどの安全な方法で管理することが推奨されます。

これにより、機密情報をコードに直接埋め込むことを避けられます。次に、データベースの移行です。ローカル環境で使用しているデータベース(例:SQLite)を、本番環境に適したデータベース(例:PostgreSQL、MySQL)に移行する必要があります。

これには、データベースのバックアップとリストア、スキーマの変更、データの変換などが含まれる場合があります。Airflowは、データベースの移行をサポートするツールを提供しており、これらを活用することで、移行プロセスを効率化できます。

また、本番環境へのデプロイは、自動化されたCI/CDパイプラインを通じて行うことが推奨されます。これにより、手動でのデプロイによる人的ミスを減らし、迅速かつ一貫性のあるデプロイを実現できます。

Dockerを使用することで、DAGコードと依存関係を統一的な環境で管理し、本番環境への移行を容易にすることができます。本番環境への移行を計画的に行うことで、ダウンタイムを最小限に抑え、スムーズな移行を実現できます。

おわりに

この記事では、Airflowをローカル環境でセットアップし、データパイプラインの構築とテストを効率的に行う方法を解説しました。Dockerを使用することで、環境構築の手間を省き、開発サイクルを短縮できます。

しかし、データ基盤の構築には専門的な知識や経験が必要です。もし、データ基盤構築にお困りでしたら、Hakkyのデータ基盤構築支援サービスをご検討ください。お客様のビジネスに最適なデータ基盤をセキュアかつスピーディーに構築し、データ活用を加速させるお手伝いをいたします。詳細は以下のバナーからご確認ください。

tip
お知らせ

お客様のビジネスに最適なデータ基盤構築を、Hakkyがセキュアかつスピーディーに支援します。データ活用を加速させるための第一歩を、まずはHakkyにご相談ください。


関連記事

参考文献

2025年07月06日に最終更新
読み込み中...