AWS Transform Custom向けコミュニティスキル設計：AWS Glue 5.0アップグレード準備

AWS Transform Custom向けコミュニティスキル設計：AWS Glue 5.0アップグレード準備

TL;DR

AWS Glue 2.0、3.0、4.0リポジトリをGlue 5.0用に準備するAWS Transform Customコミュニティスキルを設計しました。安全な機械的変換と人間による証拠を必要とする変更を分離し、移行レポートを生成し、すでに互換性のあるファイルは変更しません。ライブのatxアクセスがなかったため、この投稿のベンチマークは明示的に手動シミュレーションと記載しており、エージェント実行ではありません。この提案はissue #75として公開されており、まだマージされておらず、プルリクエストにもなっていません。

不足しているデータエンジニアリング変換

AWS Transform Customは単一リポジトリ、またはAWS BatchとFargate経由で数千のリポジトリに対してエージェント駆動のコード変換を適用できます。2026年7月30日時点で、パブリックサンプルリポジトリaws-samples/aws-transform-custom-samplesには、EKSバージョンアップグレード準備スキル、JBossからSpring Bootへの移行、Kubernetes準備移行という3つのコミュニティ提供変換が含まれていました。データエンジニアリングには一切触れられていませんでした。

日常業務のほとんどがAWSデータエンジニアリング、Databricks、Delta Lakeにまたがっているため、このギャップは明らかに埋めるべきものでした。

AWS Transform Custom「スキル」の構造

何かを書く前に、既存の最も深い例であるjboss-to-springbootを研究しました。このパターンが他の2つのスキルの実質的な非公式仕様となっているためです：

• README.md — 問題、スキルの機能、atx CLI経由での呼び出し方法。これにはリポジトリが明確な線引きを行う記述もあります：これらは準備変換です。リポジトリのアーティファクト — コードとIaC — を変更しますが、ジョブをデプロイしたり、AWS APIを呼び出して実行中のリソースを変更したり、データレベルの等価性を主張したりしません。この区別は以下すべてを通じて重要です。
• SKILL.md — エージェント向け定義：トリガーキーワード、Objective、明示的なNon-Goals、Constraints、具体的なビフォーアフター例、「ソースコード内の信号 → 参照ファイル」ルーティングテーブル、番号付きValidation / Exit Criteriaチェックリストを含むYAMLフロントマター。
• references/ — 特定の信号が検出された場合にのみエージェントが読み込む、焦点を絞った深掘りファイル。
• BENCHMARKS.md — エグゼクティブサマリーテーブルと文書化された再現可能な方法論。

正確にコピーすべき設計上の選択が2つありました。まず、スキルは条件付きPhase 0を実行し、何か変更する前に実際に適用される移行フェーズを検出します。次に、フラグのみのカテゴリを維持します：エージェントが自動変換してはならないもの — 曖昧な依存関係、カスタムコネクタ、機械的でない動作変更 — は、代わりに人間が判断するためのレポートに記載する必要があります。2つ目の選択は、私が構築した他のどの要素よりも重要でした。

なぜGlue 5.0を特にターゲットにするのか

AWS Glue 5.1は2025年11月に一般提供され、Spark 3.5.6、Python 3.11、Scala 2.12.18、Java 17で動作します。Glue 5.0（Spark 3.5.4、同じPython/Scala/Javaバージョン）は完全にサポートされています。このスキルの初版 — およびすべてのフィクスチャとベンチマーク — をGlue 5.0に限定し、issue #75で提案されているものに一致させました。スキルの構造は5.1へのフォローアップとしてきれいに拡張できます。検証していない主張を含む広範なスキルよりも、実際に実行したベンチマークを持つ狭いスキルをリリースしたいと考えました。

glue-version-upgrade-readinessはAWS Glue ETLジョブ（PySparkおよびScala）とそのIaCを分析し、ソースバージョン2.0、3.0、4.0からGlue 5.0への準備を行います。Phase 0検出フラグで制御され、リポジトリごとに必要な作業のみを実行し、以下をカバーします：

• Spark 2.4/3.1/3.3 → 3.5互換性とモダナイゼーションパターン — registerTempTableなどの非推奨API（Spark 2.0以降非推奨、削除はされていないがランタイムアップグレードと合わせてクリーンアップする価値あり）、レガシーな日時解析フラグ、関連するSQLセマンティクス変更
• Python 3.7/3.10 → 3.11互換性、依存関係ピンバンプを含む
• Glue固有のAPIとログ引数の変更
• コネクタとデータレイク形式の更新 — 新しいGlueバージョンでのネイティブIceberg/Delta/Hudiサポート
• Terraform / CloudFormation / CDKの更新で新しいランタイムをターゲット化

そして、意図的に自動で触れないもの：AWS Marketplaceコネクタ、コンパイル済み/ネイティブ依存関係、クリーンな機械的等価物がないSpark 2.x動作に依存するもの。これらは根拠とともにMIGRATION_REPORT.mdに書き込まれ、サイレント移行はされません。

ライブアクセスなしでのベンチマーク

スキルを検証する本来の方法は、シードされたテストリポジトリに対して実際のatx CLIで実行することです。環境にライブのAWS Transform Customアクセスがなかったため、数字を捏造したり検証を完全にスキップしたりする代わりに、既知の埋め込み非互換性を持つ3つのフィクスチャリポジトリ — PySpark Glue 2.0ジョブ、Scala Glue 3.0ジョブ、Terraform管理のGlue 4.0ジョブ — を用意し、手動でスキルの各フェーズを順に実行し、Python 3.11、Terraform、cfn-lint、sbtという実際のローカルツールで結果を確認しました。

以下のすべての数字は「エージェント実行ではなく手動シミュレーション」と明記されており、そのラベルはパブリックissueに残され、どこでも滑らかに修正されていません：

フィクスチャ	検出された所見	検証された機械的修正	手動レビュー項目	偽陽性	結果
Glue 2.0 PySpark	5/5	4/4	1/1	0	部分的に準備完了
Glue 3.0 Scala	5/5	3/3	2/2	0	コネクタによりブロック
Glue 4.0 Terraform	4/4	3/3	1/1	0	部分的に準備完了
合計	14/14	10/10	4/4	0	3/3のコントロールが変更なし

これらの数字は、フィクスチャに対してスキルの規定フェーズを手動適用した結果を測定したものです。AWS Transform Customの自律実行精度の測定ではありません — そのデータはまだなく、数字が登場するすべての場所でそのことを述べています。

Scalaの結果が最も信頼できる理由は、それがきれいな合格ではないからです。このフィクスチャには意図的に未公開のカスタムコネクタが埋め込まれています。スキルは正しく置き換えを推測することを拒否し、フラグを立て、sbt compileは完全なビルドで実際に失敗します — 一方、変換されたソースコード自体は分離ハーネスでクリーンにコンパイルされます。そこで「準備完了」と報告するスキルは誤った結果だったでしょう。

移行スキルは可能な限り高い合格率を最適化すべきではありません。最も正当な合格率を最適化すべきです。

また、スキルのドキュメントに埋め込まれたすべてのコード例 — Python、Terraform、CloudFormationスニペット — を同じ実際のバリデータで実行し、各フィクスチャのコントロールファイル（SHA-256で前後を検証）も実行しました。

自身の過剰な主張を修正

issueを開く前に、最も確信が持てなかった2つの主張に対して別途ファクトチェックを実行しました：AWSドキュメントが一般的にGlue DynamicFramesを非推奨としているかどうか（していません — Lake Formationの細かいアクセス制御シナリオでのみ）、およびCDKチームが実験的なaws-glue-alphaモジュールの安定性メカニズムとしてcdk synthを規定しているかどうかです。

2つ目は成立しませんでした。CDKはモジュールをexperimentalと文書化し、バージョン間での破壊的変更について警告していますが、合成を安定性保証として具体的に言及しているわけではありません — それは私が要求することにした検証ステップで、当初はAWS自身のガイダンスであるかのように書かれていました。スキルファイル、リファレンスドキュメント、提案全体で文言を修正し、要件が正しく帰属されるようにしました：それはこのスキルの独自の安全ゲートであり、文書化されたCDK推奨ではありません。

これはそれ自体小さな修正ですが、公開前に発見されるか、レビューのメンテナによって発見されるかの違いがあります。自分で発見する方がどちらにせよ良い — 誰かが反論しなければならない主張と、単に検証できる主張の違いです。

現在の状況

これは提案であり、採用された貢献ではありません。完全なスキル、リファレンスドキュメント、3つのベンチマークフィクスチャはローカルで構築・検証済みですが、何もマージされていません — ここにブランチをリンクしていないのは、まだパブリックブランチが存在しないためです。リポジトリのコントリビュートガイドラインでは、重要な作業はプルリクエストの前にissueで議論されることになっているため、まさにその状態です：issue #75で、メンテナのフィードバックを待っています。

AWS Glueを大規模に運用していて、Glue 5.0または5.1移行のエッジケースに遭遇したことがある方は、issueまたはこちらのコメントでお知らせいただければと思います。また、AWS Transform Customを初めて見る方で、community-sourced-transformations/は本当に未開拓の入り口です。現在存在するJavaとKubernetesの例以外にも貢献の余地がたくさんあります。