排查 IBM Spectrum Symphony 连接器问题

本文档可帮助您解决 IBM Spectrum Symphony 与 Google Cloud集成时遇到的常见问题。具体而言，本文档针对 IBM Spectrum Symphony 主机工厂服务、Compute Engine 和 GKE 提供商的连接器以及 Symphony Operator for Kubernetes 提供了问题排查指南。

Symphony 主机工厂服务问题

这些问题与中央 Symphony 主机工厂服务有关。您可以在 Linux 上的以下位置找到此服务的主要日志文件：

$EGO_TOP/hostfactory/log/hostfactory.hostname.log

您可以在加载宿主工厂环境变量时设置 $EGO_TOP 环境变量。在 IBM Spectrum Symphony 中，$EGO_TOP 指向企业网格编排器 (EGO) 的安装根目录，EGO 是集群的核心资源管理器。Linux 上 $EGO_TOP 的默认安装路径通常为 /opt/ibm/spectrumcomputing。

集群不会为待处理的工作负载添加新的虚拟机

当 Symphony 队列包含作业，但主机工厂无法预配新的虚拟机 (VM) 来管理负载时，就会出现此问题。宿主工厂日志文件不包含任何 SCALE-OUT 消息。

当 Symphony 请求者未正确配置或启用时，通常会发生此问题。如需解决此问题，请检查已配置的请求者的状态，以验证其是否已启用以及是否存在待处理的工作负载。

找到请求者配置文件。该文件通常位于以下位置：
```
$HF_TOP/conf/requestors/hostRequestors.json
```
当您使用 source 命令时，$HF_TOP 环境变量会在您的环境中定义。该值是 IBM Spectrum Symphony 主机工厂服务的顶级安装目录的路径。
打开 hostRequestors.json 文件，然后找到 symAinst 条目。在该部分中，验证 enabled 参数是否已设置为值 1，以及提供方列表是否包含已配置的 Google Cloud 提供方实例的名称。
- 对于 Compute Engine 配置，提供方列表必须显示您在 Compute Engine 提供方安装期间启用提供方实例时创建的 Compute Engine 提供方名称。
- 对于 GKE 配置，提供方列表必须显示您在 GKE 提供方安装期间启用提供方实例时创建的 GKE 提供方的名称。
确认已启用 symAinst 请求者后，检查使用方是否有需要扩缩的待处理工作负载。

查看所有使用方及其工作负载状态的列表：
```
egosh consumer list
```
在输出中，找到与您的工作负载关联的使用方，并验证该工作负载是否处于待处理状态。如果请求者已启用且有工作负载处于待处理状态，但宿主工厂服务未发起扩缩请求，请检查 HostFactory 服务日志中是否存在错误。

主机出厂服务未启动

如果宿主工厂服务未运行，请按以下步骤解决问题：

检查 HostFactory 服务的状态：
```
egosh service list
```
在输出中，找到 HostFactory 服务，并检查 STATE 字段是否显示 STARTED 状态。

如果 HostFactory 服务未启动，请重启该服务：

egosh service stop HostFactory
egosh service start HostFactory

其他错误和日志记录

如果您遇到主机工厂服务的其他错误，请增加日志详细程度以获取更详细的日志。为此，请完成以下步骤：

打开 hostfactoryconf.json 文件进行修改。该文件通常位于以下位置：
```
$EGO_TOP/hostfactory/conf/
```
如需详细了解 $EGO_TOP 环境变量的值，请参阅 Symphony 主机工厂服务问题。

将 HF_LOGLEVEL 值从 LOG_INFO 更新为 LOG_DEBUG：

{
  ...
  "HF_LOGLEVEL": "LOG_DEBUG",
  ...
}

进行更改后，保存文件。

如需使更改生效，请重启 HostFactory 服务：

egosh service stop HostFactory
egosh service start HostFactory

重启后，HostFactory 服务会生成更详细的日志，您可以使用这些日志来排查复杂问题。您可以在主宿主工厂日志文件（位于 Linux 上的 $EGO_TOP/hostfactory/log/hostfactory.hostname.log）中查看这些日志。

主机工厂提供程序问题

以下问题发生在 Compute Engine 或 Google Kubernetes Engine 的宿主工厂提供程序脚本中。

查看提供程序日志（hf-gce.log 或 hf-gke.log），了解详细的错误消息。hf-gce.log 和 hf-gke.log 文件的位置由提供程序配置文件中设置的 LOGFILE 变量决定，如启用提供程序实例中所述。

虚拟机或 pod 未配置

在宿主工厂提供程序日志显示对 requestMachines.sh 脚本的调用后，但资源未显示在 Google Cloud项目中时，可能会出现此问题。

如需解决此问题，请按以下步骤操作：

检查提供程序脚本日志（hf-gce.log 或 hf-gke.log），看看是否有来自 Google Cloud API 的错误消息。hf-gce.log 和 hf-gke.log 文件的位置由提供程序配置文件中设置的 LOGFILE 变量决定，如启用提供程序实例中所述。
验证服务账号是否具有正确的 IAM 权限：
1. 按照查看当前访问权限中的说明操作。
2. 验证服务账号是否具有项目中的 Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
为确保主机模板中的 Compute Engine 参数有效，您必须验证以下内容：
1. 宿主模板参数必须位于您在 Compute Engine 提供程序安装期间设置提供程序实例时创建的 gcpgceinstprov_templates.json 文件中。最常验证的参数是 gcp_zone 和 gcp_instance_group。
2. 验证 gcp_instance_group 参数设置的实例组是否存在。如需确认实例组，请按照查看 MIG 的属性中的说明操作，使用模板文件中的 gcp_instance_group 名称和 gcp_zone 区域值。

Pod 在 GKE 上卡在 `Pending` 或 `Error` 状态

此问题可能会在 hf-gke 日志显示已创建 GCPSymphonyResource 资源后出现，但 GKE 集群中的相应 pod 始终无法达到 Running 状态，并且可能会显示 Pending、ImagePullBackOff 或 CrashLoopBackOff 等状态。

如果 Kubernetes 集群中存在问题，例如容器映像名称无效、CPU 或内存资源不足，或者卷或网络设置配置错误，则会出现此问题。

如需解决此问题，请使用 kubectl describe 检查自定义资源和 Pod 的事件，以确定根本原因：

kubectl describe gcpsymphonyresource RESOURCE_NAME
kubectl describe pod POD_NAME

替换以下内容：

RESOURCE_NAME：资源的名称。
POD_NAME：Pod 的名称。

排查 Kubernetes 操作器问题

Kubernetes 运算符管理 Symphony pod 的生命周期。以下部分可帮助您排查在操作员和这些资源方面可能遇到的常见问题。

诊断资源状态字段方面的问题

Kubernetes 运算符通过以下两种主要资源类型管理 GKE 中的 Symphony 工作负载：

GCPSymphonyResource (GCPSR) 资源用于管理 Symphony 工作负载的计算 pod 的生命周期。
MachineReturnRequest (MRR) 资源负责处理计算资源的返回和清理。

您可以使用以下状态字段来诊断 GCPSymphonyResource 资源的问题：

phase：资源的当前生命周期阶段。选项包括 Pending、Running、WaitingCleanup 或 Completed。
availableMachines：已准备就绪的计算 Pod 数量。
conditions：包含时间戳的详细状态条件。
returnedMachines：返回的 Pod 列表。

您可以使用以下状态字段来诊断 MachineReturnRequest 资源的问题：

phase：退货请求的当前阶段。选项包括 Pending、InProgress、Completed、Failed 或 PartiallyCompleted。
totalMachines：要返回的机器总数。
returnedMachines：成功退回的机器数量。
failedMachines：未能返回的机器数量。
machineEvents：每台机器的状态详细信息。

`GCPSymphonyResource` 资源卡在 `Pending` 状态

当 GCPSymphonyResource 资源保持在 Pending 状态且 availableMachines 的值未增加时，会出现此问题。

此问题可能是由以下某一原因造成的：

集群中的节点容量不足。
拉取容器映像时出现问题。
资源配额限制。

要解决此问题，请执行以下操作：

检查 pod 的状态，以确定映像拉取或资源分配是否存在任何问题：
```
kubectl describe pods -n gcp-symphony -l symphony.requestId=REQUEST_ID
```
将 REQUEST_ID 替换为您的请求 ID。
检查节点以确保容量充足：
```
kubectl get nodes -o wide
```
Pod 可能会显示 Pending 状态。当 Kubernetes 集群需要扩容但耗时超出预期时，通常会发生此问题。监控节点，确保控制平面可以横向扩缩。

Pod 未退回

如果您创建了 MachineReturnRequest（经常性月收入），但 returnedMachines 的数量没有增加，就会出现此问题。

出现此问题的原因如下：

Pod 卡在 Terminating 状态。
存在节点连接问题。

要解决此问题，请执行以下操作：

检查是否有 pod 卡在 Terminating 状态：

kubectl get pods -n gcp-symphony --field-selector=status.phase=Terminating

说明 MachineReturnRequest 以获取有关退货流程的详细信息：
```
kubectl describe mrr MRR_NAME -n gcp-symphony
```
将 MRR_NAME 替换为 MachineReturnRequest 的名称。
手动删除自定义资源对象。此删除操作会激活最终清理逻辑：
```
kubectl delete gcpsymphonyresource RESOURCE_NAME
```
将 RESOURCE_NAME 替换为 GCPSymphonyResource 资源的名称。

`MachineReturnRequest` 中有大量机器出现故障

当 MachineReturnRequest 状态中的 failedMachines 数量大于 0 时，就会出现此问题。出现此问题的原因如下：

Pod 删除已超时。
节点不可用。

要解决此问题，请执行以下操作：

检查 MachineReturnRequest 状态中的 machineEvents，了解具体错误消息：
```
kubectl describe mrr MRR_NAME -n gcp-symphony
```
查找节点故障事件或控制平面性能问题：
1. 获取所有节点的状态：
```
kubectl get nodes -o wide
```
2. 检查特定节点：
```
kubectl describe node NODE_NAME
```

Pod 未被删除

当已删除的 pod 卡在 Terminating 或 Error 状态时，就会出现此问题。

出现此问题的原因如下：

控制平面或操作员过载，这可能会导致超时或 API 节流事件。
手动删除父级 GCPSymphonyResource 资源。

要解决此问题，请执行以下操作：

检查父级 GCPSymphonyResource 资源是否仍然可用且未处于 WaitingCleanup 状态：
```
kubectl describe gcpsymphonyresource RESOURCE_NAME
```
如果父 GCPSymphonyResource 资源不再位于系统上，请手动从 pod 中移除 finalizer。终结器会告知 Kubernetes 等待 Symphony operator 完成其清理任务，然后再完全删除 pod。首先，检查 YAML 配置以找到 finalizer：
```
kubectl get pods -n gcp-symphony -l symphony.requestId=REQUEST_ID -o yaml
```
将 REQUEST_ID 替换为与 pod 关联的请求 ID。
在输出中，查找元数据部分中的 finalizers 字段。您应该会看到类似于以下代码段的输出：
```
metadata:
...
finalizers:
-   symphony-operator/finalizer
```

如需手动从 pod 中移除终结器，请使用 kubectl patch 命令：

kubectl patch pod -n gcp-symphony -l symphony.requestId=REQUEST_ID --type json -p '[{"op": "remove", "path": "/metadata/finalizers", "value": "symphony-operator/finalizer"}]'

将 REQUEST_ID 替换为与 pod 关联的请求 ID。

旧的 Symphony 资源不会自动从 GKE 集群中删除

当工作负载完成且 GKE 停止其 pod 后，关联的 GCPSymphonyResource 和 MachineReturnRequest 对象在 GKE 集群中保留的时间会超过预期的 24 小时清理期。

如果 GCPSymphonyResource 对象缺少必需的 Completed status 条件，就会出现此问题。操作者的自动清理流程依赖于此状态来移除对象。如需解决此问题，请完成以下步骤：

查看相关 GCPSymphonyResource 资源的详细信息：
```
kubectl get gcpsr GCPSR_NAME -o yaml
```
将 GCPSR_NAME 替换为存在此问题的 GCPSymphonyResource 资源的名称。

查看状态为 True 的 Completed 类型条件：

status:
  availableMachines: 0
  conditions:
  -   lastTransitionTime: "2025-04-14T14:22:40.855099+00:00"
    message: GCPSymphonyResource g555dc430-f1a3-46bb-8b69-5c4c481abc25-2pzvc has
      no pods.
    reason: NoPods
    status: "True"        # This condition will ensure this
    type: Completed       # custom resource is cleaned up by the operator
  phase: WaitingCleanup
  returnedMachines:
  -   name: g555dc430-f1a3-46bb-8b69-5c4c481abc25-2pzvc-pod-0
    returnRequestId: 7fd6805f-9a00-41f9-afe9-c38aa35002db
    returnTime: "2025-04-14T14:22:39.373216+00:00"

如果 GCPSymphonyResource 详情中未显示此条件，而是显示了 phase: WaitingCleanup，则表示 Completed 事件已丢失。

检查与 GCPSymphonyResource 关联的 pod：
```
kubectl get pods -l symphony.requestId=REQUEST_ID
```
将 REQUEST_ID 替换为请求 ID。
如果不存在任何 pod，请安全地删除 GCPSymphonyResource 资源：
```
kubectl delete gcpsr GCPSR_NAME
```
将 GCPSR_NAME 替换为 GCPSymphonyResource 的名称。
如果您在删除 GCPSymphonyResource 之前就存在这些 pod，则必须将其删除。如果 Pod 仍然存在，请按照未删除 Pod 部分中的步骤操作。

Pod 未加入 Symphony 集群

当 pod 在 GKE 中运行，但未显示为 Symphony 集群中的有效主机时，就会出现此问题。

如果 pod 内运行的 Symphony 软件无法连接到 Symphony 主宿主并向其注册，则会发生此问题。此问题通常是由于网络连接问题或容器内 Symphony 客户端的配置错误所致。

如需解决此问题，请检查在 pod 内运行的 Symphony 服务的日志。

使用 SSH 或 exec 访问 pod 并查看日志：
```
kubectl exec -it POD_NAME -- /bin/bash
```
将 POD_NAME 替换为 pod 的名称。
当您在 pod 中有 sh 时，EGO 和 LIM daemon 的日志位于 $EGO_TOP/kernel/log 目录中。$EGO_TOP 环境变量指向 IBM Spectrum Symphony 安装的根目录：
```
cd $EGO_TOP/kernel/log
```
如需详细了解 $EGO_TOP 环境变量的值，请参阅 Symphony 主机工厂服务问题。
检查日志中是否存在阻止 GKE Pod 与本地 Symphony 主 Pod 建立连接的配置或网络错误。

设备退回请求失败

当您创建 MachineReturnRequest 自定义资源时，如果对象卡住，并且操作员未终止相应的 Symphony pod，则在缩减操作期间可能会出现此问题。

运算符的终结器逻辑中的故障会阻止干净地删除 pod 及其关联的自定义资源。此问题可能会导致资源孤立和不必要的费用。

如需解决此问题，请手动删除自定义资源，这应会激活操作者的清理逻辑：

kubectl delete gcpsymphonyresource RESOURCE_NAME

将 RESOURCE_NAME 替换为资源的名称。

排查 IBM Spectrum Symphony 连接器问题 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Symphony 主机工厂服务问题

集群不会为待处理的工作负载添加新的虚拟机

主机出厂服务未启动

其他错误和日志记录

主机工厂提供程序问题

虚拟机或 pod 未配置

Pod 在 GKE 上卡在 Pending 或 Error 状态

排查 Kubernetes 操作器问题

诊断资源状态字段方面的问题

GCPSymphonyResource 资源卡在 Pending 状态

Pod 未退回

MachineReturnRequest 中有大量机器出现故障

Pod 未被删除

旧的 Symphony 资源不会自动从 GKE 集群中删除

Pod 未加入 Symphony 集群

设备退回请求失败

排查 IBM Spectrum Symphony 连接器问题

Pod 在 GKE 上卡在 `Pending` 或 `Error` 状态

`GCPSymphonyResource` 资源卡在 `Pending` 状态

`MachineReturnRequest` 中有大量机器出现故障