エージェントワーカー

Foundryからの着信ネットワークトラフィックを受け入れられないネットワーク内のシステムに接続するために、中間のエージェントをエージェントワーカーまたはエージェントプロキシとして使用できます。このページでは、エージェントワーカーランタイムの設定オプションについて説明し、データ接続エージェントに既に精通していることを前提としています。

エージェントのセットアップ

エージェントワーカーランタイムを使用するには、エージェントをセットアップする必要があります。ソースを設定する際に、エージェントワーカーオプションを選択し、少なくとも1つの利用可能なエージェントを選択できます。そのソース接続を介して実行される機能は、エージェントワーカーホストでジョブとして実行されます。

機能の実行

エージェントワーカーランタイムを使用する場合、機能はエージェントホストで直接Javaコードを実行することによって実行されます。これらのJavaプロセスは、あなたのシステムからデータを引き出し、Foundryにデータをプッシュすることも（バッチ同期のように）、Foundryからデータを引き出してあなたのシステムにプッシュすることも（エクスポートのように）できます。

この実行モデルにはいくつかの欠点があります。例えば：

• エージェントでのクラスパスの競合の可能性。
  • 特にカスタムJDBCワークフローでは、カスタムJARがFoundryから出荷される依存関係と競合する可能性があります。
• エージェントで実行されるジョブ間の競合。
  • ジョブは任意にエージェントプロセスに割り当てられたメモリとディスクスペースをすべて使用する可能性があり、他のジョブが開始されないかクラッシュする原因となる可能性があります。
  • 特にエージェントワーカーランタイムで実行されるWebフックにとって問題です。このシナリオでは、長時間実行される同期が短時間実行されるWebフックの実行を妨げないように、Webフック実行専用のエージェントを強く推奨します。
• 一部の機能のサポートの欠如。
  • 仮想テーブルや仮想メディアなどの機能は、エージェントワーカーランタイムと互換性がありません。これらはFoundryからの同期接続を必要とし、エージェントでジョブとして実行することができないためです。

メモリ割り当てと使用

エージェントメモリは、エージェントワーカーランタイムを使用して実行される機能のパフォーマンスを決定する主要な要因の1つです。

エージェントメモリに利用可能な主要な設定は次のとおりです：

• JVMヒープ： エージェント設定ページで設定され、エージェントが起動時に割り当てるべきメモリ量を示します。このメモリは、OSの観点からエージェントによって取得され、ホストマシンの利用可能なメモリより少なくなければなりません。デフォルトのJVMヒープ値は1GBです。
• ホストメモリ： エージェントがインストールされているマシンの仕様に基づきます。少なくとも16GBのメモリを推奨します。

ホスト上で観察される実際のメモリ使用量は、エージェントワーカーによって現在実行されているワークロード、ならびに同じホストで実行されている他のプロセスに基づいて変動します。

エージェントをエージェントワーカーとして使用する際のメモリ使用量を観察および監視する際の主な指標は次の2つです：

• OS物理メモリ使用量： エージェントホスト上の実際の総メモリ使用量で、エージェントプロセスだけでなく、同じホストで実行されている他のプロセスも含みます。これはエージェントプロセスの割り当てられたJVMヒープサイズを超えて、利用可能な物理メモリ全体に達する可能性があります。
• エージェントメモリ使用量： エージェントによるメモリ使用量で、常に設定されたJVMヒープサイズより小さくなります。

エージェントのメモリ使用量の監視情報については、エージェントメトリクスと健康監視を参照してください。

負荷分散

エージェントワーカーランタイムを使用する場合、複数のエージェントを単一のソース接続に割り当てることができます。エージェントは、割り当てられたソース接続で設定された特定の機能を実行するジョブを割り当てられます。ジョブは、ジョブの開始時に利用可能なエージェントの1つで実行されます。

ジョブは、利用可能な帯域幅が最も大きいエージェントに割り当てられます。帯域幅は次のように計算されます：

(最大同時同期数) - (現在実行中のバッチ同期数) = 帯域幅

最大同時同期数はデフォルトで16であり、エージェント設定で設定可能です。最大同時同期数のクォータは、すべての機能とすべての割り当てられたソースに対して強制されます。つまり、任意のソースで任意の機能を実行すると、利用可能な同時同期クォータの1ユニットが使用されます。これは、レガシーデータ接続タスクも含まれます。すべての利用可能なエージェントで帯域幅がゼロの場合、または割り当てられたエージェントが正の帯域幅を持っているが、現在実行中の最大同時同期数を超えている場合、ジョブはキューに入れられます。

一般的に、単一のエージェントで正常に実行できるよりも大きなワークロードを負荷分散するために複数のエージェントを使用することは推奨されません。複数のエージェントの主な意図された使用法は、メンテナンスのためにオフラインにされるエージェントを許可することです。最適なパフォーマンスと信頼性を得るために、マルチエージェントセットアップの各エージェントは、割り当てられたソース接続に設定された機能の完全なセットを処理できるようにすることをお勧めします。

直接 vs データプロキシアップロード戦略

エージェントワーカーランタイムは、バッチ同期からのデータをPalantirプラットフォームにアップロードする方法を指定するための2つのオプションをサポートしています：

データプロキシモード

データプロキシモードでは、データはデータプロキシサービスを使用して公開Foundry APIを使用してアップロードされます。これはFoundry APIを呼び出してデータセットを読み書きする際に使用される同じAPIゲートウェイを使用します。

データプロキシモードを使用するように設定されたエージェントは、エージェント構成YAMLに次のように含まれます：

Copied!
1
2
3
4
destinations:
  foundry:
    uploadStrategy:
      type: data-proxy

直接モード [廃止]

直接モードでは、データはFoundryデータカタログの基礎となるストレージバケットに直接アップロードされます。パフォーマンスの向上を提供しますが、Palantirサポートによるカスタムネットワーク構成が必要であり、最新のクラウドインフラストラクチャでは利用できません。

直接モードを使用するように設定されたエージェントは、エージェント構成YAMLに次のように含まれます：

Copied!
1
2
3
4
destinations:
  foundry:
    uploadStrategy:
      type: direct

カスタムJDBCドライバ

エージェントにカスタムJDBCドライバを追加する方法についての情報は、JDBC（カスタム）コネクタのドキュメントにあります。ドライバはPalantirによって署名され、エージェントに直接追加されてエージェントワーカーランタイムで動作します。

エージェントプロキシおよび直接接続ランタイムの場合、カスタムドライバはドキュメントに説明されているようにJDBC（カスタム）コネクタユーザーインターフェイスに直接追加されます。これらのドライバはPalantirによって署名される必要はありません。

資格情報

エージェントワーカーランタイムのユニークな側面の1つは、資格情報がFoundryに保存されないことです。代わりに、データ接続ユーザーインターフェイスで資格情報が入力されるときに、それらはソースに割り当てられた各エージェントの公開鍵で暗号化されます。暗号化された資格情報は、それぞれのエージェントに保存されます。

これにより、エージェントワーカーランタイムを使用する際の資格情報設定に次のような制約と制限が適用されます：

• ソースに割り当てられたエージェントのセットが変更された場合、データ接続で資格情報を再入力する必要があります。
• 新しいダウンロードリンクを使用してエージェントが再プロビジョニングされた場合、資格情報は自動的に転送されず、データ接続で再入力する必要があります。

ディレクトリやホスト間でのエージェントの移動に関する詳細情報は、エージェント構成リファレンスドキュメントに記載されており、既存のエージェントディレクトリを移動する際に暗号化された資格情報を保持するための指示が含まれています。

証明書

エージェントは、Foundryと内部ネットワークの両方と通信します。これにより、エージェントがこれらの接続を確立するために、信頼ストアに正しい証明書を持つ必要があります。

エージェントに追加の証明書を設定する必要がある場合は、次の2つの状況があります：

• エージェントがFoundryと通信するための証明書
• エージェントがシステムと通信するための証明書

エージェントがFoundryと通信するための証明書

エージェントがFoundryと通信するための証明書の要件は、エージェント構成ドキュメントで説明されており、エージェントがエージェントプロキシまたはエージェントワーカーとして使用されるかどうかにかかわらず必要です。

エージェントがシステムと通信するための証明書

エージェントがエージェントワーカーとして使用される場合、エージェントで実行されるJavaプロセスがシステムと正常に通信するために追加の証明書が必要になる場合があります。新しいソース接続ごとに新しい証明書を追加する必要があり、これらの証明書は有効期限が切れたり、回転した場合に更新されるべきです。

必要な証明書が欠けている場合、探索などのソース機能を使用しようとすると、次のようなエラーが表示されます：

Wrapped by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

特定のソースシステムに接続するための追加の証明書を追加するには、これらの指示に従ってください。

エージェントから直接接続へのソースの切り替え

エージェントベースのソースがインターネット経由でアクセス可能なシステムに接続する場合、それを直接接続ランタイムに移行する必要があります。この移行を実行するには、以下の手順に従ってください。

1. 接続設定 > 接続詳細に移動し、クラウド直接接続に切り替えるを選択します。

2. ウォークスルーダイアログの指示に従って移行を開始します。

3. 代表的なエージェントを選択します。これは、必要に応じてソースシークレットとドライバを提供できる健康なエージェントであるべきです。

4. （オプション）ドライバを構成します。

5. 出口ポリシーを追加します。

6. 移行を選択してこのプロセスを完了します。

トラブルシューティング

このセクションでは、移行中に発生する可能性のある状況と、提案される解決手順について説明します。移行は元に戻せます。

Could not resolve type id as a subtype of 'com.palantir.magritte.api.Source'

提案される解決策：

これは、ソースに必要な依存関係が見つからない場合に発生します。特定のソースに必要なすべての証明書、プロキシ、およびドライバが構成されていることを確認し、移行を再試行してください。

UnknownHostException

提案される解決策：

• ソースに正しい出口ポリシーが割り当てられていることを確認します。
• 例外を投げているエンドポイントにFoundryがアクセスできることを確認してください。

Driver class not found

提案される解決策：正しいドライバがJDBCソースにアップロードされていることを確認してください。

PKIX path building failed

提案される解決策：正しい証明書がソースに追加されていることを確認してください。

プライベートキーの追加

接続するシステムが相互TLS（mTLS）を必要とする場合、プライベートキーをエージェントに手動で追加する必要があります。

デフォルトのブートストラップキーストアとトラストストアは、エージェントが再起動されるたびに再生成され、デフォルトのキーストアに加えられた変更は再起動時に上書きされます。以下の手順は、エージェントホスト上の異なる場所にあるカスタムキーストアを指すようにデフォルトのキーストアを上書きする方法と、このカスタムキーストアを変更してプライベートキーを追加する方法を説明します。

1. デフォルトのブートストラップキーストアをコピーし、エージェントホストの別の場所に保存します。以下のコマンドを、ホスト上でエージェントを実行しているのと同じユーザー名で実行してください。フォルダ名をsecurityとするか、お好みに応じて名前を付けてください。

   Copied!
   1
   2
   $ mkdir /home/<username>/security
   $ cp <bootvisor_root>/var/data/processes/<bootstrapper_dir>/var/conf/keyStore.jks  /home/<username>/security/

2. Javaのkeytoolコマンドラインツールを使用して、顧客提供のキーストアからコピーしたエージェントキーストアにキーをインポートします。このツールがまだインストールされていない場合は、エージェントにバンドルされたJDKのbinディレクトリにあります。

   Copied!
   1
   2
   3
   4
   $ keytool -importkeystore -srckeystore <CUSTOM_KEYSTORE.jks> -destkeystore /home/<username>/security/keyStore.jks
   キーストアCUSTOM_KEYSTORE.jksをkeyStore.jksにインポートしています...
   送信先キーストアのパスワードを入力してください: keystore
   ソースキーストアのパスワードを入力してください:

   • keytool -listコマンドを使用して、コピーしたキーストアにキーが追加されたことを確認できます：

     Copied!
     1
     2
     3
     4
     5
     6
     7
     8
     9
     10
     11
     $ keytool -list -keystore /home/<username>/security/keyStore.jks
     キーストアのパスワードを入力してください:
     キーストアの種類: jks
     キーストアプロバイダ: SUN
     
     キーストアには2つのエントリがあります
     
     <CUSTOM_KEY>>, 15-Dec-2022, PrivateKeyEntry,
     証明書フィンガープリント (SHA-256): A5:B5:2F:1B:39:D3:DA:47:8B:6E:6A:DA:72:4B:0B:43:C7:2C:89:CD:0D:9D:03:B2:3F:35:7A:D4:7C:D3:3D:51
     server, 15-Dec-2022, PrivateKeyEntry,
     証明書フィンガープリント (SHA-256): DB:82:66:E8:09:43:30:9D:EF:0A:41:63:72:0C:2A:8D:F0:8A:C1:25:F7:89:B1:A3:6E:6F:C6:C5:2C:17:CB:B2

3. keytool -keypasswdコマンドを使用して、インポートされたキーのパスワードを更新します。エージェントキーストアでは、キーとキーストアのパスワードが一致している必要があります。

   Copied!
   1
   2
   $ keytool -keypasswd -alias <CUSTOM_KEY> -new keystore -keystore /home/<username>/security/keyStore.jks
   キーストアのパスワードを入力してください:

4. データ接続で、エージェントに移動し、エージェント設定タブを開きます。設定の管理セクションで、詳細を選択し、エージェントタブを選択し、新しくコピーしたキーストアを指すようにkeyStoreを更新します。その後、keyStorePasswordを追加し、適切な値（デフォルトではkeystore）に設定します。

   Copied!
   1
   2
   3
   4
   5
   security:
       keyStore: /home/<username>/security/keyStore.jks
       keyStorePassword: keystore
       trustStore: var/conf/trustStore.jks
   ...

5. 最後に、エクスプローラータブを選択し、keyStorePathとkeyStorePasswordの両方を更新します。新しい設定を保存します。

   Copied!
   1
   2
   3
   4
   5
   security:
       keyStorePath: /home/<username>/security/keyStore.jks
       keyStorePassword: keystore
       trustStorePath: var/conf/trustStore.jks
   ...

6. エージェントを再起動します。