Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
データ接続と統合Data ConnectionレガシードキュメントAgent ワーカーランタイムの設定リファレンス

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

Agent ワーカー

このページは古い内容であり、過去の情報を参照する目的でのみ掲載しています。 最新の実装については、Agent ワーカーのドキュメントページを確認することを推奨します。

Foundry からの受信ネットワークトラフィックを受け入れられないネットワーク内のシステムに接続するには、中継用の Agent を Agent ワーカーまたは Agent プロキシとして使用できます。Agent ワーカーランタイムは、コネクターが Agent プロキシランタイムに対応していない場合にのみ使用してください。このページでは、Agent ワーカーランタイムで利用可能な設定オプションについて説明します。Data Connection の Agent についてすでに理解していることを前提としています。

Agent をセットアップする

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

機能の実行

Agent ワーカーランタイムを使用する場合、機能は Agent ホスト上で Java コードを直接実行することで実行されます。これらの Java プロセスは、システムからデータを取得して Foundry に送信する場合（バッチ同期など）や、Foundry からデータを取得してシステムに送信する場合（エクスポートなど）があります。

この実行モデルには、次のような欠点があります。

  • Agent 上でクラスパスの競合が発生する可能性があります。
    • これは特にカスタム JDBC ワークフローに関係します。カスタム JAR が、Foundry から配布されて Agent のクラスパス上で実行される依存関係と競合する可能性があるためです。
  • Agent 上で実行されるジョブ間でリソースの競合が発生します。
    • ジョブは、Agent プロセスに割り当てられたメモリーとディスク容量をすべて使用してしまうことがあり、その結果、ほかのジョブがいつまでも起動しなかったり、クラッシュしたりする可能性があります。
    • これは、Agent ワーカーランタイムで実行される Webhook にとって特に問題となります。この場合、実行時間の長い同期が実行時間の短い Webhook の実行を妨げないように、Webhook の実行専用の Agent を用意することを強く推奨します。
  • 一部の機能に対応していません。
    • 仮想テーブルや仮想メディアなどの機能は、Agent ワーカーランタイムと互換性がありません。これらの機能は Foundry からの直接の同期接続を必要とし、Agent 上のジョブとして実行できないためです。

メモリーの割り当てと使用量

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

Agent のメモリーに関して利用可能な主要な設定は次のとおりです。

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

ホスト上で観測される実際のメモリー使用量は、Agent ワーカーが現在実行しているワークロードや、同じホスト上で実行されているほかのプロセスによって異なります。

Agent ワーカーとして使用される Agent のメモリー使用量を観測および監視する際には、次の2つの主要なメトリクスがあります。

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

Agent のメモリー使用量の監視については、Agent のメトリクスとヘルス監視を確認してください。

負荷分散

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

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

(Maximum concurrent syncs) - (currently running batch syncs) = bandwidth

最大同時同期数のデフォルトは 16 です。Agent 設定で変更できます。最大同時同期数のクォータは、すべての機能と、割り当てられたすべてのソースを対象に適用されます。つまり、どのソースでどの機能を実行しても、利用可能な同時同期クォータを1単位消費します。これには、レガシーの Data Connection のタスクも含まれます。利用可能なすべての Agent の帯域幅がゼロの場合、または割り当てられた Agent の帯域幅が正の値であっても、現在実行中の同期数が最大同時同期数を超えている場合、ジョブはキューに入れられます。

帯域幅を計算する際に考慮されるのは、バッチ同期のみです。つまり、追加のジョブを割り当てる際には、Agent 上で実行されているほかの機能は無視されます。Agent の主要なワークロードがストリーミング同期、変更データキャプチャ同期、エクスポート、またはほかの機能である場合、複数の Agent を使用する構成でジョブを割り当てる際に、予期しない動作が発生する可能性があります。

帯域幅の値が同じである複数の利用可能な Agent に、ジョブが均等に分散される保証はありません。

一般に、単一の Agent で正常に実行できる大きなワークロードの負荷を分散する手段として、複数の Agent を使用することは推奨しません。複数の Agent を使用する主な目的は、メンテナンスのために Agent をオフラインにできるようにすることです。最適なパフォーマンスと信頼性を確保するため、複数の Agent を使用する構成では、それぞれの Agent が、割り当てられたソース接続に設定されているすべての機能を処理できるようにすることを推奨します。

直接アップロード方式とデータプロキシアップロード方式

Agent ワーカーランタイムには、バッチ同期のデータを Palantir プラットフォームにアップロードする方法を指定するための2つのオプションがあります。

データプロキシモード

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

データプロキシモードを使用するように設定された Agent では、Agent 設定の YAML に次の内容が含まれます。

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

直接モード [サンセット]

直接モードは、新しい Agent や、2024年6月より後にセットアップされたエンロールメントでは利用できません。データプロキシモードがデフォルトであり、新しい Agent で対応している唯一の選択肢です。以前に直接モードを使用するように設定された Agent は、Agent がインストールされているホストのパブリック IP が変更されない限り、引き続きサポートされます。

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

直接モードを使用するように設定された Agent では、Agent 設定の YAML に次の内容が含まれます。

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

カスタム JDBC ドライバー

Agent にカスタム JDBC ドライバーを追加する手順については、JDBC（カスタム）コネクターのドキュメントを参照してください。Agent ワーカーランタイムで動作させるには、ドライバーに Palantir の署名が付与され、Agent に直接追加されている必要があります。

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

資格情報

Agent ワーカーランタイムの特徴の1つは、平文の資格情報が Foundry に保存されないことです。代わりに、Data Connection のユーザーインターフェースで資格情報を入力すると、Foundry に送信される前に、ソースに割り当てられた各 Agent の公開鍵を使ってブラウザー内で暗号化されます。暗号化された資格情報は Foundry に保存され、必要なときに、対応する Agent のみが秘密鍵を使って復号できます。

このため、Agent ワーカーランタイムを使用する場合、資格情報の設定には次の注意事項と制限が適用されます。

  • ソースに割り当てられた Agent が変更された場合は、Data Connection で資格情報を再入力する必要があります。
  • 新しいダウンロードリンクを使って Agent を再プロビジョニングした場合、資格情報は自動的には転送されないため、Data Connection で再入力する必要があります。

ディレクトリ間およびホスト間での Agent の移動について詳しくは、Agent 設定のリファレンスドキュメントを参照してください。既存の Agent ディレクトリを移動するときに、暗号化された資格情報を保持する手順も記載されています。

証明書

Agent は Foundry と内部ネットワークの両方と通信します。このため、これらの接続を確立するには、Agent のトラストストアに正しい証明書が必要です。

Agent に追加の証明書を設定する必要があるのは、次の2つの状況です。

Agent と Foundry の通信を可能にする証明書

Agent が Foundry と通信するための証明書の要件は、Agent 設定のドキュメントに記載されています。これらの証明書は、Agent を Agent プロキシとして使用する場合も、Agent ワーカーとして使用する場合も必要です。

Agent とお使いのシステムの通信を可能にする証明書

Agent を Agent ワーカーとして使用する場合、Agent 上で実行される 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

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

ソースを Agent から直接接続に切り替える

Agent ベースのソースがインターネット経由でアクセス可能なシステムに接続している場合は、直接接続ランタイムに移行する必要があります。次の手順に従って移行します。

  1. 接続設定 > 接続情報に移動し、Direct cloud connectionに変更を選択します。
Direct cloud connectionに変更
  1. ウォークスルーダイアログの指示に従って、移行を開始します。
移行を開始
  1. 代表となる Agent を選択します。必要に応じてソースのシークレットとドライバーを供給できる、正常な Agent を選択する必要があります。
Agent を選択
  1. （任意）ドライバーを設定します。
ドライバーを設定
  1. エグレスポリシーを適用します。
エグレスポリシーを適用

新しいエグレスポリシーを作成するには、Control Panel の「ネットワークエグレス設定の管理」というワークフローへのアクセス権が必要です。このアクセス権は、情報セキュリティ責任者ロールに付与されています。

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

トラブルシューティング

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

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）が必要な場合は、Agent に秘密鍵を手動で追加する必要があります。

デフォルトの Bootstrapper キーストアとトラストストアは、Agent が再起動されるたびに再生成されます。デフォルトのキーストアに加えた変更は、再起動時に上書きされます。以下の手順では、デフォルトのキーストアをオーバーライドして、Agent ホスト上の別の場所にあるカスタムキーストアを参照するように設定する方法と、このカスタムキーストアを変更して秘密鍵を追加する方法を説明します。

  1. デフォルトの Bootstrapper キーストアをコピーし、Agent ホスト上の別の場所に保存します。ホスト上で Agent を実行しているのと同じユーザー名で、次のコマンドを実行します。フォルダーには 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 コマンドラインツールを使って、顧客が提供したキーストアから、コピーした Agent キーストアに鍵をインポートします。このツールがまだインストールされていない場合は、Agent に同梱されている JDK の bin ディレクトリで見つけることができます。

    Copied!
    1
2
3
4
$ keytool -importkeystore -srckeystore <CUSTOM_KEYSTORE.jks> -destkeystore /home/<username>/security/keyStore.jks
Importing keystore CUSTOM_KEYSTORE.jks to keyStore.jks...
Enter destination keystore password: keystore
Enter source keystore password:

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

      Copied!
      1
2
3
4
5
6
7
8
9
10
11
$ keytool -list -keystore /home/<username>/security/keyStore.jks
Enter keystore password:
Keystore type: jks
Keystore provider: SUN

Your keystore contains 2 entries

<CUSTOM_KEY>>, 15-Dec-2022, PrivateKeyEntry,
Certificate fingerprint (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,
Certificate fingerprint (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 コマンドを使って、インポートした鍵のパスワードを更新します。Agent キーストアでは、鍵とキーストアのパスワードが一致している必要があります。

    Copied!
    1
2
$ keytool -keypasswd -alias <CUSTOM_KEY> -new keystore -keystore /home/<username>/security/keyStore.jks
Enter keystore password:

  4. Data Connection で Agent に移動し、Agent 設定タブを開きます。設定の管理セクションで詳細を選択し、Agent タブを選択して、keyStore を更新し、新しくコピーしたキーストアを参照するようにします。次に、keyStorePassword を追加して、適切な値（デフォルトでは keystore）に設定します。

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

Agent キーストアの詳細設定

  1. 最後に、Explorer タブを選択し、keyStorePath と keyStorePassword の両方を更新します。キーストアのパス項目は、Agent タブでは keyStore、Explorer タブでは keyStorePath という名前です。新しい設定を保存します。

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

    Bootstrapper の設定を変更する必要はありません。

  2. Agent を再起動します。