オンプレミスのセットアップおよびインストールの問題 ​

このガイドでは、オンプレミスエージェント（OPA）のインストール時または初期化時に発生する一般的な問題について説明します。 これらのエラーは、権限の問題、無効な設定ファイル、またはEnvironmentレベルの制限が原因で発生します。

設定ファイルの問題 ​

<INSTALL_HOME>/conf/config.ymlのconfig.ymlファイルは、エージェントがWorkatoに認証および接続する方法を制御します。 このファイルのエラーにより、初回アクティベーション時または後で編集した後にエージェントが起動できなくなります。

config.ymlのコネクション詳細が正しくない ​

config.ymlファイル内の認証エントリが正しくないと、エージェントが起動時に失敗する可能性があります。 認証の詳細が正確であることを確認します。

無効なconfig.yml形式 ​

config.ymlファイルでは、厳密なインデントとスペース指定が必要です。 スペースや改行の位置が誤っていると、YAMLの解析に失敗します。 エージェントを起動する前にオンラインバリデーターを使用して形式を確認し、外部ツールを使用する前に機密情報を削除します。

権限およびアカウントの問題 ​

OPAで、権限不足によるエラーが発生する場合があります。 ほとんどの権限エラーは、アクティベーション中、初回起動時、または権限変更後に発生します。

Windows Certificate Storeへのアクセス ​

Windows証明書ストアを選択した状態でエージェントをアクティベートすると、Certificate not foundエラーが発生する場合があります。 これは通常、証明書ストアにアクセスするための権限が不足していることが原因です。 キーと証明書をファイルシステムに保存するか、権限を更新することで、この問題を解決できます。

キーと証明書をファイルシステムに保存するには、Windowsにオンプレミスエージェントをインストールするガイドを参照してください。

Windowsサービスアカウントの権限 ​

割り当てられたservice accountに必要な権限がない場合、エージェントの起動に失敗することがあります。 この問題を解決するには、より高い権限を持つユーザーを割り当てます。 例として、Windowsでは次のようにします。

詳細については、Windowsにオンプレミスエージェントをインストールするを参照してください。

Linux権限 ​

OPAインストーラーはworkatoシステムユーザーを自動的に作成します。 Workatoは、有効化中の権限エラーを回避するために、このシステムユーザーとしてセットアップコマンドを実行することを強く推奨します。

エージェントのインストール後にworkato system userがまだ存在しない場合は、次の手順を実行して作成します。

sudo groupadd -r workato
sudo useradd --comment "Workato Agent" \
            --no-create-home \
            --home /nonexistent \
            --gid workato \
            --system \
            --shell /usr/sbin/nologin \
            workato

sudo chown -R workato:workato /etc/workato-agent/
sudo chown -R workato:workato /usr/lib/workato-agent/

Unable to create directory [work] to use as the base directoryエラー ​

エージェントにworkディレクトリを作成する権限がない場合、起動時にUnable to create directory [work] to use as the base directoryエラーで失敗することがあります。 この問題は、エージェントが権限の制限されたアカウントで実行されている場合によく発生します。

初期化エラー

このエラーを回避するには、管理者アカウントでエージェントを実行します。 エージェントがサービスとして実行されている場合は、割り当てられたサービスユーザーにインストールパスへのフルアクセス権があることを確認します。

エージェントがログフォルダへのアクセスを失った ​

クリーンアップジョブまたは自動化されたサーバープロセスによって、ログフォルダが削除されることがあります。 このフォルダにアクセスできない場合、エージェントを起動できません。

OPAエラー

アクセスを復元するには、ログフォルダを再作成します。 特定のサーバーアプリケーションまたはルールによって、OPAログフォルダが繰り返し削除される場合があることに注意してください。 この問題が続く場合は、より高い権限を持つアカウントを使用してOPAを再インストールします。

ネットワークおよび証明書の問題 ​

エージェントは、ポート443経由でWorkato gateways（sg3.workato.com、sg4.workato.com）に到達し、SSL証明書チェーンを検証する必要があります。 不適切に設定されたプロキシ、ファイアウォール、SSLインスペクションツール、および中間証明書の欠落により、このコネクションが切断される可能性があります。

Unable to load folder structureエラー ​

オンブレミスファイルコネクターがネットワークフォルダにアクセスしようとしたときに、Unable to load folder structureエラーで失敗することがあります。

このエラーは、OPAホストがターゲットフォルダに安定して接続できない場合に発生します。

問題を解決するには、次の手順を実行します。

PKIX path building failedエラー ​

エージェントの起動時に、ログに次のエラーが表示されることがあります。

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

このエラーは、オンプレミスエージェント（OPA）がターゲットサービスのSSL証明書チェーンを検証できない場合に表示されます。

このエラーは通常、次のいずれかの問題が原因で発生します。

• 中間証明書またはルート証明書が信頼チェーンにありません。
• SSLインスペクションまたはDLPツールによって証明書が変更または置換されています。
• プロキシまたはファイアウォールが、OPAホストとサービスの間のHTTPSトラフィックを傍受しています。

エラーを解決するには、OPA設定に関連するトラブルシューティング手順を実行します。

• エラーが内部サービスに関係している場合は、必要な中間証明書およびルート証明書を信頼します。 証明書は、コネクション設定、config.yml、またはOPAトラストストアに追加できます。

• Environmentにファイアウォール、送信プロキシ、またはDLPツールなどのSSLインスペクションレイヤーが含まれる場合は、Workato gatewaysの例外を作成します。 ゲートウェイコネクションはWorkatoのプライベートCAのみを信頼するため、WorkatoのFQDNに対してSSLインスペクションをバイパスする必要があります。 インスペクションツールのCAをOPAトラストストアに追加しても、ゲートウェイエラーは解決されません。 詳細については、SSL/TLSインスペクションの設定を参照してください。

• プロキシ経由で接続するには、config.ymlファイルのproxy:セクションを設定します。 詳細については、オンプレミスエージェントのプロキシアクセスを設定するガイドを参照してください。

起動失敗のログを確認 ​

エージェントが起動または接続しない場合は、OPAログを確認します。 "agent connected"および"disconnected"のエントリが繰り返し表示される場合、多くの場合、ネットワーク接続が不安定であることを示しています。 Prometheusメトリクスエンドポイント（OPA 32.0以降）を公開して、エージェントのパフォーマンスに関するリアルタイム情報を収集できます。

PKIX path building failedのようなSSLエラーや、com.workato.agent.net.AgentNonRecoverableException: Error connecting to the gateway sg3.workato.com:443 javax.net.ssl.SSLHandshakeException: PKIX path building failedなどの完全な例外は、エージェントがターゲットサービスのSSL証明書チェーンを検証できないことを示しています。 これは、中間証明書またはルート証明書がない場合、SSL検査ツールが証明書を置換または変更する場合、またはプロキシやファイアウォールがOPAホストとサービス間のコネクションを傍受する場合に発生することがあります。

これらのパターンは、問題が設定、権限、またはネットワーク制限のどれに起因するかを確認するのに役立ちます。

インストールのベストプラクティス ​

Workatoでは、エージェントを確実に起動し、中断なく実行するために次のプラクティスを推奨しています。

Workatoのゲートウェイへのアクセスを確認 ​

OPAを実行しているマシンが、ポート443経由でsg3.workato.comおよびsg4.workato.comに到達できることを確認します。 送信HTTPSトラフィックをブロックするファイアウォールまたはプロキシにより、エージェントが接続できなくなる場合があります。 詳細については、OPAがインストールされたサーバーでゲートウェイ名を解決するを参照してください。

一貫した設定管理を使用 ​

プロダクションデプロイメントの前に、テストEnvironmentでconfig.ymlファイルを検証します。 ロールバックと設定追跡のために、検証済みのファイルバージョンを保存します。

エージェントインスタンスを分離 ​

各エージェントを、独自の設定および証明書セットを持つ個別のパスにインストールします。 エージェント間でフォルダやservice accountを共有しないでください。

データ効率を最適化 ​

エージェントを、オンプレミスシステムに最も近いWorkatoデータセンターにデプロイします。 このセットアップにより、レイテンシーが低減され、大容量または高スループットのデータがサポートされます。

認証情報を安全に処理 ​

認証情報を保存するには、シークレットマネージャーを使用します。 認証情報をYAMLファイルに直接埋め込んだり、プレーンテキストで保存したりしないでください。 レガシーYAML設定に依存するセットアップでは、ファイルを保護し、アクセスを制限します。

Windowsインストール ​

OPAサービスのデフォルトアカウントとしてLocal Serviceを使用します。 このアカウントは制限付きアクセスを提供します。 ほとんどのチームは、権限を管理し、必要なリソースへの適切なアクセスを確保するために、ドメイン固有のservice accountを設定します。

Linuxインストール ​

Workatoでは、LinuxにOPAをインストールする際に次のプラクティスを推奨しています。

• サーバーの再起動後に自動再起動を有効にするには、OPAをサービスとして設定します。
• アクティベーション中の権限エラーを回避するには、workato system userとしてセットアップコマンドを実行します。 詳細については、Linux権限セクションを参照してください。