Cloud Agentは、ファイアウォールで保護されたネットワーク上にデータソースがある場合に便利です。同じネットワークにインストールされると、Cloud Agent はCData Virtuality SaaS へのWeb ソケット接続を開始します。その後、CData Virtuality はWeb ソケット接続をトンネルとして使用し、プライベートネットワーク内の実際のData Sources に接続します。

API Key

CData Virtuality Server に接続する前に、Cloud Agent は有効な API キーを与える必要があります。これはCLOUD_AGENT_CLIENT_API_KEY optionに格納されており、以下の SQL 文を使用して取得できます:

SELECT optionValue FROM "SYSADMIN.OptionValues" WHERE NAME = 'CLOUD_AGENT_CLIENT_API_KEY'

API キーは CData Virtuality Server 起動時に自動的に生成されま す(まだ存在しない場合)。SYSADMIN_VDB.generateCloudAgentApiKey() procedureを使用して新しい値を生成できます。

Example

データ・ソースの作成例を示します:

CALL SYSADMIN.createConnection(name => 'testDatasource', jbossCliTemplateName => 'postgresql', connectionOrResourceAdapterProperties => 'cloudAgent=true,db=test_tables,user-name=postgres,password=Password1!,check-valid-connection-sql="select 1"') ;;
CALL SYSADMIN.createDatasource(name => 'testDatasource', translator => 'postgresql', modelProperties => 'importer.tableTypes="TABLE,VIEW",importer.useFullSchemaName=FALSE,importer.importIndexes=TRUE,importer.schemaPattern=public,importer.defaultSchema=public', translatorProperties => '', encryptedModelProperties => '', encryptedTranslatorProperties => '') ;;

hostおよびport接続プロパティはcloudAgent=TRUEディレクティブに置き換えられ、CData Virtuality Sources にCloud Agent からアクセスされるデータソース接続であることを示します。

サーバ側では、接続オブジェクトがhostをlocalhost、portをランダムなポートとして作成されます。つまり、Postgres ドライバーの観点からは、Cloud Agent のトンネリングは透過的であり、あたかも localhost にある Postgres インスタンスに接続し、ランダムなポートをリッスンしているかのようです。接続が作成されると、ランダムポートを持つサーバーソケットも作成され、接続を待ち受けます。

CData Virtuality Server からの接続がlocalhost サーバーソケットで開始されると、接続を受け入れるソケットが作成され、オープンソケットはCloud Agent サーバーサイドロジックで処理されるキューに入れられます。

データソースに対してCloud Agent接続がある場合、Cloud Agentサーバー側はキューからソケットを取り出し、Cloud Agentを通してソケットから/ソケットへのトラフィックのルーティングを開始します。

データソースに対するCloud Agent接続がない場合、オープンソケットはCloud Agentの接続を待ってしばらくキューに残り、タイムアウト後にクローズされてキューから削除されます。これは、CData Virtuality Server が起動しているが、Cloud Agent への接続がない場合に、接続を受け付けたソケットを閉じることなく、一部のドライバーがサーバーの起動を妨げる応答を無期限に待つ場合にも便利です(これはドライバーがターゲットデータソースに全く到達できない場合とは異なるため、Cloud Agent 接続の場合は常にlocalhostで接続を受け付けますが、Cloud Agent に要求を「転送」する前にソケット上で何も応答しないだけです)。

CLOUD_AGENT_HOST_ADDRESSオプション値は、必要に応じてローカルホスト以外の別のホストを指定するために使用できます。

上記接続のCloud Agent Configurationです:

dvsaas.ws.url=ws://localhost:8080/cloud-agent
client.api.key=f5ba2a5c-5246-4c4d-a05b-2b44790a78d3
 
datasources=testDatasource_VDB_ID_1
 
testDatasource_VDB_ID_1.host=localhost
testDatasource_VDB_ID_1.port=15432

Agent側ではVDB IDも付加します。同じ名前のデータソースがサーバ側の異なるVDBに複数存在する可能性があるためです。

Webサービスデータソースの作成例です:

CALL SYSADMIN.createConnection(name => 'wsDatasource', jbossCliTemplateName => 'ws', connectionOrResourceAdapterProperties => 'cloudAgent=true,cloudAgentWsHost="catfact.ninja"') ;;
CALL SYSADMIN.createDatasource(name => 'wsDatasource', translator => 'ws', modelProperties => '', translatorProperties => '', encryptedModelProperties => '', encryptedTranslatorProperties => '') ;;

と、そのための Cloud Agent Configuration:

dvsaas.ws.url=ws://localhost:8080/cloud-agent
client.api.key=f5ba2a5c-5246-4c4d-a05b-2b44790a78d3
 
datasources=wsDatasource_VDB_ID_1
 
wsDatasource_VDB_ID_1.host=catfact.ninja
wsDatasource_VDB_ID_1.port=443
wsDatasource_VDB_ID_1.useSSL=true

Web service data sources support available since v4.7

Configuration

Configuration ディレクトリには、CData Virtuality SaaS への接続方法と、Cloud Agent によってプロキシされるデータソースに関する情報が含まれています。ディレクトリ内にある.propertiesという拡張子を持つすべてのファイルが読み込まれます。configDirシステムプロパティで明示的に指定されていない場合、プロパティはデフォルトで作業ディレクトリ内のconfigフォルダで検索されます。ディレクトリ内の構成変更は動的に検出され、Cloud Agentを再起動することなく読み込まれます(変更のスキャンは30秒ごとに行われます)。

以下にプロパティファイルの例を示します:

dvsaas.ws.url=ws://localhost:8080/cloud-agent
client.api.key=someApiKey
datasources=someDatasourceName_VDB_ID_1, anotherDatasourceName_VDB_ID_1
 
someDatasourceName_VDB_ID_1.host=localhost
someDatasourceName_VDB_ID_1.port=15432
 
anotherDatasourceName_VDB_ID_1.host=localhost
anotherDatasourceName_VDB_ID_1.port=443
anotherDatasourceName_VDB_ID_1.useSSL=true

Parameter

Description

dvsaas.ws.url

The URL of the CData Virtuality SaaS to which the Cloud Agent would initiate web socket connections. The URL format is ws[s]://host[:port]/cloud-agent, and the wss protocol should be used to initiate web socket connections over HTTPS.

datasources

Contains a comma-separated list of names of all data sources proxied by the agent

<datasource>.host

The host address of the data source being proxied by the Cloud Agent

<datasource>.port

The port number of the data source being proxied by the Cloud Agent

<datasource>.useSSL

TRUE if secured connection should be established between the agent and the data source (default: FALSE)

<datasource>.SSLTrustAll

TRUE if all SSL verifications are disabled for the connection between the agent and the datasource (default: FALSE)

Configuration Updates

  • Cloud Agentは、Configurationフォルダの変更をListenし、変更が検出されると自動的にConfigurationをリフレッシュします。

  • Cloud Agentは、起動時だけでなく変更時にも構成を送信します。

  • CData Virtuality Server はCloud AgentにもConfiguration を送信できます。

  • clientId (ランダムなUUID)は、エージェントインスタンスにまだ存在しない場合、起動時に生成され、エージェントコンフィギュレーションディレクトリの ファイルに格納されます。client_id これは、エージェントのクラスタがある場合に、他のインスタンスと区別できるように、インスタンスを識別するために使用されます。

  • また、設定エラー(無効なデータソース定義など)が発生した場合でも、CData Virtuality SaaS のURL とAPI キーが正しければ、Cloud Agent はCData Virtuality Server に接続するので、(無効な)Configuration を検査し、CData Virtuality Sources のUI を通して修正することができます。

Cloud Agent Web Socket Connection Types

Cloud Agent がCData Virtuality Server との間で確立するWeb ソケット接続には3つの「タイプ」があります:

  • マスターコネクション:CData Virtuality Server への初期接続を確立し、CData Virtuality Server と Agent の設定を交換します。

  • データソース管理接続:CData Virtuality Server が、CData Virtuality Server によって実際のデータソース接続が開始されたときにエージェントに通知するために使用します。

  • データソースの接続:CData Virtuality Server と実際のデータソース間のデータ交換に使用します。

例えば、上記の Data Sources の場合:

  • エージェントは、testDatasource_VDB_ID_1データソースの CData Virtuality Server とのデータソース管理 Web ソケット接続を確立します。

  • CData Virtuality Server はプロキシされたPostgres インスタンスへの接続を確立しようとします。管理コネクションを通じてエージェントへセッション ID を送信します。

  • エージェントは CData Virtuality Sources とのデータソースWeb ソケット接続を確立し、セッションID を提供します。

  • CData Virtuality Server は、その接続を通じて実際のデータソースデータの送信を開始します。

  • エージェントは最初のパッケージを受信し、実際のターゲットデータソースへの接続を OPEN して、実際のデータソースと CData Virtuality Sources の間でパッケージの交換を開始します。

このアーキテクチャでは、1つのWebソケット接続が何らかの理由で過負荷になったり、壊れたり、閉じられたりしても、正常に機能し続ける他の接続には影響しません。

System Procedures

Cloud Agentを使用するための特別なシステム手順がいくつかあります:

  • SYSADMIN_VDB.getCloudAgentConnectionStatus

  • SYSADMIN_VDB.updateCloudAgentConfiguration(IN file string, IN configuration string) c

  • SYSADMIN_VDB.getCloudAgentConfiguration(OUT clientId string NOT NULL, OUT file string NOT NULL, OUT configuration string)

詳細はSYSADMIN_VDB Proceduresをご参照ください。

Logging

デフォルトでは、アプリケーションログは標準出力と、日替わりで作業ディレクトリのlogsフォルダに書き込まれます(最大 30 ログファイル; 現在のログファイルはcloud-agent.logという名前で、古いログファイルにはcloud-agent-2023-11-21.logのように日付が含まれます)。ロギングの動作をカスタマイズするには、以下の Configuration パラメータを指定します:

  • logDirシステムプロパティでLogging フォルダ(すなわち-DlogDir="<path to log directory>")を指定します

  • log4j.configurationFileシステムプロパティでカスタムlog4j 設定ファイル(すなわち-Dlog4j.configurationFile="<path to log4j config file>")を指定し、例えばログレベル、ログフォーマット、ローテーション戦略などを変更します

See Also

Cloud Agent Configuration クラウドエージェント関連のオプションについてはこちらをご覧ください。