Astro ローカル環境

このスキルは、Astro CLI を使用してローカルの Airflow 環境を管理するのに役立ちます。

2 つのモード：Docker（デフォルト、コンテナを使用）およびStandalone（Docker 不要、ローカル venv を使用 — Airflow 3 + uv が必須）。

新規プロジェクトのセットアップは、setting-up-astro-project スキルを参照してください。 Airflow が実行中の場合、authoring-dags および testing-dags スキルから MCP ツールを使用します。

---

開始 / 停止 / 再開（Docker）

# ローカル Airflow を開始（webserver at http://localhost:8080）
astro dev start

# コンテナを停止（データは保持）
astro dev stop

# コンテナを強制終了してボリュームを削除（初期状態）
astro dev kill

# すべてのコンテナを再開
astro dev restart

# 特定のコンポーネントを再開
astro dev restart --scheduler
astro dev restart --webserver

デフォルト認証情報： admin / admin

以下を変更した後は再開が必要： requirements.txt, packages.txt, Dockerfile

Standalone モード? 次のセクションを参照してください。

---

Standalone モード

Docker を使わないローカル開発。Airflow を機械上で直接実行し、.venv/ で uv によって管理されます。

要件： Airflow 3（runtime 3.x）、PATH に uv が必要。Windows では非対応。

plain astro dev init は既に runtime 3.x イメージをピンしているため、バージョンフラグは不要です。プロジェクト初期化については setting-up-astro-project を参照してください。

開始

# 1 回限りの設定：standalone をデフォルトモードとして設定
astro config set dev.mode standalone

# または呼び出しごとにフラグを使用
astro dev start --standalone

フラグ	説明
--foreground / -f	フォアグラウンドで出力をストリーミング
--port / -p	webserver ポートをオーバーライド（デフォルト: 8080）
--no-proxy	リバースプロキシを無効化

停止 / 強制終了 / 再開

# 停止（.venv は保持）
astro dev stop

# 強制終了（.venv と .astro/standalone/ を削除 — 初期状態）
astro dev kill

# 再開（.venv を保持して高速再開、-k で先に強制終了）
astro dev restart

開始時に config を設定する代わりに --standalone を使用した場合、以降のすべてのコマンド（stop、kill、restart、bash、run、logs など）でも --standalone を渡します。

状態の場所： venv は .venv/ 内、データベースとログは .astro/standalone/ 内、DAG は dags/ から。

---

リバースプロキシ

複数の Airflow プロジェクトをローカルで実行し、ポート競合を回避します。Docker と standalone の両モードで動作します。

各プロジェクトは <project-name>.localhost:6563 のようなホスト名を取得します。http://localhost:6563 にアクセスすると、すべてのアクティブなプロジェクトが表示されます。

# プロキシステータスとアクティブなルートを確認
astro dev proxy status

# プロキシを強制停止（次の astro dev start で自動再開）
astro dev proxy stop

設定	コマンド
プロキシポートを変更	astro config set proxy.port <port>
開始時に無効化	astro dev start --no-proxy

デフォルトプロキシポート：6563

---

ステータスを確認

astro dev ps

---

ログを表示

# すべてのログ
astro dev logs

# 特定のコンポーネント
astro dev logs --scheduler
astro dev logs --webserver

# リアルタイムで追従
astro dev logs -f

Standalone： astro dev logs は同じですが、統一されたログを表示します（コンポーネント別のフィルタリングはなし）。

---

Airflow CLI コマンドを実行

# Airflow 環境でシェルを開く
astro dev bash

# Airflow CLI コマンドを実行
astro dev run airflow info
astro dev run airflow dags list

Standalone： 同じコマンドが動作します — bash は venv アクティベート済みのシェルを開き、run は venv 内で実行されます。

---

Airflow API にクエリを実行

astro api airflow を使用して、実行中のローカル Airflow インスタンスにクエリを実行します。URL パスではなく operation ID を優先します。

デフォルト： localhost:8080、admin/admin（自動検出）。--api-url、--username、--password で上書きできます。

探索

# すべてのエンドポイントをリスト
astro api airflow ls

# キーワードでフィルタリング
astro api airflow ls dags
astro api airflow ls task

# operation のパラメータとスキーマを表示
astro api airflow describe get_dag

主要フラグ

フラグ	目的
-p key=value	パスパラメータ
-F key=value	body/query フィールド（ブール値/数値を自動変換）
-q / --jq	レスポンスに jq フィルタを適用
--paginate	すべてのページを取得
-X / --method	HTTP メソッドをオーバーライド
--generate	curl コマンドを出力（実行しない）

DAG

# すべての DAG をリスト
astro api airflow get_dags

# パターンでフィルタリング（SQL LIKE — % ワイルドカードを使用）
astro api airflow get_dags -F dag_id_pattern=%etl%

# 特定の DAG を取得
astro api airflow get_dag -p dag_id=my_dag

# 詳細情報を取得（スケジュール、パラメータなど）
astro api airflow get_dag_details -p dag_id=my_dag

# 一時停止 / 再開
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=true
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=false

# DAG ソースコードを表示
astro api airflow get_dag_source -p dag_id=my_dag

# インポートエラーを確認
astro api airflow get_import_errors

DAG ラン

# DAG のランをリスト
astro api airflow get_dag_runs -p dag_id=my_dag

# ランをトリガー
astro api airflow trigger_dag_run -p dag_id=my_dag

# 設定でトリガー
astro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value

# 特定のランを取得
astro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# DAG ランをクリア（再実行）
astro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false

タスクインスタンス

# ランのタスクインスタンスをリスト
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# ~ をワイルドカードとして使用（すべての DAG またはすべてのラン）
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~

# 特定のタスクインスタンスを取得
astro api airflow get_task_instance -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -p task_id=extract

# 失敗したタスクをクリア/再試行
astro api airflow post_clear_task_instances -p dag_id=my_dag \
  -F dag_run_id=manual__2026-04-07 -F only_failed=true -F dry_run=false

# タスクログを取得
astro api airflow get_log -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 \
  -p task_id=extract -p try_number=1

設定とコネクション

astro api airflow get_connections
astro api airflow get_variables
astro api airflow get_config

jq でのフィルタリング

# DAG ID のみをリスト
astro api airflow get_dags -q '.dags[].dag_id'

# ランから失敗したタスク ID を取得
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \
  -q '[.task_instances[] | select(.state=="failed") | .task_id]'

---

トラブルシューティング

問題	解決策
ポート 8080 が使用中	他のコンテナを停止するか、.astro/config.yaml を編集
コンテナが起動しない	astro dev kill その後 astro dev start
パッケージインストール失敗	requirements.txt の構文を確認
DAG が表示されない	astro dev parse を実行してインポートエラーを確認
ディスク容量不足	docker system prune
Standalone が起動しない	uv が PATH に あり、runtime が 3.x であることを確認
プロキシポート競合	astro config set proxy.port <port>
.venv が破損	astro dev kill その後 astro dev start --standalone

環境をリセット

何か壊れた場合：

astro dev kill
astro dev start

---

Airflow をアップグレード

互換性をまず確認

astro dev upgrade-test

バージョンを変更

1. Dockerfile を編集：

   FROM quay.io/astronomer/astro-runtime:13.0.0
   

2. 再開：

   astro dev kill && astro dev start
   

---

関連スキル

• setting-up-astro-project: プロジェクトを初期化し、依存関係を設定
• authoring-dags: DAG を記述（MCP ツールを使用、実行中の Airflow が必須）
• testing-dags: DAG をテスト（MCP ツールを使用、実行中の Airflow が必須）
• deploying-airflow: DAG を本番環境にデプロイ（Astro、Docker Compose、Kubernetes）