ローカルデバッグ - リモートライブトラフィック付き
注釈：本資料はAI技術を用いて翻訳されています。
このガイドはRemote Debug機能について説明しています。これはインクラスタトラフィックをローカルマシンにルーティングして、コード変更のたびにイメージを再構築またはアプリを再デプロイすることなく、Extend Appをデバッグできる機能です。一般的なデバッグコンセプト（VS Codeワークフロー、ブレークポイント、ログ読取）については、Extend ローカルデバッグガイドを参照してください。
- Remote Debugを有効化または無効化するとアプリが再起動されます。
- デバッグセッション中にサポートされるのは、ポッドレプリカ1つのみです。
- アプリごとに許可されるのは、アクティブなデバッグセッション1つのみです。
- Remote Debugが有効化されているがセッションが接続されていない場合、インクラスタトラフィックは通常どおりアプリに到達し続けます。トラフィックはアクティブなセッションが開いている間のみローカルマシンにリダイレクトされます。
仕組み
Remote Debugが有効化されると、サイドカーコンテナがExtend Appのポッドに注入されます。サイドカーはすべてのインバウンドトラフィックを透過的にインターセプトし、セキュアなトンネルを通じてローカルマシンに転送します。ローカルアプリがリクエストを処理し、レスポンスは同じトンネルを通じて返信されます。
加えて、CLIはasync-messaging サービス用にローカルTCPリスナーをセットアップするため、ローカルアプリはクラスタ内で実行されているときと同じ方法でイベントをパブリッシュできます。
前提条件
-
extend-helper-cliv0.0.12以上がインストール済み。extend-helper-cli READMEをご参照ください。 -
Extend Appが既にデプロイされており、実行中である必要があります。
-
使用するOAuthクライアントには、以下の権限が必要です:
AGS Private Cloudの場合:
ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ, UPDATE]ADMIN:NAMESPACE:{namespace}:EXTEND:TUNNEL [READ]
AGS Shared Cloudの場合:
- Extend > App Management (Read, Update)
- Extend > TCP Tunneling (Read)
Remote Debugを有効化
Extend Appでリモートデバッグを有効化するには、以下のコマンドを実行します。
extend-helper-cli remote-debug enable --namespace <my-game-namespace> --app <my-extend-app>
アプリが現在実行中の場合、再起動を確認するプロンプトが表示されます。
app "my-extend-app" is currently running and will be restarted to apply the debug mode change. continue? [y/N]:
プロンプトをスキップするには、--confirmを渡します。
extend-helper-cli remote-debug enable --namespace <my-game-namespace> --app <my-extend-app> --confirm
Remote Debugを有効化するとアプリが再起動されます。
Admin Portalからも、Extend Appの設定に移動してデバッグモードを有効にすることで、Remote Debugを有効化できます。
デバッグトンネルに接続
ステップ1 - ローカルアプリを起動
Extend Appをローカルで起動します。標準ポートでリッスンしている必要があります。
- gRPC: ポート
6565 - HTTP: ポート
8000
ローカルアプリが別のポートまたはアドレスでリッスンしている場合、connectコマンドで--local-grpc-portまたは--local-http-portを使用して指定できます。
ステップ2 - 接続
ローカルマシンとインクラスタサイドカーの間にトンネルを開くには、以下のコマンドを実行します。
extend-helper-cli remote-debug connect --namespace <my-game-namespace> --app <my-extend-app>
ローカルアプリが非標準ポートでリッスンしている場合は、明示的に指定します。
extend-helper-cli remote-debug connect --namespace <my-game-namespace> --app <my-extend-app> \
--local-grpc-port localhost:6565 \
--local-http-port localhost:8000
セッションが確立された場合の出力は次のようになります。
INFO[0001] target pod: my-extend-app-xxxxx-xxxxx port: 30001
INFO[0001] connecting to extend app debug sidecar...
INFO[0002] connected to extend app debug sidecar, session established
INFO[0002] starting extend services
デバッグセッション中、このコマンドを実行し続けてください。トンネルが接続されていない場合、インクラスタトラフィックはローカルアプリに到達しません。
トンネルが切れた場合、CLIは自動的に再接続を試みます。セッションを停止するには、Ctrl+Cを押してください。
リアルトラフィックでのデバッグ
ローカルアプリは現在、インクラスタトラフィックを受信しています。通常と同じように、ブレークポイント、ログステートメント、またはIDE デバッグワークフローを使用してください。
async-messaging サービスはlocalhost:7575で使用可能です。これはアプリがクラスタ内で実行されているときに使用するアドレスを反映しています。以下のすべてのシナリオで、ローカルアプリはこのアドレスを使用してasync-messaging イベントをパブリッシュできます。
イベントハンドラー
ローカルアプリプロセスはクラスタ内でパブリッシュされたイベントを受信します。デバッガーを使用してペイロードを検査し、イベント処理ロジックをステップスルーできます。
Service Extension
ローカルアプリプロセスはインクラスタ呼び出し元からの実際のHTTPリクエストを受信します。認証、ルーティング、レスポンスロジックを含むリクエスト処理をエンドツーエンドでデバッグできます。モックデータではなく実際のトラフィックを使用します。
Function Override
ローカルアプリプロセスはクラスタからのgRPCコールを受信します。IDE デバッガーを使用してFunction Overrideロジックをステップスルーできます。
Remote Debugを無効化
デバッグを完了したら、Remote Debugを無効化して通常の動作を復元します。
extend-helper-cli remote-debug disable --namespace <my-game-namespace> --app <my-extend-app>
アプリが現在実行中の場合、再起動を確認するプロンプトが表示されます。
app "my-extend-app" is currently running and will be restarted to apply the debug mode change. continue? [y/N]:
プロンプトをスキップするには、--confirmを渡します。
extend-helper-cli remote-debug disable --namespace <my-game-namespace> --app <my-extend-app> --confirm
Remote Debugを無効化するとアプリが再起動されます。
よくある問題
connectコマンドが「app is not running」エラーで失敗
原因: 接続前にアプリが実行状態である必要があります。
修正: アプリが実行中でない場合は起動するか、起動が完了するまで待ってください。
connectコマンドが「debug mode is not enabled」エラーで失敗
原因: このアプリに対して Remote Debugが有効化されていません。
修正: enableコマンドを使用するか、Admin Portalから Remote Debugを有効化してください。
Remote Debugを有効化を参照してください。
connectコマンドが「debug session is still active」エラーで失敗
症状: connectコマンドがアクティブなセッションについてのエラーで直ちに終了します。
原因: 別のデバッグセッションが既にこのアプリに接続しています。一度に許可されるのはセッション1つのみです。
修正: 前のセッションが正常に切断されなかった場合は、数秒待ってからもう一度試してください。
トンネルは接続するがローカルアプリがトラフィックを受信しない
原因: ローカルアプリが実行中でないか、予期されたのとは別のポートでリッスンしています。
修正: remote-debug connectを実行する前に、ローカルアプリが実行中で正しいポートでリッスンしていることを確認してください。デフォルトポートを変更した場合は、--local-grpc-portまたは--local-http-portを使用して正しいアドレスを渡してください。
アプリが停止中にデバッグモードが有効化または無効化された
原因: アプリが実行中でない場合、設定変更は保存されますが、実行中のポッドにはまだ適用されていません。
修正: アプリをデプロイして変更を適用します。
extend-helper-cli deploy-app --namespace <my-game-namespace> --app <my-extend-app> --image-tag <current-image-tag>