deploying-go-sdk-bundles

Go SDK バンドルのデプロイ

Go SDK のデプロイでは、1 つの成果物であるバンドルを使用します。これは、埋め込みソースコードとマニフェスト（AFBNDL01 形式、「実行可能ファイル自体がバンドル」）も含む、自己完結型のネイティブ実行可能ファイルです。go でビルドしてパックし、Airflow の ExecutableCoordinator がスキャンする場所に配置すると、Python タスクランナーがタスクインスタンスごとに 1 回フォークします。このスキルはプラットフォームに依存せず、ビルド、コーディネーターの設定、バンドルをワーカーに配置する方法を説明します。

実験的機能です。 Go SDK は現在も開発中であり、本番環境での使用には対応していません。すべて単一のモジュール github.com/apache/airflow/go-sdk（Go 1.24 以降）に対して解決されます。

作業の順序： タスクを作成する（authoring-go-sdk-tasks）→ バンドルをビルドしてパックする（このスキル）→ executables_root 配下に配置してコーディネーターを設定する → 対応する Python スタブ DAG をデプロイする。

---

バンドルのビルドとパック

コーディネーターが認識するのはパック済みのバンドルだけです。AFBNDL01 のトレーラーをスキャンし、それがないファイルはすべて無視するため、通常の go build で生成したバイナリは、そのままではデプロイできません。go.mod の Go 1.24 tool ディレクティブで提供されるパッカーを使用します（グローバルへのインストールは不要で、バージョンはプロジェクトごとに固定されます）。

go tool airflow-go-pack ./example/bundle                              # build + pack in one step
go tool airflow-go-pack --goos linux --goarch amd64 ./example/bundle -- -trimpath  # cross-compile; flags after -- pass to `go build`
go tool airflow-go-pack --executable ./bin/sample-dag-bundle --source main.go --airflow-metadata <airflow-metadata.yaml> # pack an existing binary
go tool airflow-go-pack inspect ./bin/sample-dag-bundle               # inspect a packed bundle

パッカーはバイナリをビルドし、RegisterDags からマニフェストを取得するために --airflow-metadata を指定して実行した後、ソースコード、マニフェスト、64 バイトのトレーラーを追加します。生成されるのは、実行可能ファイル 1 つです。

• ワーカーの OS／アーキテクチャに合わせてビルドします。 バンドルはネイティブ実行可能ファイルであり、移植性はありません。--goos／--goarch を指定してクロスコンパイルしてください。一致しないバイナリは、ワーカー上で exec format error により失敗します。
• バイナリを変更した場合は、必ず再パックしてください。 ストリップ、再署名、デバッグビルドへの差し替えを行うと、トレーラーの binary_sha256 が無効になり、バンドルは拒否されます。

---

コーディネーターの設定

Python の ExecutableCoordinator は executables_root をスキャンし、受信した dag_id を各バンドルに埋め込まれたマニフェストと照合して、整合性ハッシュを検証した後、バンドルをフォークします。ホスト上では Go プロセスは実行されません。

1. パック済みの実行可能ファイルを、スキャン対象のディレクトリに配置します。

   cp ./bundle /opt/airflow/executable-bundles/   # identified by the AFBNDL01 trailer, not by filename
   

2. ExecutableCoordinator を登録し、キューを割り当てます（configuring-airflow-language-sdks を参照してください）。

   [sdk]
   coordinators = {"go": {"classpath": "airflow.sdk.coordinators.executable.ExecutableCoordinator", "kwargs": {"executables_root": ["/opt/airflow/executable-bundles"]}}}
   queue_to_coordinator = {"golang": "go"}
   

3. 対応する Python スタブ DAG をデプロイします。queue= は queue_to_coordinator のキー（ここでは golang）と一致する必要があります。また、dag_id と task_id も、バンドルで登録したものと一致する必要があります。

---

デプロイ方法

Task SDK を備えた Airflow であれば、どの環境でも SDK を実行できます。Astronomer のツールは必要ありません。

Docker／Kubernetes

バンドルをイメージのプラットフォーム向けにクロスコンパイルし、イメージに組み込みます。イメージに Go ランタイムやワーカープロセスは必要ありません。Python タスクランナーがバンドルをフォークします。

FROM apache/airflow:3.3.0        # the language SDKs target Airflow 3.3+
COPY ./executable-bundles/ /opt/airflow/executable-bundles/
# set AIRFLOW__SDK__COORDINATORS and AIRFLOW__SDK__QUEUE_TO_COORDINATOR as env vars

Helm チャートでは、上記のようにバンドルをカスタムイメージに組み込むか、共有ボリューム経由でマウントします。また、ワーカー／スケジューラーの環境変数で [sdk] 設定を指定します。Docker Compose と Helm のワークフロー全般については、deploying-airflow を参照してください。

上記の apache/airflow:3.3.0 タグは例です。言語 SDK には Airflow 3.3 以降が必要です。記憶を頼りにこのタグをそのままコピーするのではなく、実際に実行する最新の 3.x を固定してください。ベースイメージの最新のタグまたはドキュメントを確認してください。

Astro（選択肢の一つであり、必須ではありません）

1. バンドルをビルドしてパックし、プロジェクトに配置します：mkdir -p include/executable-bundles && cp ../go-bundle/<packed-bundle> include/executable-bundles/。
2. プロジェクトの Dockerfile で、バンドルをコーディネーターのディレクトリにコピーします：COPY include/executable-bundles/ /opt/airflow/executable-bundles/。
3. コーディネーターの設定をプロジェクトの .env に記述します（自動的に読み込まれます）：AIRFLOW__SDK__* の JSON 値（configuring-airflow-language-sdks を参照）。
4. astro dev start を実行します（変更後は astro dev restart）。デプロイには astro deploy を使用します。

Astro Runtime／Airflow のバージョンを記憶だけで固定しないでください。生成された Dockerfile または最新のドキュメントを確認してください。Go SDK がプレビュー段階の間は、ベータ版／開発版のイメージが必要になる場合があります。

---

バージョン管理とプレビュー版のインストール

go-sdk/ は単一の Go モジュールであるため、リリースタグはモノレポのサブディレクトリ形式である go-sdk/vX.Y.Z にします（cmd ごとのタグは作成しないでください）。バンドルモジュールは github.com/apache/airflow/go-sdk に依存します。このバージョンを固定すると、tool ディレクティブで参照されている同じモジュール内のパッケージ airflow-go-pack のバージョンも固定されます。リリースタグを指定してください：

go get github.com/apache/airflow/[email protected]

未リリースのコミットやブランチを使ってビルドする場合（たとえば、次のタグが付く前に修正を試す場合）は、それを直接依存先に指定します。Go が疑似バージョンを生成します：

go get github.com/apache/airflow/go-sdk@<commit-or-branch>

---

デプロイのチェックリスト

• バンドルをビルドしてパックした（go tool airflow-go-pack）。登録した dag_id／task_id が Python のスタブと一致している。
• ワーカーの OS／アーキテクチャ向けにビルドした（例：--goos linux --goarch amd64）。
• パック済みの AFBNDL01 バンドルを、executables_root 配下のディレクトリに配置した。
• ExecutableCoordinator と queue_to_coordinator を設定した（configuring-airflow-language-sdks）。
• Python のスタブ DAG をデプロイし、その queue= を Go コーディネーターにルーティングした。
• 再ビルド／ストリップ／署名の後に再パックした（binary_sha256 が保持されます）。

---

関連スキル

• authoring-go-sdk-tasks：Go のタスクコードと、それに対応する Python のスタブを作成します。
• configuring-airflow-language-sdks：ExecutableCoordinator を登録し、キューをルーティングします。
• deploying-airflow：Airflow の一般的なデプロイ（Astro、Docker Compose、Kubernetes）。
• setting-up-astro-project：Astro プロジェクトを初期化して設定します。