运行连接器代理程序

创建 Satellite 连接器后，请完成以下步骤创建代理并完成设置。

先决条件

创建 Satellite 连接器。
安装 CLI。
可选: 创建服务标识。建议使用单个用户凭证来提供服务标识。
确保运行代理的用户或服务 ID 在 IAM 中具有 Viewer 平台角色 Satellite。
使用您自己的登录或服务标识创建 API 密钥。此 API 密钥由连接器代理程序使用。
确保计算环境满足运行代理程序映像的最低要求。
查看代理程序参数。

查看代理程序参数

通过以下环境变量向代理程序提供配置信息。这些环境变量中的任何一个都可以直接设置为值，也可以设置为包含该值的文件的路径。路径值必须可从容器内访问，因此基于安装点而不是主机上的本地路径。请参见下表中的示例。

配置环境变量
环境变量	必需	描述
`SATELLITE_CONNECTOR_ID`	是	代理程序绑定到的 Satellite 连接器的标识。您可以在 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 隧道入口服务器。指定内部入口将确保代理和隧道服务器之间的所有流量都保持在专用网络内。
`LOG_LEVEL`	否	设置要为代理程序接收的日志记录详细信息的级别。您可以指定 `fatal`，`error`，`warn`，`debug`，`info` 或 `trace` 中的一个。默认级别为 `info`。通常，`debug` 和 `trace` 级别仅在调试时使用。
`PRETTY_LOG`	否	仅限 Windows 环境。指定“`true` 以显示漂亮格式的日志，或指定”`false` 以显示 JSON 格式的日志。

在容器平台上运行代理程序

开始之前，请查看最低要求。

步骤 1: 创建本地配置文件

有多种方法可以将代理程序配置环境变量信息传递到容器。以下示例使用配置文件。但是，您还可以使用 docker run --env 命令来指定值。

请注意，如果将 --env 与 API 密钥配合使用，那么 API 密钥将向容器环境公开，并且在 docker inspect 命令的输出上可见。您可以保护文件中的 API 密钥，然后在环境变量中使用文件名。如果选择使用文件名，那么必须确保在环境变量中指定的文件路径已安装到容器中的文件路径，如以下示例中所示。

以下步骤中显示的文件名是示例，可以针对您的环境进行定制。

在此示例中，创建配置文件的目录 ~/agent/env-files。
使用 IBM Cloud API 密钥的单行值在 ~/agent/env-files 目录中创建一个名为 apikey 的文件，该文件可访问 Satellite 连接器。
使用以下值在 ~/agent/env-files 目录中创建名为 env.txt 的文件。用您的Satellite修改 "SATELLITE_CONNECTOR_ID 变量。连接器 ID。
```
SATELLITE_CONNECTOR_ID=<Your Satellite Connector ID>
SATELLITE_CONNECTOR_IAM_APIKEY=/agent-env-files/apikey
SATELLITE_CONNECTOR_TAGS=sample tag
```
此时，您的目录包含 2 文件，看起来类似于以下示例。
```
env-files$ ls
apikey  env.txt
```
完成以下部分中的步骤以拉取代理程序映像。

步骤 2: 正在拉取代理程序映像

登录到 IBM Cloud® Container Registry。或者使用 API 密钥直接从 Docker 登录到存储库。
```
ibmcloud cr region-set icr.io
```
```
docker login -u iamapikey -p <your apikey> icr.io
```
下载适合您架构的最新版本已发布图片。可接受的标签值为 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: 运行代理程序映像

要查看代理程序映像的可用版本，请运行以下命令。

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    -

使用 -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
```

您可以通过查看容器的日志来验证是否已建立到连接器的隧道。

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 下载连接器代理程序文件

在 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

在 PowerShell 中运行以下命令，验证 sha512sum 的 .zip。

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

在 PowerShell 中运行以下命令以抽取 .zip 文件内容。

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

完成以下部分中的步骤以更新您解压缩的配置文件。

步骤 2: 更新 `config.json` 文件

配置信息通过您在上一步中解压缩的 config.json 文件中的以下环境变量提供给代理程序。查看代理程序映像的以下参数。

使用相应的值对于每个参数更新先前抽取的 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
}

保存文件。
完成以下部分中的步骤以启动代理程序。

步骤 3: 启动代理程序

通过在 PowerShell中运行 install 命令来启动代理程序。
```
.\install
```
如果启动代理并收到 Windows Microsoft Defender SmartScreen 错误，这是意料之中的。纯文本安装脚本没有签名。我们建议您在下载代理后依靠该步骤来验证 sha512sum。
在 PowerShell 中运行 Get-Service 命令，验证代理是否已安装。
```
Get-Service 'Satellite Connector Service'
```

通过在 PowerShell中运行 Get-Content 命令来查看代理程序日志。

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

可选: 通过在 PowerShell中运行 uninstall 命令来停止代理程序。
```
.\uninstall
```

设置代理程序后，可以创建端点和 ACL 以管理对这些端点的访问权。有关更多信息，请参阅创建和管理连接器端点。

在 Windows 上更新代理

您可以使用代理软件包中的 update-service 命令对代理应用配置更改。运行该命令时，将停止，卸载和重新安装代理程序。完成以下步骤更新您的代理。

更新前，请查看 Connector Windows 代理更改日志中的更改，并检查最新版本是否比当前运行的代理更新。

您可以在当前运行的代理软件包内的 version.txt 文件中找到当前的版本号。如果没有找到 version.txt 文件，或者当前版本号小于最新版本号，则表示有更新的版本可供更新。
如果有更新的代理版本，并且您想使用它，请按照步骤 1：从 CLI 下载连接器代理文件中的说明下载最新版本，然后再执行以下步骤。

修改 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
}

在 PowerShell中运行 update-service 命令。
```
.\update-service
```
在 PowerShell 中运行 Get-Service 命令，验证代理是否已安装。
```
Get-Service 'Satellite Connector Service'
```

通过在 PowerShell中运行 Get-Content 命令来查看代理程序日志。

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

后续步骤

创建连接器代理程序后，您可以创建端点以从 IBM Cloud 专用网络连接到位置上运行的资源。您还可以通过创建访问控制表规则来控制对端点的访问。有关更多信息，请参阅创建和管理连接器端点。

运行连接器代理程序

先决条件

查看代理程序参数

在容器平台上运行代理程序

步骤 1: 创建本地配置文件

步骤 2: 正在拉取代理程序映像

步骤 3: 运行代理程序映像

在 Windows 上运行代理

步骤 1: 从 CLI 下载连接器代理程序文件

步骤 2: 更新 config.json 文件

步骤 3: 启动代理程序

在 Windows 上更新代理

后续步骤

步骤 2: 更新 `config.json` 文件