IBM Cloud Docs
コネクター・エージェントの実行

コネクター・エージェントの実行

Satellite コネクタを作成した 後、次の手順を実行してエージェントを作成し、セットアップを確定します。

前提条件

エージェント・パラメーターの確認

構成情報は、以下の環境変数を介してエージェントに提供されます。 これらの環境変数は、値に直接設定することも、値を含むファイルのパスに設定することもできます。 パス値は、コンテナー内からアクセス可能でなければならないため、ホスト上のローカル・パスではなく、マウント・ポイントに基づいています。 例として以下の表をご覧ください。

設定のための環境変数
環境変数 必須 説明
SATELLITE_CONNECTOR_ID ある エージェントがバインドされている Satellite ・コネクターの ID。 コネクター ID は、 Satellite コンソール で確認することも、 ibmcloud sat connector ls コマンドを実行して確認することもできます。
SATELLITE_CONNECTOR_IAM_APIKEY ある IAM API キー。 セキュリティー上の理由から、IAM API キーをファイルに保管してから、この値にファイルを指定することを検討してください。 注: Windows 環境では、ファイル・パス内のスラッシュをエスケープする必要があります。
SATELLITE_CONNECTOR_TAGS いいえ エージェントを識別するのに役立つユーザー定義の文字列。 このストリングは、役立つと思われる任意の値にすることができます。 値は 256 文字以下でなければならず、256 文字を超える場合は切り捨てられます。 <>/{}%[]?,;@$&.
SATELLITE_CONNECTOR_DIRECT_LINK_INGRESS いいえ Satellite Tunnel Ingress サーバーがエージェントのトラフィックを誘導する。 内部Ingressを指定すると、エージェントとトンネルサーバー間のすべてのトラフィックがプライベートネットワーク内に留まるようになります。
LOG_LEVEL いいえ エージェントについて受け取るロギング詳細のレベルを設定します。 fatal、 error、 warn、 debug、 info、または trace のいずれかを指定できます。 デフォルトのレベルは info。 通常、 debug および trace レベルはデバッグ時にのみ使用されます。
PRETTY_LOG いいえ Windows環境のみ。 きれいな形式でログを表示するには「true、JSON形式でログを表示するには「false 指定する。

コンテナー・プラットフォームでのエージェントの実行

作業を始める前に、最低限必要な条件 を確認してください。

ステップ 1: ローカル構成ファイルの作成

エージェント構成環境変数情報をコンテナーに渡すには、いくつかの方法があります。 以下の例では、構成ファイルを使用しています。 ただし、 docker run --env コマンドを使用して値を指定することもできます。

API キーとともに --env を使用すると、API キーがコンテナー環境に公開され、 docker inspect コマンドの出力に表示されることに注意してください。 ファイル内の API キーを保護してから、そのファイル名を環境変数で使用することができます。 ファイル名を使用することを選択する場合は、以下の例に示すように、環境変数に指定するファイル・パスがコンテナー内のファイル・パスにマウントされていることを確認する必要があります。

以下のステップに示すファイル名は例であり、ご使用の環境に合わせて調整できます。

  1. 構成ファイル用のディレクトリー (この例では ~/agent/env-files) を作成します。

  2. ~/agent/env-files ディレクトリーに apikey というファイルを作成します。このファイルには、 Satellite コネクターにアクセスできる IBM Cloud API キーの単一行の値を指定します。

  3. ~/agent/env-files ディレクトリーに、以下の値を持つ env.txt という名前のファイルを作成します。 SATELLITE_CONNECTOR_ID 変数をSatelliteで変更する。コネクタID。

    SATELLITE_CONNECTOR_ID=<Your Satellite Connector ID>
SATELLITE_CONNECTOR_IAM_APIKEY=/agent-env-files/apikey
SATELLITE_CONNECTOR_TAGS=sample tag

  4. この時点で、ディレクトリーには 2 つのファイルが含まれており、以下の例のようになります。

    env-files$ ls
apikey  env.txt

  5. 以下のセクションの手順を実行して、エージェント・イメージをプルします。

ステップ 2: エージェント・イメージのプル

  1. IBM Cloud® Container Registry にログインします。 または、API キーを使用して Docker から直接リポジトリーにログインします。

    ibmcloud cr region-set icr.io

    docker login -u iamapikey -p <your apikey> icr.io

  2. お客様のアーキテクチャに適した公開済みのイメージの最新バージョンをダウンロードしてください。 使用可能なタグ値は、 latest 、 latest-amd64 、 latest-arm64 、 latest-ppc64le 、 latest-s390x です。 公開バージョンの一覧は 、 IBM Satellite Connector Agent Release History からご覧いただけます。

    docker pull icr.io/ibm/satellite-connector/satellite-connector-agent:latest

  3. エージェント・イメージを実行するには、以下の手順を実行します。

ステップ 3: エージェント・イメージの実行

  1. エージェント・イメージの使用可能なバージョンを表示するには、以下のコマンドを実行します。

    ibmcloud cr images --include-ibm |egrep -i "tag|satellite"

    出力例:

    Repository                                                  Tag             Digest         Namesp  Created         Size     Security status
icr.io/ibm/satellite-connector/satellite-connector-agent    latest          63a97392e510   ibm     -               937 B    -
icr.io/ibm/satellite-connector/satellite-connector-agent    latest-amd64    0d2b1a5773e5   ibm     1 week ago      50 MB    -
icr.io/ibm/satellite-connector/satellite-connector-agent    latest-arm64    cb60b8d7040f   ibm     1 week ago      94 MB    -
icr.io/ibm/satellite-connector/satellite-connector-agent    latest-ppc64le  4bcf8b1f6ea7   ibm     1 week ago      107 MB   -
icr.io/ibm/satellite-connector/satellite-connector-agent    latest-s390x    27588d9d6143   ibm     1 week ago      94 MB    -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.0          5f4e42c8d53e   ibm     2 years ago     124 MB   -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.1          0caddb11b1c1   ibm     1 year ago      125 MB   -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10         52db33f1ec43   ibm     -               937 B    -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-amd64   90c920b580fe   ibm     2 months ago    50 MB    -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-arm64   322f92d8c373   ibm     2 months ago    94 MB    -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-ppc64le 603b3507f20c   ibm     2 months ago    107 MB   -
icr.io/ibm/satellite-connector/satellite-connector-agent    v1.1.10-s390x   afe670f04ea2   ibm     2 months ago    95 MB    -

  2. -v オプションを使用して、 env-files ディレクトリーをコンテナーの /agent-env-files ディレクトリーにマウントします。 公開されたイメージの最新バージョンまたは特定のバージョンを使用できます。

    環境変数がファイルへのパスを使用している場合、そのパスはコンテナー内のファイル・パスでなければなりません。 ファイル・パスを取得するには、 docker run コマンドで -v オプションを使用します。 -v オプションは、ローカル環境変数ディレクトリー・パスによって指定され、その後にコンテナー内のマウント・パスが続き、 : で区切られます。 例えば、 -v ~/agent/env-files:/agent-env-files と入力します。ここで、 ~/agent/env-files はローカル・パス、 /agent-env-files はコンテナー内のパスです。

    docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:latest

    イメージのバージョン 1.1.0 を使用するコマンド例では、以下のコマンドを実行します。

    docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:v1.1.0

  3. コンテナーのログを調べて、コネクターに対してトンネルが確立されたことを確認できます。

    docker logs CONTAINER-ID

    ログの先頭付近に、以下の例のような項目があります。

    {"level":30,"time":"2023-06-20T16:12:20.133Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_ID value from SATELLITE_CONNECTOR_ID environment variable."}
{"level":30,"time":"2023-06-20T16:12:20.138Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A01","msg":"Load SATELLITE_CONNECTOR_IAM_APIKEY value from file /agent-env-files/apikey."}
{"level":30,"time":"2023-06-20T16:12:20.140Z","pid":8,"hostname":"6b793f671c79","name":"agentOps","msgid":"A02","msg":"Load SATELLITE_CONNECTOR_TAGS value from SATELLITE_CONNECTOR_TAGS environment variable."}
{"level":30,"time":"2023-06-20T16:12:20.142Z","pid":8,"hostname":"6b793f671c79","name":"connector-agent","msgid":"LA2","msg":"Connector id: U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI, region: us-south, release info: 20230610-dd48822928d35a84b31029a996fa9abc9d29fc93_A."}
{"level":30,"time":"2023-06-20T16:12:20.392Z","pid":8,"hostname":"6b793f671c79","name":"tunneldns","msgid":"D04","msg":"DoTunnelDNSLookup DNS resolve c-01-ws.us-south.link.satellite.cloud.ibm.com to 169.61.31.178"}
{"level":30,"time":"2023-06-20T16:12:21.560Z","pid":8,"hostname":"6b793f671c79","name":"utilities","msg":"MakeLinkAPICall GET /v1/connectors/U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI status code 200"}
{"level":30,"time":"2023-06-20T16:12:21.563Z","pid":8,"hostname":"6b793f671c79","name":"agent_tunnel","msgid":"LAT03","msg":"Got configuration"}
{"level":30,"time":"2023-06-20T16:12:21.565Z","pid":8,"hostname":"6b793f671c79","name":"agent_tunnel","msgid":"LAT04-wss://c-01-ws.us-south.link.satellite.cloud.ibm.com/ws","msg":"Connecting to wss://c-01-ws.us-south.link.satellite.cloud.ibm.com/ws"}
{"level":30,"time":"2023-06-20T16:12:21.922Z","pid":8,"hostname":"6b793f671c79","name":"tunneldns","msgid":"D04","msg":"DoTunnelDNSLookup DNS resolve c-01-ws.us-south.link.satellite.cloud.ibm.com to 169.61.31.178"}
{"level":30,"time":"2023-06-20T16:12:22.294Z","pid":8,"hostname":"6b793f671c79","name":"TunnelCore","msgid":"TC24","msg":"Tunnel open","connector_id":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI"}
{"level":30,"time":"2023-06-20T16:12:22.299Z","pid":8,"hostname":"6b793f671c79","name":"connector_tunnel_base","msgid":"CTB26-U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI","msg":"Send connector information to tunnel server"}
{"level":30,"time":"2023-06-20T16:12:22.307Z","pid":8,"hostname":"6b793f671c79","name":"connector_tunnel_base","msgid":"CTB27","msg":"Tunnel connected","connector_id":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaThzdWd1ZDFwZ2RrZmUxa3UxZyI","cipher":{"name":"TLS_AES_256_GCM_SHA384","standardName":"TLS_AES_256_GCM_SHA384","version":"TLSv1.3"}}

エージェントをセットアップした後、エンドポイントと ACL を作成して、それらのエンドポイントへのアクセスを管理できます。 詳しくは、 コネクター・エンドポイントの作成と管理 を参照してください。

Windows上でのエージェントの実行

Windows でコネクター・エージェントを実行するには、以下の手順を確認してください。

作業を始める前に、最低限必要な条件 を確認してください。

ステップ 1: CLI からのコネクター・エージェント・ファイルのダウンロード

  1. CLI から、以下のコマンドを実行してエージェントの .zip ファイルをダウンロードします。

    ibmcloud sat agent attach --platform windows

    出力例。

    Downloading agent setup tools for windows...
OK
Satellite connector agent for windows was successfully returned /var/folders/17/y8wr4y_x1tb4yf__g3wr6g8m0000gp/T/windows_satellite_connector_4097559421.zip

  2. PowerShell で以下のコマンドを実行して、.zip の sha512sum を確認します。

    Get-FileHash -Algorithm SHA512 -Path c:\windows_satellite_connector_1420916628.zip

  3. PowerShell で以下のコマンドを実行して、 .zip ファイルの内容を解凍します。

    Expand-Archive -Path 'C:\path\to\windows_satellite_connector_4097559421.zip' -DestinationPath ‘C:\path\to\extract'

  4. 以下のセクションのステップを実行して、抽出した構成ファイルを更新します。

ステップ 2: config.json ファイルの更新

構成情報は、前のステップで抽出した config.json ファイル内の以下の環境変数を使用してエージェントに提供されます。 エージェント・イメージの以下のパラメーターを確認します。

  1. 前に抽出した config.json を、 各パラメーターの 適切な値で更新します。

    ファイル・パス内のスラッシュをエスケープする必要があります。

    例 config.json.

    {
  "SATELLITE_CONNECTOR_ID":"<Your Satellite Connector ID>",
  "SATELLITE_CONNECTOR_IAM_APIKEY":"<Your API Key>",
  "SATELLITE_CONNECTOR_TAGS":"sample tag",
  "LOG_LEVEL": "info",
  "PRETTY_LOG": true
}

    値が設定された config.json の例。

    {
  "SATELLITE_CONNECTOR_ID":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA",
  "SATELLITE_CONNECTOR_IAM_APIKEY":"C:\\path\\to\\apikey",
  "SATELLITE_CONNECTOR_TAGS":"sample tag",
  "LOG_LEVEL": "info",
  "PRETTY_LOG": true
}

  2. ファイルを保存します。

  3. 以下のセクションの手順を実行して、エージェントを開始します。

ステップ 3: エージェントの開始

  1. PowerShellで install コマンドを実行して、エージェントを開始します。

    .\install

    エージェントを起動して Windows Microsoft Defender SmartScreen エラーが発生した場合、これは予期されたことです。 プレーンテキストのインストールスクリプトは署名されていない。 エージェントをダウンロードした 後、sha512sum を確認するステップに頼ることをお勧めします。

  2. PowerShell で Get-Service コマンドを実行して、エージェントがインストールされていることを確認します。

    Get-Service 'Satellite Connector Service'

  3. PowerShellで Get-Content コマンドを実行して、エージェント・ログを表示します。

    Get-Content 'C:\path\to\extract\logs\{satelliteconnectorservice_{{yyyymmdd}}.out.log}'

  4. オプション: PowerShellで uninstall コマンドを実行して、エージェントを停止します。

    .\uninstall

エージェントをセットアップした後、エンドポイントと ACL を作成して、それらのエンドポイントへのアクセスを管理できます。 詳しくは、 コネクター・エンドポイントの作成と管理 を参照してください。

Windows上でのエージェントの更新

エージェントパッケージの update-service コマンドを使用して、設定変更をエージェントに適用することができます。 このコマンドを実行すると、エージェントが停止、アンインストール、および再インストールされます。 以下の手順でエージェントを更新してください。

  1. 更新する前に、Connector Windows エージェントの変更ログ の変更を確認し、最新バージョンが現在実行中のエージェントより新しいかどうかを確認します。

    現在のバージョン番号は、現在実行中のエージェントのエージェントパッケージ内の version.txt ファイルで確認できます。 version.txt ファイルが見つからなかったり、現在のバージョン番号が最新のバージョン番号より小さかったりした場合は、アップデート可能な新しいバージョンがあります。

  2. 利用可能な新しいエージェントバージョンがあり、それを使用したい場合は、次のステップに進む前に、Step 1: CLIからConnectorエージェントファイルをダウンロードする の指示に従って最新バージョンをダウンロードしてください。

  3. config.json ファイルの設定パラメータを変更する。

    例 config.json.

    {
  "SATELLITE_CONNECTOR_ID":"<Your Satellite Connector ID>",
  "SATELLITE_CONNECTOR_IAM_APIKEY":"<Your API Key>",
  "SATELLITE_CONNECTOR_TAGS":"<tags>",
  "LOG_LEVEL": "info",
  "PRETTY_LOG": true
}

    値が設定された config.json の例。

    {
  "SATELLITE_CONNECTOR_ID":"U2F0ZWxsaXRlQ29ubmVjdG9yOiJjanM4cnRzZjFsN2c0M3U4cmp1MBA",
  "SATELLITE_CONNECTOR_IAM_APIKEY":"C:\\path\\to\\apikey",
  "SATELLITE_CONNECTOR_TAGS":"sample tag",
  "LOG_LEVEL": "info",
  "PRETTY_LOG": true
}

  4. PowerShellで update-service コマンドを実行します。

    .\update-service

  5. PowerShell で Get-Service コマンドを実行して、エージェントがインストールされていることを確認します。

    Get-Service 'Satellite Connector Service'

  6. PowerShellで Get-Content コマンドを実行して、エージェント・ログを表示します。

    Get-Content 'C:\path\to\extract\logs\{satelliteconnectorservice_{{yyyymmdd}}.out.log}'

次のステップ

コネクター・エージェントを作成した後、 IBM Cloud プライベート・ネットワークからロケーションで実行されているリソースに接続するためのエンドポイントを作成できます。 アクセス制御リスト・ルールを作成することによって、エンドポイントへのアクセスを制御することもできます。 詳しくは、 コネクター・エンドポイントの作成と管理 を参照してください。