mabl Linkの使用方法

ステージングやlocalhostなど、組織内の環境に対してmablクラウドからテストを実行できるようにするには、mabl Linkを使用します。mabl Linkによって、組織内のプライベートネットワークとmablクラウドとの間に、セキュアなトンネルを確立できます。こここで、mabl Linkをセットアップする方法を以下にまとめていきます。

📘

mabl Linkの位置

mabl Link はネットワーク上の永続的なサーバーまたはVMで実行すると最適に機能します。

ステップ1: ワークスペースのAPIキーの取得

mabl Link Agentを使用するには、mabl APIキーが必要です。ワークスペース固有のAPIキーを取得するには、mablアプリケーションで [Settings] > [APIS] の順に選択します。

ステップ2: Link Agentのダウンロードとインストール

Link Agentは、mablクラウドとの間でセキュアトンネルを確立するJavaベースの軽量アプリケーションです。Docker、またはJavaベースの配布パッケージを利用できます。セットアップと保守を簡単に行うことができるため、可能な場合は、Dockerの使用をお勧めします。希望する配布パッケージを取得するには、mablアプリケーションの [Settings] > [NETWORKING] の順に選択します。

ステップ3: Link Agentの実行

Dockerを使用するか、Windows上でエージェントをセットアップする場合は、それぞれDockerまたはWindowsの手順に従い、このステップは省略してください。

📘

Link Agentのシステム要件

Link Agentには、Java 9以降をサポートするJVMが必要です。他の依存関係はありません。Link Agentは、OpenJDKとHotspotの両方のJVMで動作することが確認されています。Linux、Windows、MacOSにはOpenJDK 11をお勧めします。

一部のお客様で問題が発生しているため、JavaのOpenJ9バリアントは使用しないでください。

厳密な最小要件はありませんが、vCPU 1つ以上、RAM 1GB以上、ストレージ2GB以上のマシンをお勧めします。

🚧

Unrecognized option: --add-opens エラーが発生した場合

Link Agentを実行した場合、もし以下のようなエラーがメッセージが発生した場合は、ご利用中のJavaのバージョンが古い、もしくは、正しいJavaのバージョンがPathに設定されていない可能性があります。

Unrecognized option: --add-opens
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

JavaベースのLink Agentを利用する場合は、ワークスペースの [Settings] > [NETWORKING] からアーカイブをダウンロード可能です。

JavaベースのLink Agentのアーカイブをダウンロードした後、テスト対象のアプリケーション環境にアクセスするマシン (ホスト) にそのファイルをコピーし、適切な場所を選んで展開します。試すだけであれば、個人でご利用のコンピューターでもかまいません。

# Extract bzip2 tar:
tar xjf link-agent.tbz2

# Or extract zip:
unzip link-agent.zip

ターミナルからアーカイブを展開します。そして、解凍されてできたLink Agentディレクトリに移動し、Link Agentを実行します。実行するには、Link Agentに次の2つのパラメーターを渡す必要があります。

• --api-key <APIキー>
• --name <ホスト名>

api-keyは、先ほどのステップ1でコピーしたキーです。nameは、このエージェントを識別するために使用する識別子（ホスト名）ですので、各環境にあわせて設定してください。英小文字、数字、ハイフンのみを使用でき、長さは24文字以下です。正規表現の^[a-z0-9-]{1,24}$に一致する必要があります。

エージェントは、生成されたDNS名 (<指定したホスト名>.link.mabl.com) に接続します。<指定したホスト名> の部分は、起動時に渡される--name引数に基づいて生成され、エージェントが同じ名前で起動される限り固定となります。固定ですので、ITセキュリティ部門は、個々のFQDNやワイルドカード*.link.mabl.comをホワイトリストに登録することができます。

有効なLink Agentの起動コマンドの例を示します。

cd link-agent

# Start the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01

# Or you may wish to start the Link Agent in the background
# and keep it running even after you log out:
nohup bin/link-agent --api-key fake-api-key --name qa-env-01 &

cd link-agent

# NOTE: requires using the Java JDK (not JRE)

# Start the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01

# Or you may wish to start the Link Agent in the background
# and keep it running even after you log out:
nohup bin/link-agent --api-key fake-api-key --name qa-env-01 &

cd link-agent

# Start the Link Agent as a foreground process
bin\link-agent.bat --api-key fake-api-key --name qa-env-01

📘

別の設定方法: 設定ファイル

コマンドラインで設定オプションを渡す代わりに、設定ファイルによってLink Agentを設定することもできます。設定ファイルオプションを使用すれば、プロセスのリストにAPIキーが表示されたり、シェル履歴にキーが残ったりするのを避けることができます。また、複数のLink Agentを管理する場合、設定ファイルを使用すれば、起動スクリプトを標準化でき、デプロイするLink Agentインスタンスのそれぞれに対して設定ファイルを変更するだけで済みます。

設定ファイルの使用方法の詳細については、Link Agent設定ファイルドキュメントを参照してください。

HTTP転送プロキシのサポート

基本プロキシ認証のサポートも含め、HTTP転送プロキシを使用するようにLink Agentを設定できます。設定すると、トラフィックはすべてプロキシ経由でルーティングされます。プロキシを設定するには、次のコマンドライン引数を使用します。

• --http-proxy <ホスト>:<ポート> (or -h <host>:<port>)
• --proxy-auth <ユーザー名>:<パスワード> (or -i <ユーザー名>:<パスワード>)
• --proxy-mode <all|none|mabl|upstream> (or -y <all|none|mabl|upstream>)

📘

Proxyモードオプション

--proxy-mode (or -y) フラグを使用すると、設定されたプロキシを介する接続を指定できます。指定できるオプションは以下です。

• all : すべての接続は設定されたプロキシを通して行われます。
• none : プロキシを通さずに接続を行います。
• mabl :mabl内のAPIの呼び出しやセキュアなトンネリング接続のみプロキシを通します。テスト環境への接続などはプロキシを通さずに行います。
• upstream: テスト環境への接続などだけ、設定されたプロキシを通します。mablへの接続はプロキシを使用せずに行われます。

📘

プロキシ除外

特定のホストのみにアクセスするのにプロキシが必要な場合は、プロキシ除外を使用できます。除外を指定する際は、除外式をカンマ区切りで列挙します。除外式には、個別のIPアドレス、CIDR範囲、またはホスト/ドメインを指定できます。ホスト/ドメインの除外式はサフィックスとして扱われます。

たとえば、除外でexample.comを指定した場合、この除外式はwww.example.com、api.example.com、host1.subdomain1.example.comとも一致します。除外のタイプごとの例を以下に示します。

• 個別のIPアドレス: 192.168.10.50
• CIDR範囲: 10.0.0.0/8
• ホスト/ドメイン: example.com
• 実際の指定例は、次のようになります。

--proxy-exclude "localhost,127.0.0.1,192.168.10.50,10.0.0.0/8,example.com"

ステップ4: Link接続の有効性の検証

Link Agentを起動した後 (ステップ3を参照), mabl の画面に戻り、[Settings] > [NETWORKING] の順に選択します。[mabl Link Agents]という見出しの下に、起動したLink Agentのが表示されます。最初はトンネルが初期化中である旨を示すメッセージが次のように表示されます。

Link Agentは、起動後数分で [Connected] ステータスになるはずです。

📘

エージェントの接続に関する問題のトラブルシューティング

リストにLink Agentが表示されない場合、エージェントを起動したホストでエージェントプロセスがまだ実行中であることを確認し、ログファイル (logs/agent.log) でエラーの有無をチェックします。エージェントの起動で問題が発生した場合は、mabl画面下のIntercomチャットか[email protected] からmablのサポートにお問い合わせください。

リストにエージェントが表示されるにもかかわらず、接続されない場合、まず、その名前が、エージェント起動時に指定した名前と一致することを確認します。エージェントが接続されない場合は、数分待ち、接続が確立されるかどうかを確認します。特に、新しいLink Agentを初めて起動する場合は、完全に接続するまで数分かかることがあります。10分待っても接続しない場合は、mablのサポートにお問い合わせください。

ホワイトリストへのmabl Linkの登録

組織のファイアウォールルールが厳しい場合、IT部門に必要な作業は、ポート443の送信 (egrees) トラフィックのホワイトリストに次の2つのエンドポイントを追加することだけです。

• api.mabl.com
• <指定したホスト名>.link.mabl.com

Link Agentは、これら2つのエンドポイントに限り、送信 (egress) 接続を開始します。エージェントの接続先となるDNS名 (<指定したホスト名>.link.mabl.com) は、常に同じ静的IPアドレスに解決されます。そのため、DNS名をホワイトリストに登録したくない場合は、このIPアドレスのみをホワイトリストに登録することもできます。

それぞれ名前の異なる複数のエージェントを使用する予定の場合、各エージェントの各完全修飾ドメイン名 (FQDN) を示すワイルドカードドメイン*.link.mabl.comをホワイトリストに登録することを検討してください。

ステップ5: Link Agentを使用するようにmabl環境を設定

mablの画面で [Configuration] > [Environments] の順に選択し、新しい環境を作成するか、既存の環境を編集します。[Use link agent] チェックボックスを切り替えて、エージェントを無効/有効にします。この設定のドロップダウンメニューにエージェントが表示されるには、エージェントがすでに起動されている必要があります。

🚧

Link Agentと既存の環境との関連付け

Link Agentを環境に関連付けると、その環境に関連する「すべて」のプランのトラフィックが、そのLink Agentを経由してルーティングされます。既存のプランに影響を与えないようにするには、Link Agent用に専用の環境を新しく作成することをお勧めします。すべての環境がプライベートネットワークの場合は、Link Agentを設定するまで、どのプランも正しく実行できません。

ステップ6: Linkを有効にした環境とプランとの関連付け

Link Agent経由でトラフィックをルーティングするには、ステップ5で作成した環境をプランに関連付ける必要があります。mabl UIで新しいプランを作成するか、既存のプランを編集し、ステップ5で作成した環境を選択します。

📘

URLはLink Agentによって解決される

入力するURLは、(mablのネットワーク内ではなく) Link Agentによって解決されます。そのため、Link Agentの実行ホストが解決できるURLであれば、どのURLも使用できます。このURLには、パブリックでないFQDN、プライベートIPアドレス、https://app-local.example.com などの/etc/hostsエントリが含まれます。

ステップ7: Linkでのテストプランの実行

これで、以前のステップで作成したプランを実行できます。プランのテストの実行結果には、mablがアクティブなLink Agentを検索して見つけたことを示す次のようなメッセージが表示されます。

テストの実行が始まる前にLink Agentが起動していない場合、または接続が完了していない場合、次のようなエラーが表示されます。

デプロイイベントでのLink Agent名のオーバーライド

開発者がローカル開発環境でテストを行う必要がある場合など、シナリオによっては、一部のテスト/プランで使用されているLink Agentを一時的にオーバーライドする必要があります。デプロイイベントで新しいLink Agent名を渡すことで、設定済みのLink Agentを動的にオーバーライドすることができます (APIによるテストのトリガーを参照)。デプロイイベントで使用されているLink Agentをオーバーライドするには、次のパラメーターをJSONリクエストボディに追加します。

"plan_overrides":{"link_agent_label":"your-agent-name-here"}