Heroku Exec (SSH トンネリング)

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2024年05月28日(火)

はじめに
ポートフォワーディング
SOCKS プロキシ
Java デバッグツールの使用
リモートデバッグ
dyno からのファイルのコピー
Docker での使用
機能の無効化
Private Spaces で事前コンパイルされたデプロイ
制限

Heroku Exec は、dyno に安全な TCP と SSH トンネルを作成するための機能です。SSH セッション、ポートフォワーディング、リモートデバッグ、一般的な Java 診断ツールを使用した検査がサポートされています。

はじめに

Heroku Exec は、次を実行することによって使用できます。

$ heroku ps:exec

Private Spaces アプリで Exec を使用する場合、カスタム buildpack がアプリに自動的に追加されるため、再デプロイが必要です。Common Runtime のアプリの場合、再デプロイは必要ありません。

$ git commit -m "Heroku Exec" --allow-empty
$ git push heroku main

アプリをデプロイしたら、このコマンドを再度実行して Web dyno に接続します。

$ heroku ps:exec
Establishing credentials... done
Connecting to web.1 on ⬢ your-app...
~ $

デフォルトでは、Heroku Exec は web.1 dyno に接続しますが、必要に応じて dyno を指定できます。

$ heroku ps:exec --dyno=web.2
Establishing credentials... done
Connecting to web.2 on ⬢ your-app...
~ $

dyno への接続で問題が発生した場合は、--status フラグを使用して Exec 接続のステータスを確認できます。

$ heroku ps:exec --status
=== limitless-savannah-19617 Heroku Exec status
Dyno   Proxy Status  Dyno Status
─────  ────────────  ───────────
web.1  running       up
web.2  running       up

ポートフォワーディング

対話型ターミナルセッションの作成に加えて、CLI では、ローカルポート上のトラフィックを dyno 内のポートに転送できます。この例で、9090 はローカルポートおよび dyno ポートです。

$ heroku ps:forward 9090
Listening on 9090 and forwarding to web.1:9090...

その後、リクエストを安全なソケット経由で dyno 内のポート 9090 にルーティングするために、リモートデバッガ、プロファイラ、場合によってはブラウザを localhost:9090 に接続します。ポートフォワーディングを停止するには、CTRL+C を使用します。

SOCKS プロキシ

複数のポート上のトラフィックを転送するために、ローカル SOCKS プロキシを使用することもできます。プロキシを起動するには、次のコマンドを実行します。

$ heroku ps:socks

プロキシが実行されたら、dyno 内の任意のポートにアクセスできます。次に例を示します。

$ curl --socks5 localhost:1080 0.0.0.0:12345

Java デバッグツールの使用

Java デバッグツールを使用するには、まず、次のコマンドを実行して Heroku CLI Java プラグインをインストールする必要があります。

$ heroku plugins:install java

その後、次のコマンドをローカルで実行して、dyno への JConsole 接続を開くことができます。

$ heroku java:jconsole

JConsole 接続は、SSH で作成された安全な SOCKS プロキシ経由でルーティングします。これにより、すべてのトラフィックが確実に暗号化されます。ただし、JVM はより下位の暗号化を認識できないため、接続が安全でないことが JConsole によって警告されます。

次のような、さらに Java に関連したコマンドの一覧を取得するには、heroku help java を実行します。

heroku java:visualvm
heroku java:jmap
heroku java:jstack

Heroku Exec が有効になっている場合、デフォルトの JAVA_TOOL_OPTIONS 環境変数は、dyno 内のすべての Java プロセスに対して JMX を有効にするオプションが含まれるように変更されます。このアクションは、次を実行することによって防止できます。

$ heroku config:set HEROKU_DISABLE_JMX=1

このコマンドにより、JMX を必要とする heroku java:visualvm などのコマンドが無効になります。ただし、ps:exec や java:jmap などのその他のコマンドは引き続き動作します。JMX を選択的に有効にしたい場合は、アプリを実行するために使用される java コマンドに $HEROKU_JMX_OPTIONS 環境変数を追加できます。

リモートデバッグ

多くの一般的な IDE は、SSH トンネルを使用したリモートデバッグ機能を提供しています。

いずれの場合も、まず、アプリケーションを設定してリモートデバッグを有効にする必要があります。Node.js の場合は、アプリを起動する node コマンドに --inspect=9090 を追加する必要があります。たとえば、Procfile は次のようになる可能性があります。

web: node --inspect=9090 index.js

Java アプリケーションの場合は、Java Debug Wire Protocol (JDWP) を設定するために -agentlib オプションを指定する必要があります。次に例を示します。

web: java -agentlib:jdwp=transport=dt_socket,server=y,address=9090,suspend=n -jar target/myapp.jar

どちらの場合も、ポート 9090 は任意です。

Procfile を変更し、アプリを再デプロイしたら、Heroku Exec クライアントを使用してポートフォワーディングを開始できます。

$ heroku ps:forward 9090

最後に、IDE またはリモートデバッガを localhost:9090 に接続します。

特定のベンダーについての詳細は、IDE のドキュメントを参照してください。

IntelliJ IDEA や WebStorm を含むほとんどの JetBrains 製品では、Edit Configurations を選択し、新しい Remote 実行設定を作成します。ポート 9090 と localhost を選択します。次に、設定を起動し、ブレークポイントを設定して、アプリケーションを開きます。

dyno からのファイルのコピー

dyno からファイルをコピーするには、dyno ではなくローカルマシンで次のコマンドを実行します。

$ heroku ps:copy filename

このコマンドにより、特定の名前を持つ dyno 内のファイルが、同じ名前を持つローカルファイルにコピーされます。-o オプションを使用すると、ローカルファイルの名前を指定できます。このコマンドは One-off dyno や、heroku run で開始されたプロセスでは使用できません。

Docker での使用

Docker でアプリをパッケージ化し、Container Registry 経由でデプロイしている場合は、Heroku Exec の使用が正式にはサポートされず、追加の設定手順がいくつか必要になります。

Docker イメージに bash、curl、openssh (7.2、7.6、8.x でテスト済み)、ip (Ubuntu 派生イメージの iproute2 パッケージに含まれています)、および、jq または python のどちらかがインストールされていることを確認してください。

次のコードを含む heroku-exec.sh ファイルを作成し、それをイメージの /app/.profile.d ディレクトリに含めます。

[ -z "$SSH_CLIENT" ] && source <(curl --fail --retry 3 -sSL "$HEROKU_EXEC_URL")

WORKDIR は異なる場合があっても、heroku-exec.sh ファイルは /app/.profile.d に存在する必要があります。ファイルを正しいディレクトリに追加する Dockerfile コマンドの例を次に示します。

ADD ./.profile.d /app/.profile.d

最後に、デフォルトのシェルが bash になるように、Dockerfile に次の行を含めます。

RUN rm /bin/sh && ln -s /bin/bash /bin/sh

Private Space で Docker を使用する場合は、.profile.d スクリプトが実行されないため、CMD エントリに heroku-exec.sh スクリプトを追加する必要があります。次に例を示します。

CMD bash heroku-exec.sh && node index.js

機能の無効化

この機能を無効にするには、次のコマンドを実行します。

$ heroku features:disable runtime-heroku-exec

その後、必要に応じて、次のコマンドを実行してアプリ (Private Spaces のみ) から Heroku Exec buildpack を削除します。

$ heroku buildpacks:remove heroku/exec

Private Spaces で事前コンパイルされたデプロイ

Private Space と Heroku Maven プラグインで Heroku Exec を使用するには、pom.xml に次のプラグイン設定を追加しておく必要があります (<buildpacks> セクションに注意)。

<plugin>
  <groupId>com.heroku.sdk</groupId>
  <artifactId>heroku-maven-plugin</artifactId>
  <configuration>
    <buildpacks>
      <buildpack>https://github.com/heroku/exec-buildpack</buildpack>
      <buildpack>heroku/jvm</buildpack>
    </buildpacks>
  </configuration>
</plugin>

次に、mvn heroku:deploy を使用して再デプロイし、heroku ps:exec またはこのドキュメントで説明されている他のコマンドを実行します。

sbt-heroku プラグインでは、build.sbt に次の設定を追加する必要があります。

herokuBuildpacks in Compile := Seq(
    "https://github.com/heroku/exec-buildpack",
    "heroku/jvm"
)

次に、sbt deployHeroku を使用して再デプロイし、heroku ps:exec またはこのドキュメントで説明されている他のコマンドを実行します。

Heroku CLI デプロイプラグインでは、使用するいずれかの war:deploy または jar:deploy コマンドに --buildpacks heroku/exec,heroku/jvm オプションを追加する必要があります。

制限

接続

各 Heroku Exec 接続は最大 1 時間持続します。1 時間後に、再接続が必要になる場合があります。さらに、Heroku Exec は Shield Private Spaces ではサポートされていません。

Heroku Exec は、One-off dyno またはリリースフェーズの dyno では有効になりません。

環境変数

Heroku Exec によって作成された SSH セッションには、環境変数として設定された環境設定がありません (つまり、セッションの env では heroku config:set によって設定された環境設定が一覧表示されません)。

Shield Private Spaces の互換性

Shield Private Spaces で実行されるアプリの高コンプライアンス要件のために、Heroku Exec はサポートされません。

Categories