【解決】Azure WebJobsがポータルに表示されなくてハマった。原因は圧縮方法。

Azure App ServiceでWebJobsにZIPファイルをアップロードしたのに、なぜかポータルにWebJobが表示されない…。設定は正しいはずなのに、スケジュール実行もされず、途方に暮れてました。

原因はZIPファイルを作成する際の「ディレクトリ構造」という、非常に見落としがちなポイントでした。

今回は、Azure WebJobsが認識されないという不可解な現象の根本原因と、そこに至るまでのトラブルシューティングの道のり、そして得られた教訓を詳しく解説していきます。同じ問題で時間を溶かしてしまっている方の助けになれば幸いです。

なぜWebJobが認識されなかったのか？

結論から言うと、Azure WebJobsの仕組みでは、アップロードされたZIPファイルが展開された際に、特定のディレクトリ直下に実行可能ファイルが存在することを期待しているためです。

具体的には、.../triggered/{WebJob名}/ というパスの直下に、run.sh や run.cmd, run.php といったWebJobの実行ファイルが配置されている必要があります。

期待される正しいディレクトリ構造

WebJobsが正常に認識されるためのディレクトリ構造は以下の通りです。

ShellScript
/wwwroot/App_Data/jobs/triggered/{WebJob名}/
|-- run.sh  <-- WebJob名ディレクトリの直下にある
|-- settings.job
|-- (その他の必要なファイル)

問題が発生していた誤ったディレクトリ構造

今回、問題となっていたのは、ZIPファイルを作成する際にプロジェクトフォルダごと圧縮してしまったことで、以下のように余分なディレクトリ階層が一つ挟まっていたケースです。

ShellScript
/wwwroot/App_Data/jobs/triggered/{WebJob名}/
|-- {プロジェクトフォルダ名}/  <-- ★この余分なディレクトリが原因！
|   |-- run.sh
|   |-- (その他の必要なファイル)
|-- __MACOSX/  <-- (macOSで作成した場合の不要なメタデータ)
|-- settings.job

このため、WebJobsの実行環境であるKuduサービスは {WebJob名} ディレクトリの直下で実行ファイルを見つけられず、これを有効なWebJobとして認識できませんでした。これが、ポータルにWebJobが表示されなかった根本的な原因です。

発見までの道のり

この結論にたどり着くまでには、長い試行錯誤の道のりがありました。

始まりは「1つだけの成功」

今回幸いだったのは、実験していた複数のWebJobのうち、1つだけは正常に登録・実行されていたことです。これをヒントに、まずは権限の問題や、そもそも公式サンプル以外のファイルを入れたことが原因ではないかと仮説を立て、様々なパターンで実験を繰り返しました。しかし、状況は一向に改善しませんでした。

「ログ探し」

次に考えたのは、とにかくログを探すことでした。しかし、アプリケーションのログなど、考えられる場所をいくら探しても、エラーログはもちろん、WebJobに関するログが一切出力されていませんでした。「ログが出ていない」という事実が、そもそもWebJobとして認識すらされていないことを示唆していましたが、その時は何をすれいいんだろう・・・というような状況でした。

Kuduで掴んだ解決の糸口

「Kudu（App Serviceのバックエンドを直接操作できるサービス）なら何か分かるかもしれない」と考え、手当たり次第にファイルシステムを調べていきました。

そして、D:\home\site\wwwroot\App_Data\jobs\triggered ディレクトリの中を覗いたとき、ついに原因特定の糸口を発見します。

うまくいっているWebJobのディレクトリでは settings.job と run.sh が同じ階層にいるのに、失敗している他のWebJobではディレクトリ構造が異なっていたのです。この発見が、今回の問題の確信に繋がりました。

最大のハマりポイント：エラーが出ないという罠

この問題をさらに分かりづらくしていたのが、Azureポータルの挙動です。ZIPファイルをアップロードすると、ポータル上では以下のように「WebJob Added」という成功通知が表示されてしまうのです。

このようにエラーが出ないため、アップロード処理自体は成功していると信じ込んでしまいます。まさか内部的に認識されていないとは夢にも思わず、原因の特定に非常に時間がかかりました。

解決策：正しいディレクトリ構造でZIPファイルを作成する

解決策は非常にシンプルです。ZIPファイルを作成する際に、プロジェクトのルートフォルダを丸ごと圧縮するのではなく、そのフォルダの中にあるファイル群を直接選択して圧縮することです。

このようにして作成したZIPファイルをアップロードすれば、Azure側で展開された際に、期待通りのディレクトリ構造になります。

今回の学びと教訓

今回のトラブルシューティングから得られた教訓は、非常に重要なものでした。

  1. ログを丁寧に観察する重要性: 「ログが出ていない」という事実もまた、重要なヒントであると認識すること。権限不足であれば何かしらのエラーログが出力されるはずで、それがないということは、もっと手前の「登録プロセス」に問題があると切り分けるべきでした。
  2. ディレクトリ構造の重要性: 簡単な実験のつもりが、ここまでディレクトリ構造にハマるとは思いませんでした。特にデプロイメントにおいては、ファイルの配置がシステムの挙動を左右することを改めて痛感しました。今後はIaC (Infrastructure as Code) での管理に移行するため、このような手作業でのミスは発生しにくくなるかもしれませんが、この「ディレクトリ構造が非常に大事」という原則は、記憶に刻んでおきたいと思います。

まとめ

Azure WebJobsのZIPデプロイで失敗する主な原因の一つは、ZIPファイル内のディレクトリ構造にあります。そして、ポータル上では成功したように見えてしまうため、問題の発見が遅れがちです。

もし同じ問題で悩んでいたら、一度ご自身のZIPファイルの中身と、Kuduから見たデプロイ後のディレクトリ構造を確認してみてください。

AzureAzure App Service

Posted by takumioda