deploying-go-sdk-bundles

Par astronomer · agents

Compile, empaquète et déploie des bundles Go SDK Airflow compilés afin que l'ExecutableCoordinator puisse les exécuter. À utiliser lorsque l'utilisateur souhaite compiler un bundle de tâches Go, pose des questions sur `go build`, `go tool airflow-go-pack`, le bundle exécutable autonome AFBNDL01, l'empaquetage ou l'inspection d'un bundle, son placement sous `executables_root`, la compilation croisée d'un bundle pour les workers, la gestion des versions/tags/pseudo-versions du module `go-sdk`, ou le déploiement du bundle sur un worker Airflow (Docker, Kubernetes ou Astro). Pour le code des tâches, voir authoring-go-sdk-tasks ; pour les paramètres partagés du coordinateur, voir configuring-airflow-language-sdks.

npx skills add https://github.com/astronomer/agents --skill deploying-go-sdk-bundles

Déploiement des bundles Go SDK

Un déploiement Go SDK produit un artifact : un bundle, un unique exécutable natif autonome qui embarque aussi sa source intégrée et un manifest (le format AFBNDL01, « l'exécutable est le bundle »). Vous le construisez et l'empaquetez avec go, le placez où l'ExecutableCoordinator d'Airflow scanne, et le task runner Python le forke une fois par task instance. Cette skill est agnostique de la plateforme : elle montre la construction, le câblage du coordinator, puis comment placer le bundle sur un worker.

Expérimental. Le Go SDK est en développement actif et n'est pas prêt pour la production. Tout se résout contre le module unique github.com/apache/airflow/go-sdk (Go 1.24+).

Ordre des opérations : écrire les tasks (authoring-go-sdk-tasks) -> construire et empaqueter le bundle (cette skill) -> le placer sous executables_root et configurer le coordinator -> déployer le matching Python stub DAG.

Construire et empaqueter le bundle

Le coordinator ne reconnaît qu'un bundle empaqueté : il scanne la trailer AFBNDL01 et ignore silencieusement tout fichier qui ne la possède pas, donc un binaire go build simple n'est pas déployable seul. Utilisez le packer, fourni comme directive tool Go 1.24 dans go.mod (pas d'installation globale, version épinglée par projet) :

go tool airflow-go-pack ./example/bundle                              # build + pack en une étape
go tool airflow-go-pack --goos linux --goarch amd64 ./example/bundle -- -trimpath  # cross-compile; les flags après -- passent à `go build`
go tool airflow-go-pack --executable ./bin/sample-dag-bundle --source main.go --airflow-metadata <airflow-metadata.yaml> # empaqueter un binaire existant
go tool airflow-go-pack inspect ./bin/sample-dag-bundle               # inspecter un bundle empaqueté

Le packer construit le binaire, l'exécute avec --airflow-metadata pour capturer le manifest depuis RegisterDags, puis ajoute la source + le manifest + une trailer de 64 octets. Le résultat est un unique fichier exécutable.

  • Construire pour l'OS/arch du worker. Le bundle est un exécutable natif et n'est pas portable ; cross-compilez avec --goos/--goarch. Un binaire désassorti échoue sur le worker avec exec format error.
  • Ré-empaqueter après tout changement du binaire. Re-stripper, re-signer, ou échanger un debug build invalide le binary_sha256 de la trailer, et le bundle est alors rejeté.

Câbler le coordinator

L'ExecutableCoordinator de Python scanne executables_root, associe le dag_id entrant au manifest intégré de chaque bundle, vérifie son hash d'intégrité, puis forke le bundle. Aucun processus Go ne tourne sur l'hôte.

  1. Placez l'exécutable empaqueté sous un répertoire scanné :

    cp ./bundle /opt/airflow/executable-bundles/   # identifié par la trailer AFBNDL01, pas par le nom de fichier

  2. Enregistrez ExecutableCoordinator et routez la queue vers lui (voir 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. Déployez le matching Python stub DAG ; son queue= doit égaler la clé queue_to_coordinator (golang ici), et ses dag_id/task_ids doivent correspondre à ce que le bundle a enregistré.

Chemins de déploiement

Le SDK s'exécute sur tout Airflow avec le Task SDK ; les outils Astronomer ne sont pas requis.

Docker / Kubernetes

Cross-compilez le bundle pour la plateforme de l'image et intégrez-le. Aucun runtime Go ou worker process n'est nécessaire dans l'image ; le task runner Python forke le bundle.

FROM apache/airflow:3.3.0        # les language SDKs ciblent Airflow 3.3+
COPY ./executable-bundles/ /opt/airflow/executable-bundles/
# définir AIRFLOW__SDK__COORDINATORS et AIRFLOW__SDK__QUEUE_TO_COORDINATOR comme variables d'env

Sur la Helm chart, intégrez le bundle dans une image personnalisée comme ci-dessus ou montez-le via un volume partagé, et définissez la config [sdk] via des variables d'environnement sur le worker/scheduler. Consultez deploying-airflow pour le workflow Docker Compose et Helm plus large.

Le tag apache/airflow:3.3.0 ci-dessus est illustratif : les language SDKs nécessitent Airflow 3.3 ou plus récent. Épinglez la version 3.x actuelle que vous utilisez réellement plutôt que de copier ce tag de mémoire ; lisez les tags ou docs actuels de l'image de base.

Astro (une option, pas obligatoire)

  1. Construisez/empaquetez le bundle, puis stagez-le dans le projet : mkdir -p include/executable-bundles && cp ../go-bundle/<packed-bundle> include/executable-bundles/.
  2. Dans le projet Dockerfile, copiez le bundle dans le répertoire du coordinator : COPY include/executable-bundles/ /opt/airflow/executable-bundles/.
  3. Mettez la config du coordinator dans le projet .env (chargé automatiquement) : les valeurs JSON AIRFLOW__SDK__* (voir configuring-airflow-language-sdks).
  4. astro dev start (ou astro dev restart après modifications) ; déployez avec astro deploy.

N'épinglez pas les versions d'Astro Runtime / Airflow de mémoire ; lisez le Dockerfile généré ou les docs actuels. Pendant que le Go SDK est en preview, une image beta/dev peut être requise.

Versioning et installations preview

go-sdk/ est un unique module Go, donc son release tag prend la forme de sous-dossier monorepo, go-sdk/vX.Y.Z (ne créez pas de tags par cmd). Votre module de bundle dépend de github.com/apache/airflow/go-sdk ; épingler cette version épingle aussi airflow-go-pack, qui est un package dans le même module référencé via la directive tool. Épinglez contre le release tag :

go get github.com/apache/airflow/go-sdk@v1.0.0

Pour construire contre un commit ou une branche non-releasée (par exemple, pour essayer un fix avant le prochain tag), dépendez-en directement et Go fabrique une pseudo-version :

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

Checklist de déploiement

  • Bundle construit et empaqueté (go tool airflow-go-pack) ; les dag_id/task_id enregistrés correspondent aux Python stubs.
  • Construit pour l'OS/arch du worker (par exemple --goos linux --goarch amd64).
  • Bundle AFBNDL01 empaqueté placé sous un répertoire dans executables_root.
  • ExecutableCoordinator + queue_to_coordinator configurés (configuring-airflow-language-sdks).
  • Python stub DAG déployé, son queue= routé vers le Go coordinator.
  • Ré-empaqueté après tout rebuild/strip/sign (préserve le binary_sha256).

Skills connexes

  • authoring-go-sdk-tasks : Écrire le code Go des tasks et les Python stubs correspondants.
  • configuring-airflow-language-sdks : Enregistrer ExecutableCoordinator et router la queue.
  • deploying-airflow : Déploiement général d'Airflow (Astro, Docker Compose, Kubernetes).
  • setting-up-astro-project : Initialiser et configurer un projet Astro.

Skills similaires

configuring-airflow-language-sdks
astronomer / agents

Configurer Airflow pour router les tâches SDK natifs vers le bon coordinateur.

400
deploying-airflow
astronomer / agents

Déployer des DAGs Airflow en production via Astro, Docker Compose ou Kubernetes.

400
managing-astro-local-env
astronomer / agents

Gérer un environnement Airflow local via l'Astro CLI en mode Docker ou standalone.

400
troubleshooting-astro-deployments
astronomer / agents

Diagnostiquer et résoudre les problèmes de déploiements Astronomer en production via l'Astro CLI.

400
managing-astro-deployments
astronomer / agents

Gérer les déploiements Astronomer en production via l'Astro CLI.

400