Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
データ接続と統合データ接続エージェントエージェントワーカー設定リファレンス

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

Agent ワーカーの設定リファレンス

レガシー

Agent ワーカーは開発ライフサイクルのレガシー段階にあり、追加の開発は予定されていません。引き続き全面的なサポートを利用できます。新しいソースの構築時や既存のワークフローの更新時には、Foundry ワーカー接続の使用を推奨します。この推奨の運用上の理由については、Foundry ワーカーと Agent ワーカーの比較を参照してください。

このページでは、Agent をワーカーとして使用する際に利用可能な設定オプションを説明します。Data Connection の Agentとその汎用設定オプションをすでに理解していることを前提としています。

既存の Agent ワーカーソースを Foundry ワーカーに移行するには、ソースを Agent ワーカーから Foundry ワーカーに切り替えるを参照してください。

Agent をセットアップする

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

機能の実行

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

ネットワーク

Agent ワーカーソースのネットワーク設定は、すべて Agent ホスト上で行います。Foundry 側のエグレスポリシーは適用されません。Agent ホストには、ソースシステムに直接アクセスできるようにファイアウォール、DNS、プロキシの設定が必要です。詳細なリファレンスについては、Agent のネットワークアクセスを設定するを参照してください。

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

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

Agent のメモリーに関する主要な設定は、次のとおりです。

  • JVM ヒープ： Agent 設定ページで設定し、Agent が起動時に割り当てるメモリー量を指定します。割り当てられたメモリーは OS から予約され、ホストマシンで利用可能なメモリーを超えてはなりません。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 の1つで実行されます。

ジョブは、割り当てられた Agent のうち、利用可能な Agent の1つにランダムに割り当てられます。

最大同時同期数のデフォルトは 16 で、Agent 設定で設定できます。最大同時同期数のクォータは、すべての機能と割り当てられたすべてのソースにわたって適用されます。つまり、どのソースでどの機能を実行しても、利用可能な同時同期クォータを1単位消費します。これには、ストリーミング同期、変更データキャプチャ同期、エクスポート、Webhook、レガシーの Data Connection タスクが含まれます。割り当てられた Agent で、すでに最大数の同期が同時に実行されている場合、新しいジョブは、実行中の機能が十分な数だけ終了するまでキューに入れられます。

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

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

Agent ワーカーでは、バッチ同期のデータを Palantir プラットフォームにアップロードする方法を指定するために、2つの選択肢をサポートしています。

データプロキシモード

データプロキシモードでは、データプロキシサービスを介して公開 Foundry API を使用し、データをアップロードします。この方式では、データセットの読み取りと書き込みに使用する Foundry API 呼び出しを処理するものと同じ API ゲートウェイを利用します。

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

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

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

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

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

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

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

カスタム JDBC ドライバー

Agent にカスタム JDBC ドライバーを追加する手順については、JDBC（カスタム）コネクターのドキュメントを参照してください。

Agent ワーカーで使用するには、ドライバーに Palantir サポートが署名し、Agent に直接追加する必要があります。カスタム JDBC ドライバーの署名について支援が必要な場合は、Palantir サポートにお問い合わせください。

資格情報

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

資格情報を含む Foundry 内のすべてのデータは、保存時も転送時も暗号化されます。データは、アクセスが必要な場所のメモリー内でのみ復号されます。

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

  • ソースに割り当てられた Agent の構成が変わった場合は、Data Connection で資格情報を再入力する必要があります。
  • 新しいダウンロードリンクを使用して Agent を再プロビジョニングした場合、資格情報は自動的に転送されません。既存の Agent から暗号化鍵を復元するか、Data Connection ですべての資格情報を再入力する必要があります。

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

証明書

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

特定のソースシステムに接続するための証明書の追加については、ドキュメントを参照してください。

秘密鍵を追加する

接続先のシステムで相互 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
...

  2. Agent を再起動します。

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

既知の制限事項

Agent ホスト上で機能を直接実行する場合、次のような欠点があります。

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