コネクターのデバッグ

問題を迅速かつ効率的に解決するためには、 Satellite Connectorインスタンスを IBM Cloud Logs インスタンスに接続することを強くお勧めします。

コンソールから Satellite コネクター・インスタンスにアクセスします。 Satellite Connector を作成した地域のアカウントに IBM Cloud Logs インスタンスがない場合は、[ Logging for Link] セクションの [Connect] をクリックします。 IBM Cloud Logs インスタンスを作成できる Catalog ページが表示されます。 すでに IBM Cloud Logs インスタンスがある場合は、[ Logging for Link] セクションの [Configure] をクリックします。 次に、既存のロギング・インスタンスを選択します。 Satellite Connector に IBM Cloud Logs インスタンスを接続した後、 Logging for Link セクションを使用して Logging Instance ダッシュボードを開くと、出力が Connector 用にフィルタリングされます。

ロギング・インスタンスで 「プラットフォーム・ログの受信」 が有効になっている必要があります。 このオプションを有効にするには、ロギング・インスタンスのリストから 「オプション」-> 「プラットフォームの編集」 を選択します。

通常、以下の 2 つのタイプのエラーがあります。

  1. トンネルを確立できません。 コンソールの「アクティブ・エージェント」タブにエージェントが表示されません。
  2. トンネルが確立され、アクティブ・エージェントのリストにエージェントが表示されますが、エンドポイントを使用して IBM Cloud からオンプレミス・アプリケーションにアクセスすることはできません。

トンネルを確立できません-エージェントがアクティブ・エージェントのリストに表示されません

トンネルが確立されず、UIの「アクティブなエージェント」タブにあるリストに Satellite コネクタエージェントが表示されません。

コネクター・エージェントが開始してからリストに表示されるまで、約 2 分の遅延があります。

2 分経過してもエージェントが表示されない場合は、以下のデバッグ手順に従ってください。

  1. コネクター ID と領域が正しく指定されていることを確認してください。

  2. ロギング・ダッシュボードを開き、コネクター・ログを確認します。 多くの場合、問題は IAM API キーにあり、以下の例のようなメッセージが表示されます。 詳しくは、 API キーが機能しないのはなぜですか? を参照してください。

    Failed to get configuration from API /v1/connectors/U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaTExMGxpdzFwazluMGdybXUyMCI, region us-east, code: 401. IAM Error: "status code: 400. Provided API key could not be found.", API Error: "null", hostname: "482bddf6c60b"

  3. エージェント・コンテナーのログを確認してください。 IBM Cloud Logs ダッシュボードにエラーがない場合、エージェントがトンネルサーバーと通信する前に問題が発生していることを意味します。 エージェント・コンテナー上のログ・ファイルを参照すると、詳細情報を入手できます。 コマンドは、コンテナー・プラットフォームによって異なります。 Dockerを使用している場合は、以下のコマンドを使用できます。

    docker logs <container id>

  4. 問題が何であるかをログ・メッセージから判別できるはずです。 エラーの最も一般的な理由は、 IBM トンネル・サーバーと通信するためのパブリック・アウトバウンド・アクセスがエージェントにないことです。 IBM Cloudとのトンネルをコネクター・エージェントが確立できない理由 を参照してください。

  5. 正しいコンテナー・ハードウェア・プラットフォームを使用していることを確認してください。 例えば、 arm64 プラットフォームでエージェント・イメージを実行しようとしています。 コネクター・エージェントは、 linux/amd64 プラットフォーム、または amd64をエミュレートできるプラットフォームでのみ実行されます。 この場合、次のようなエラーが表示されます。

    {"msg":"exec container process `/usr/local/bin/node`: Exec format error","level":"error","time":"2023-06-16T14:37:54.000567792Z"}

    Apple Mac のシリコン・ユーザー向けの注: ARM64 プロセッサーを使用する Apple silicon 付き Mac でコネクターを試行する場合、 Rosetta2 がインストールされていると、コンテナー・エージェントが実行されます。 これは通常、 Dockerとともにインストールされます。 コネクター・エージェントを実行すると、以下の警告が表示されます。

    icr.io/ibm/satellite-connector/satellite-connector-agent:v1.0.3 WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 43064456c42434f056348a32773a732d02d4a68690fc6b2b36790be8daa49bb2

    この場合、これは単なる警告であり、コネクター・エージェントは実行中です。 警告が表示されないようにするには、 docker run コマンドで --platform linux/amd64 オプションを指定します。

  6. コンテナー・プラットフォームがイメージをプルできることを確認します。 このイメージは、 IBM Container Registry の icr.io/ibm/satellite-connector/satellite-connector-agent:<version> にあります。 イメージが正しく指定されていることを確認してください。 エージェントを実行しているマシンは、 icr.io にネットワーク・アクセスでき、 IBM Container Registryにログインしています。 詳しくは、 エージェント・イメージのプル を参照してください。

Docker Swarm ユーザーへのメモ:「No such image」に関する以下のエラーが表示される場合:

icr.io/ibm/satellite-connector/satellite-connector-agent:v1.0.4   swarm-worker1   Shutdown    Rejected 5 minutes ago   "No such image: icr.io/ibm/sat…"

これは、 Docker Swarm がイメージをプルできなかったことを意味します。 IBM Container Registry の資格情報が無効であることが原因である可能性があります。 この問題を解決するには:

  1. サービスを削除します。
  2. IBM （ Container Registry ）にログインしてください。
  3. スタックを再始動します。

トンネルが確立されました-コンソールの「アクティブ・エージェント」タブにエージェント・コンテナーがリストされます。

コンソールの「アクティブ・エージェント」タブにエージェント・コンテナーがリストされている場合は、以下のデバッグ手順を実行します。

  1. コネクター・インスタンスに移動し、ロギング・ダッシュボードを開きます。 これにより、コネクター ID のロギング出力が自動的にフィルタリングされます。

  2. エラー・メッセージを確認してください。

    トンネルが確立されると、 IBM Cloud Logs インスタンスとエージェントのコンテナプラットフォームログの両方にエラーが記録される。 ほとんどのエラーは、 IBM Cloud 内から、トンネルを介してオンプレミスで実行されているアプリケーションにアクセスしようとしているエラーです。 エンドポイントにアクセスすると、接続の開始時に flowlog エントリーがロギング・インスタンスに書き込まれます。 以下に例を示します。

    flowlog: start for client 10.249.96.47:1206 connect to postgres.apps.wdc6.toddjohn.net:5432, conn_type: location

    接続がクローズされると、接続に関する詳細を含む別の flowlog エントリーが書き込まれます。 以下に例を示します。

    flowlog: end for client 10.249.96.47:1206 connect to postgres.apps.wdc6.toddjohn.net:5432, conn_type: location, duration 387 ms, BytesToCloud 2444, BytesFromCloud 168

    所要時間は、要求の往復時間ではなく、接続が開いている時間です。

    エンドポイントに接続しようとしてエラーが発生した場合は、エラーの詳細を含む flowlog エントリーが書き込まれます。 以下に例を示します。

    flowlog: error when client 10.249.96.47:1209 connecting to postgres.apps.wdc6.toddjohn.net:5433, conn_type: location, detail: connect ECONNREFUSED 192.168.3.84:5433

  3. 「 flowlog 」のエントリが表示されない場合は、 IBM Cloud アプリケーションがCSEエンドポイントにアクセスできること、および正しいエンドポイントアドレスとポートが使用されていることを確認してください。 たとえば、VPCインスタンスやVPC Kubernetes クラスターを使用している場合、セキュリティグループによってアクセスをブロックすることができます。 VPC から CSE エンドポイント IP およびポートへのトラフィックをセキュリティー・グループが許可していることを確認します。

  4. エンドポイントが正しく構成されていること、およびオンプレミス・アプリケーションが構成済みの宛先 FQDN または IP と宛先ポートで listen していることを確認してください。 オンプレミスのアプリケーションでコンテナを使用している場合、そのIPアドレスが変更される可能性があります。 詳しくは、 IBM Cloudからエンドポイントに到達できないのはなぜですか を参照してください。

  5. 同じコネクターに対して複数のエージェントを実行する場合は、すべてのエージェントがエンドポイントにネットワーク・アクセスできることを確認してください。 各接続要求はランダム・エージェントにルーティングされるため、すべてのエージェントがすべてのオンプレミス・エンドポイントにネットワーク接続する必要があります。 特定のコネクターの個々のエージェントをターゲットにするメカニズムはありません。