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 |
---|---|
| The URL of the CData Virtuality SaaS to which the Cloud Agent would initiate web socket connections. The URL format is |
| Contains a comma-separated list of names of all data sources proxied by the agent |
| The host address of the data source being proxied by the Cloud Agent |
| The port number of the data source being proxied by the Cloud Agent |
|
|
|
|
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)
cSYSADMIN_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 クラウドエージェント関連のオプションについてはこちらをご覧ください。