将IDC集群接入SysAgent

工作原理

IDC接入分为两层：

• 管理通道：在跳板机上安装IDC Connector组件，与云端建立加密WebSocket通道。完成后即可远程执行命令、查看节点状态。

• 巡检能力：在管理通道基础上，IDC Connector会自动在集群中部署Exporter采集组件。各节点上的Exporter周期性采集健康指标，并以巡检快照的形式写入NodeInspection CRD；IDC Connector通过K8s API读取巡检快照，再经WSS加密通道将巡检报告回传至操作系统控制台，用于对话巡检和定时巡检任务。

每个IDC机房部署一台安装了IDC Connector的跳板机，即可接入该机房的K8s集群。多个IDC机房分别接入后，可在操作系统控制台统一管理。

IDC Connector启动后会自动完成以下动作：

1. 读取本地kubeconfig，向云端注册集群并同步节点信息。

2. 与云端服务建立WSS加密连接，开始接收运维任务。

3. 通过NodeShell临时Pod在集群中部署巡检基础设施（Exporter DaemonSet、CRD等）。部署成功后，巡检功能就绪；如果节点无法拉取NodeShell镜像，巡检组件将无法部署。

接入IDC集群

前提条件

安装IDC Connector

方式一：一键安装脚本（推荐）

在跳板机上执行以下命令：

curl -fsSL https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/idc-suite/install.sh -o install.sh
bash install.sh \
  --access-key-id <your-ak> \
  --access-key-secret <your-sk> \
  --connector-name <your-connector-name> \
  --kubeconfig /path/to/your-cluster.yaml

安装脚本会自动完成RPM安装、环境配置和服务启动。内网或镜像场景下，可通过--base-url参数或RELEASE_BASE_URL环境变量覆盖发布源。

方式二：下载RPM包手动安装

适用于不使用一键安装脚本、需要分步安装或校验产物的场景。RPM包与校验和均从发布源获取。当前最新发布版本为1.3.0，请将以下命令中的<version>替换为所需版本号，并将AccessKey、Connector名称和kubeconfig路径替换为实际值。

1. 下载RPM包与校验和，并进行校验。

   BASE=https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/idc-suite
   curl -fsSL $BASE/idc-suite-<version>.x86_64.rpm -o idc-suite-<version>.x86_64.rpm
   curl -fsSL $BASE/SHA256SUMS -o SHA256SUMS
   sha256sum -c --ignore-missing SHA256SUMS

   确认RPM包的校验结果为OK后，再执行安装。

2. 安装RPM包。

   rpm -ivh idc-suite-<version>.x86_64.rpm

3. 配置环境变量。

   cat > /etc/idc-suite/idc-suite.env << EOF
   CONNECTOR_NAME=<your-connector-name>
   POP_URL=wss://sysom.cn-hangzhou.aliyuncs.com/api/v1/idc/channel
   ACCESS_KEY_ID=<your-ak>
   ACCESS_KEY_SECRET=<your-sk>
   EOF

4. 放置kubeconfig并启动服务。

   cp <your-cluster>.yaml /etc/nodehub/kubeconfigs/
   systemctl enable --now idc-suite

验证接入

执行以下命令，查看服务状态和关键日志：

systemctl status idc-suite
journalctl -u idc-suite --no-pager -n 20

日志中出现以下内容，表示集群注册和管理通道连接成功，但不代表巡检组件已部署完成：

• [bootstrap] cluster registered: ... node_count:N status:active：集群注册成功。

• [ws] connected to relay service：与云端连接成功。

接入成功后，您可以通过与SysAgent对话查看该集群，例如发送“我有哪些可用的IDC集群”。SysAgent会返回当前在线可用的IDC集群列表，包括集群ID、集群名称、所属Connector和在线状态。

继续使用目标集群的kubeconfig执行以下命令，确认巡检组件就绪。请将/path/to/your-cluster.yaml替换为实际路径。

kubectl --kubeconfig /path/to/your-cluster.yaml get crd nodeinspections.osinspect.io
kubectl --kubeconfig /path/to/your-cluster.yaml -n sysagent-system get daemonset ospilot-exporter

确认CRD存在，且DaemonSet的READY值等于集群节点数。若管理通道正常，但巡检组件不存在或未就绪，请参见下文“巡检组件未部署（NodeShell镜像拉取失败）”。

使用SysAgent巡检专家功能

IDC Connector接入后会自动部署巡检所需的组件。请先按“验证接入”中的步骤确认巡检组件就绪，再使用巡检功能。以下介绍巡检涉及的组件及其对集群的影响。

巡检组件

巡检功能依赖以下组件，由IDC Connector启动时自动部署到目标K8s集群中：

对集群的影响

巡检组件会在集群中创建以下K8s资源：

Exporter Pod的资源占用如下：

• Exporter使用hostNetwork模式，监听8401端口（用于健康检查），请确认该端口未被占用。

• 退订集群时，以上K8s资源会被自动清理。

使用巡检

接入完成后，您可以在操作系统控制台与SysAgent对话发起巡检。发起时可指定目标集群和巡检时间窗口，例如发送“对IDC集群xxx发起一次巡检，窗口取最近30分钟，并汇总异常项与异常节点”。

SysAgent会自动调用巡检服务，采集集群所有节点的健康指标并生成巡检报告。巡检报告包含以下内容：

• 巡检结论：目标集群、巡检窗口和总体等级（如Normal）。

• 异常汇总：异常项数量与检测指标总数、异常节点数量与节点总数。

• 各节点关键指标：CPU使用率（sys）、CPU iowait、内存使用率、系统负载、根磁盘使用率、容器磁盘使用率、文件描述符使用率、内核故障数和平均调度延迟等。

如需按计划自动巡检，并将巡检结果推送到IM群，请参见配置 SysAgent 定时任务。

退订与清理

在跳板机上执行以下命令，停止并卸载IDC Connector：

systemctl stop idc-suite
rpm -e idc-suite

rm -rf /var/lib/idc-suite /etc/idc-suite /etc/nodehub

常见问题

kubeconfig过期导致功能异常

现象：日志中出现Unauthorized错误。

解决方法：从ACK控制台重新获取kubeconfig，替换/etc/nodehub/kubeconfigs/下的文件后重启服务。

巡检组件未部署（NodeShell镜像拉取失败）

现象：接入流程显示成功，管理通道正常，日志中包含[bootstrap] cluster registered和[ws] connected to relay service，但集群中没有ospilot-exporter DaemonSet和nodeinspections.osinspect.io CRD。执行journalctl -u idc-suite查看日志时，可见preload failed on N of N nodes和timeout waiting for nodeshell pod to be running，节点侧Pod事件为ErrImagePull。

原因：巡检基础设施部署依赖NodeShell临时Pod，其默认镜像为docker.io/library/busybox:1.36。当集群节点无公网出口或无法访问docker.io时，镜像拉取失败，巡检组件无法部署。管理通道不依赖该镜像，因此安装摘要和管理通道验证仍显示成功。

解决方法：

1. 对于新安装的环境，通过--nodeshell-image指定集群节点可达的busybox镜像地址。以下示例适用于能够访问所示VPC端点的阿里云VPC内节点，节点无需公网出口。IDC节点应使用其网络可达的镜像地址，不能直接假定能够访问该VPC端点。

   bash install.sh \
     --access-key-id <your-ak> \
     --access-key-secret <your-sk> \
     --connector-name <your-connector-name> \
     --kubeconfig /path/to/your-cluster.yaml \
     --nodeshell-image registry-vpc.cn-hangzhou.aliyuncs.com/acs/busybox:1.35

2. 对于已安装的环境，修改/etc/idc-suite/nodehub.yaml中的nodeshell.image为集群节点可达的镜像地址，再执行以下命令重试部署：

   systemctl restart idc-suite

3. 使用目标集群的kubeconfig确认巡检组件就绪，DaemonSet的READY值应等于集群节点数：

   kubectl --kubeconfig /path/to/your-cluster.yaml -n sysagent-system get daemonset ospilot-exporter