チュートリアル: Azure App Service on Linux と PostgreSQL を使用して Quarkus Web アプリを構築する

[アーティクル]
12/09/2023

このチュートリアルでは、PostgreSQL データベースに接続されている Azure App Service で、セキュリティで保護された Quarkus アプリケーションを構築、構成、デプロイする方法を示します (Azure Database for PostgreSQL を使用)。 Azure App Service は、高いスケーラビリティを備え、パッチを自己適用する Web ホスティングサービスであり、アプリを Windows または Linux に簡単にデプロイできます。このチュートリアルを終了すると、Azure App Service on Linux で実行される Quarkus アプリが完成します。

Screenshot of Quarkus application storing data in PostgreSQL.

このチュートリアルを完了するには、次のものが必要です。

アクティブなサブスクリプションが含まれる Azure アカウント。 Azure アカウントがない場合は、無料で作成できます。
Java と Quarkus 開発に関する知識。

1.サンプルを実行する

便宜上、サンプルリポジトリ Hibernate ORM with Panache と RESTEasy には、開発コンテナー構成が含まれています。開発コンテナーには、データベース、キャッシュ、サンプルアプリケーションに必要なすべての環境変数など、アプリケーションの開発に必要なすべてのものが含まれています。開発コンテナーは、GitHub codespace で実行できます。つまり、Web ブラウザーを使用して任意のコンピューターでサンプルを実行できます。

手順 1: 新しいブラウザーウィンドウ内で次を実行します。

GitHub アカウントにサインインします。
https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app に移動します。
[Fork] を選択します。
[Create fork] (フォークの作成) を選択します。

手順 2: GitHub フォークで、[コード]>[メインに codespace を作成] を選択します。

手順 3: codespace ターミナルで次のことを行います。

mvn quarkus:dev を実行します。
''Your application running on port 8080 is available.'' という通知が表示されたら、[ブラウザーで開く] を選択します。ポート 5005 を含む通知が表示された場合は、スキップします。新しいブラウザータブにサンプルアプリケーションが表示されるはずです。Quarkus 開発サーバーを停止するには、Ctrl+C キーを押します。

Quarkus サンプルアプリケーションの作成方法の詳細については、Quarkus のドキュメント「シンプルになった HIBERNATE ORM WITH PANACHE」と「QUARKUS でデータソースを設定」を参照してください。

2.App Service と PostgreSQL を作成する

まず、Azure リソースを作成します。このチュートリアルで使用する手順では、App Service と Azure Database for PostgreSQL を含む既定でセキュリティで保護された一連のリソースを作成します。作成手順では、次のように指定します。

名前: Web アプリの名前。 Web アプリの DNS 名の一部として https://<app-name>.azurewebsites.net の形式で使われる名前です。
世界でアプリを物理的に実行するためのリージョン。
アプリのランタイムスタック。ここで、アプリに使う Java のバージョンを選びます。
アプリのホスティングプラン。これは、アプリの一連の機能と容量のスケーリングを含む価格レベルです。
アプリのリソースグループ。リソースグループを使うと、アプリケーションに必要なすべての Azure リソースを (論理コンテナーに) グループ化できます。

Azure portal にサインインし、以下の手順に従って Azure App Service リソースを作成します。

手順 1: Azure portal 内で次を実行します。

Azure portal の上部にある検索バーに「Web app database」と入力します。
[Marketplace] の見出しの下にある [Web アプリとデータベース] というラベルの付いた項目を選びます。作成ウィザードに直接移動することもできます。

手順 2:[Web アプリとデータベースの作成] ページ内で、このフォームに次のように入力します。

リソースグループ → [新規作成] を選び、msdocs-quarkus-postgres-tutorial という名前を使用します。
リージョン → 任意の近くの Azure リージョン。
名前 → msdocs-quarkus-postgres-XYZ。ここで、XYZ は任意の 3 つのランダムな文字です。この名前は Azure 全体で一意である必要があります。
ランタイムスタック → Java 17。
Java Web サーバースタック → Java SE (埋め込み Web サーバー)。
データベース → PostgreSQL - フレキシブルサーバー。サーバー名とデータベース名は、既定で適切な値に設定されます。
ホスティングプラン → Basic。準備ができたら、後で運用価格レベルにスケールアップできます。
[Review + create](レビュー + 作成) を選択します。
検証が完了した後、 [作成] を選択します。

手順 3: このデプロイは完了するまでに数分かかります。デプロイが完了したら、[リソースに移動] ボタンを選択します。 App Service アプリに直接移動しますが、次のリソースが作成されます。

リソースグループ → 作成されたすべてのリソースのコンテナーです。
App Service プラン → App Service のコンピューティングリソースを定義します。 Basic レベルの Linux プランが作成されます。
App Service → アプリを表し、App Service プランで実行されます。
仮想ネットワーク → App Service アプリと統合され、バックエンドのネットワークトラフィックを分離します。
Azure Database for PostgreSQL フレキシブルサーバー → 仮想ネットワーク内からのみアクセス可能です。サーバー上にデータベースとユーザーが作成されます。
プライベート DNS ゾーン → 仮想ネットワーク内の PostgreSQL サーバーの DNS 解決を有効にします。

3.接続設定を確認する

作成ウィザードにより、接続変数がアプリの設定として自動的に生成されます。アプリの設定は、接続のシークレットをコードリポジトリに残さないための 1 つの方法です。シークレットをより安全な場所に移動する準備ができたら、代わりに Key Vault 参照を使用できます。

手順 1: [App Service] ページの左側メニューで、[構成] を選択します。

手順 2:[構成] ページの [アプリケーションの設定] タブで、AZURE_POSTGRESQL_CONNECTIONSTRING が存在することを確認します。実行時に環境変数として挿入されます。

手順 4:[構成] ページの [アプリケーションの設定] タブで、[新しいアプリケーション設定] を選びます。設定に PORT という名前を付け、その値を、Quarkus アプリケーションの既定のポートである 8080 に設定します。 [OK] を選択します。

手順 5:[保存] を選びます。

問題がある場合は、「トラブルシューティング」セクションを確認してください。

4.サンプルコードをデプロイする

この手順では、GitHub Actions を使って GitHub のデプロイを構成します。これは、App Service にデプロイする多くの方法の 1 つにすぎませんが、デプロイプロセスで継続的インテグレーションを実現する優れた方法でもあります。既定では、GitHub リポジトリに git push があるたびにビルドとデプロイのアクションが起動されます。

以下に注意します。

デプロイされた Java パッケージは、Uber-Jar である必要があります。
このチュートリアルをわかりやすくするために、デプロイプロセス中はテストを無効にします。 GitHub Actions ランナーは Azure の PostgreSQL データベースにアクセスできないため、Quarkus サンプルアプリケーションの場合など、データベースアクセスを必要とする統合テストは失敗します。

手順 1: [App Service] ページに戻り、左側のメニューで [デプロイセンター] を選択します。

手順 2: [デプロイセンター] ページで次のことを行います。

[ソース] で、[GitHub] を選びます。既定では、ビルドプロバイダーとして GitHub Actions が選ばれます。
GitHub アカウントにサインインし、プロンプトに従って Azure を承認します。
[組織] で、自分のアカウントを選びます。
[リポジトリ] で、[msdocs-quarkus-postgresql-sample-app] を選びます。
[ブランチ] で [main] を選びます。
[認証の種類] で、[ユーザー割り当て ID (プレビュー)] を選択します。
上部のメニューから、[保存] を選択します。 App Service は、選んだ GitHub リポジトリの .github/workflows ディレクトリに、ワークフローファイルをコミットします。

手順 3: サンプルフォークの GitHub codespace に戻り、git pull origin main を実行します。これにより、新しくコミットされたワークフローファイルが codespace にプルされます。

手順 4:

エクスプローラーで src/main/resources/application.properties を開きます。 Quarkus では、Java プロパティを読み込むためにこのファイルが使用されます。
運用プロパティ %prod.quarkus.datasource.jdbc.url=${AZURE_POSTGRESQL_CONNECTIONTRING} を追加します。このプロパティでは、作成ウィザードによって自動的に生成されたアプリ設定に運用データソースの URL が設定されます。

手順 5:

エクスプローラーで .github/workflows/main_msdocs-quarkus-postgres-XYZ.yml を開きます。このファイルは、App Service の作成ウィザードによって作成されました。
Build with Maven ステップの下にある Maven コマンドを mvn clean install -DskipTests -Dquarkus.package.type=uber-jar に変更します。 -DskipTests では、Quarkus プロジェクトのテストがスキップされ、-Dquarkus.package.type=uber-jar で、App Service に必要な Uber-Jar が作成されます。

手順 6:

[ソース管理] 拡張機能を選びます。
テキストボックスに、Configure DB and deployment workflow のようなコミットメッセージを入力します。
[コミット] を選択し、[はい] で確定します。
[変更の同期 2] を選択し、[OK] で確定します。

手順 7: Azure portal 内の [デプロイセンター] ページ内に戻り、次のことを行います。

[ログ] を選択します。新しいデプロイの実行が、コミットされた変更から既に開始されています。
デプロイの実行のログ項目で、最新のタイムスタンプを持つ [ビルドまたはデプロイログ] エントリを選びます。

手順 8: GitHub リポジトリに移動したら、GitHub アクションが実行されていることを確認します。ワークフローファイルでは、ビルドとデプロイという 2 つの異なるステージを定義します。 GitHub が実行されて、[完了] の状態が表示されるまで待ちます。所要時間は約 5 分です。

問題がある場合は、「トラブルシューティング」セクションを確認してください。

5.アプリの参照

手順 1: [App Service] ページ内で、次を実行します。

左側のメニューから [概要] を選びます。
アプリの URL を選びます。直接、https://<app-name>.azurewebsites.net に移動することもできます。

手順 2: リストにいくつかの果物を追加します。おめでとうございます。Azure Database for PostgreSQL へのセキュリティで保護された接続を使用して、Azure App Service で Web アプリを実行できました。

6.診断ログをストリーミングする

Azure App Service では、アプリケーションに関する問題の診断に役立つように、コンソールに出力されたすべてのメッセージが収集されます。サンプルアプリケーションには、以下に示すように、この機能を示す標準の JBoss ログステートメントが含まれています。

private static final Logger LOGGER = Logger.getLogger(FruitEntityResource.class.getName());

@GET
public List<FruitEntity> get() {
    LOGGER.info("In FruitEntityResource.get()");
    return FruitEntity.listAll(Sort.by("name"));
}

手順 1: [App Service] ページ内で、次を実行します。

左側のメニューから、[App Service ログ] を選びます。
[アプリケーションログ記録] で [ファイルシステム] を選びます。
上部のメニューから、[保存] を選択します。

手順 2:左側のメニューから [ログストリーム] を選択します。プラットフォームログとコンテナー内のログを含む、アプリのログが表示されます。

Java アプリのログ記録の詳細については、シリーズの「.NET、Node.js、Python、Java アプリケーション用の Azure Monitor OpenTelemetry を有効にする」を参照してください。

7.リソースをクリーンアップする

完了したら、リソースグループを削除することで、Azure サブスクリプションからすべてのリソースを削除できます。

手順 1: Azure portal の上部にある検索バーで次を行います。

リソースグループ名を入力します。
リソースグループを選択します。

手順 2: [リソースグループ] ページ内で、[リソースグループの削除] を選びます。

ステップ 3:

リソースグループの名前を入力して、削除を確定します。
[削除] を選択します。
もう一度 [削除] を選択して確定します。

トラブルシューティング

エラーログ "ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource] (vert.x-eventloop-thread-0) 要求を処理できませんでした: jakarta.ws.rs.NotFoundException: HTTP 404 見つかりません" が表示されます。

これは、クライアントが不明なパスを要求したことを示す Vert.x エラーです (「QUARKUS リアクティブアーキテクチャ」を参照)。このエラーは、App Service で GET 要求を /robots933456.txt に送信することにより、アプリが起動することが確認されるため、すべてのアプリの起動時に発生します。

アプリの起動に失敗し、ログに次のようなエラーが表示されます。"モデルクラスは既定の永続化ユニット <既定値> に対して定義されていますが、構成されたデータソース <既定値> が見つかりません: 既定の EntityManagerFactory は作成されません"

これは、アプリが Azure データベースに接続できないために発生する可能性が最も高い Quarkus エラーです。アプリ設定 AZURE_POSTGRESQL_CONNECTIONSTRING が変更されていないこと、および application.properties でアプリ設定が正しく使用されていることを確認します。

よく寄せられる質問

この設定にはいくらかかりますか。
仮想ネットワークの背後でセキュリティ保護されている PostgreSQL サーバーに他のツールで接続するにはどうすればよいですか?
GitHub Actions でのローカルアプリの開発はどのように行いますか。
GitHub ワークフロー中に PostgreSQL でテストを実行する場合はどうすればよいですか?

この設定にはいくらかかりますか。

作成したリソースの価格は次のとおりです。

App Service プランは Basic レベルで作成され、スケールアップまたはスケールダウンできます。「App Service の価格」をご覧ください。
PostgreSQL フレキシブルサーバーは、ストレージサイズが最小な、最も低いバースト可能レベルである Standard_B1ms に作成されます。スケールアップまたはダウンすることができます。 Azure Database for PostgreSQL の価格に関するページを参照してください。
仮想ネットワークでは、ピアリングなどの追加機能を構成しない限り、料金は発生しません。「Azure Virtual Network の価格」を参照してください。
プライベート DNS ゾーンでは、少額の料金が発生します。「Azure DNS の価格」を参照してください。

仮想ネットワークの背後でセキュリティ保護されている PostgreSQL サーバーに他のツールで接続するにはどうすればよいですか?

コマンドラインツールからの基本的なアクセスには、アプリの SSH ターミナルから psql を実行できます。
デスクトップツールから接続するには、マシンが仮想ネットワーク内にある必要があります。たとえば、いずれかのサブネット内の Azure VM、または Azure 仮想ネットワークとサイト間 VPN で接続されているオンプレミスネットワーク内のマシンなどです。
また、仮想ネットワークに Azure Cloud Shell を統合することもできます。

GitHub Actions でのローカルアプリの開発はどのように行いますか。

App Service から自動生成されたワークフローファイルを例として使用すると、git push ごとに新しいビルドとデプロイの実行が起動されます。 GitHub リポジトリのローカルクローンから、必要な更新を行い、GitHub にプッシュします。次に例を示します。

git add .
git commit -m "<some-message>"
git push origin main

GitHub ワークフロー中に PostgreSQL でテストを実行する場合はどうすればよいですか?

既定の Quarkus サンプルアプリケーションには、データベース接続を使用したテストが含まれています。接続エラーを回避するために、-skipTests プロパティを追加しました。必要に応じて、PostgreSQL サービスコンテナーに対してテストを実行できます。たとえば、GitHub フォーク内の自動生成されたワークフローファイル (.github/workflows/main_cephalin-quarkus.yml) で、次の変更を行います。

次のスニペットに示すように、PostgreSQL コンテナーの YAML コードを build ジョブに追加します。

...
jobs:
  build:
    runs-on: ubuntu-latest

    # BEGIN CODE ADDITION
    container: ubuntu
    services:
      # Hostname for the PostgreSQL container
      postgresdb:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_USER: postgres
          POSTGRES_DB: postgres
        # Set health checks to wait until postgres has started
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    # END CODE ADDITION

    steps:
      - uses: actions/checkout@v4
      ...

container: ubuntu は、コンテナーで build ジョブを実行するように GitHub に示します。これにより、開発環境の接続文字列 (jdbc:postgresql://postgresdb:5432/postgres) は、ワークフローの実行時にそのまま動作します。 GitHub Actions での PostgreSQL 接続の詳細については、「PostgreSQL サービスコンテナーの作成」を参照してください。

Build with Maven ステップで、-DskipTests を削除します。次に例を示します。

      - name: Build with Maven
        run: mvn clean install -Dquarkus.package.type=uber-jar

次のステップ

App Service での Java アプリの実行の詳細については、開発者ガイドを参照してください。

Azure App Service で Java アプリを構成する

カスタムドメインと証明書を使用してアプリをセキュリティで保護する方法について説明します。

カスタムドメインと証明書を使用してセキュリティで保護する