deploying-go-sdk-bundles

部署 Go SDK Bundle

Go SDK 部署只有一个制品：一个 bundle，即单个自包含的原生可执行文件，其中还包含嵌入的源代码和清单（AFBNDL01 格式，“可执行文件 就是 bundle”）。使用 go 构建并打包，将其放到 Airflow 的 ExecutableCoordinator 扫描的位置，Python 任务运行器会针对每个任务实例启动一次该文件。此技能与平台无关：介绍构建、协调器配置，以及如何将 bundle 部署到工作节点。

实验性。 Go SDK 仍在积极开发中，尚未达到可用于生产环境的状态。所有内容都依赖于单个模块 github.com/apache/airflow/go-sdk（Go 1.24+）。

操作顺序： 编写任务（authoring-go-sdk-tasks）-> 构建并打包 bundle（本技能）-> 将其放到 executables_root 下并配置协调器 -> 部署匹配的 Python 存根 DAG。

---

构建并打包 bundle

协调器只识别已打包的 bundle：它会扫描 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

打包器会构建二进制文件，使用 --airflow-metadata 执行该文件，以从 RegisterDags 获取清单，然后追加源代码、清单和一个 64 字节的尾部标记。最终结果是一个可运行文件。

• 针对工作节点的 OS/架构构建。 bundle 是原生可执行文件，不能跨平台使用；请使用 --goos/--goarch 交叉编译。如果二进制文件不匹配，工作节点上会出现 exec format error。
• 对二进制文件的任何更改后都要重新打包。 重新剥离符号、重新签名或替换为调试版本都会导致尾部标记中的 binary_sha256 失效，随后 bundle 将被拒绝。

---

配置协调器

Python 的 ExecutableCoordinator 会扫描 executables_root，将传入的 dag_id 与各 bundle 中嵌入的清单进行匹配，验证其完整性哈希，然后启动该 bundle。主机上不会运行 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 必须与 bundle 注册的内容一致。

---

部署方式

只要使用 Task SDK，SDK 就能在任何 Airflow 上运行；不需要 Astronomer 工具。

Docker / Kubernetes

针对镜像的平台交叉编译 bundle，并将其打包进镜像。镜像中无需 Go 运行时或工作进程；Python 任务运行器会启动该 bundle。

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 chart，可按上述方式将 bundle 打包进自定义镜像，也可通过共享卷挂载，并通过工作节点/调度器上的环境变量设置 [sdk] 配置。有关更广泛的 Docker Compose 和 Helm 工作流，请参见 deploying-airflow。

上方的 apache/airflow:3.3.0 标签仅作示例：语言 SDK 需要 Airflow 3.3 或更高版本。请固定到你实际运行的当前 3.x 版本，不要凭记忆照抄此标签；请查阅基础镜像当前的标签或文档。

Astro（一种可选方案，并非必需）

1. 构建/打包 bundle，然后将其放入项目中：mkdir -p include/executable-bundles && cp ../go-bundle/<packed-bundle> include/executable-bundles/。
2. 在项目的 Dockerfile 中，将 bundle 复制到协调器目录：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 处于预览阶段期间，可能需要使用 beta/dev 镜像。

---

版本管理与预览版安装

go-sdk/ 是一个 Go 模块，因此它的发布标签采用单体仓库子目录格式 go-sdk/vX.Y.Z（不要为每个 cmd 单独创建标签）。你的 bundle 模块依赖于 github.com/apache/airflow/go-sdk；固定该版本也会固定 airflow-go-pack，它是同一模块中的一个包，通过 tool 指令引用。请使用发布标签固定版本：

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

若要基于尚未发布的提交或分支构建（例如，在下一个标签发布前尝试某项修复），请直接依赖它，Go 会生成一个伪版本：

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

---

部署检查清单

• Bundle 已构建并打包（go tool airflow-go-pack）；已注册的 dag_id/task_id 与 Python 存根一致。
• 针对工作进程的操作系统/架构构建（例如 --goos linux --goarch amd64）。
• 已将打包后的 AFBNDL01 bundle 放在 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 项目。