【待评审】支持主备管理的北向接口材料评审

Interface SIG Interface评审
1

背景

为满足上层管理软件对主备状态的查询和主备倒换能力，需要提供北向接口（Web、CLI、Redfish）来支持主备状态的查询和倒换命令。

依赖 D-Bus 服务：

服务 路径 接口 属性/方法
主备状态查询 /bmc/kepler/Managers/1/ActiveStandby/Local bmc.kepler.Managers.ActiveStandby.Local ActiveStatus、CommunicationStatus
对板状态查询 /bmc/kepler/Managers/1/ActiveStandby/Remote bmc.kepler.Managers.ActiveStandby.Remote ActiveStatus、CommunicationStatus
主备倒换 /bmc/kepler/Managers/1/ActiveStandby/Local bmc.kepler.Managers.ActiveStandby.Local SwitchStatus 方法

关联ISSUE

[需求]: 支持主备管理的北向接口 - openUBMC/rackmount - AtomGit | GitCode

评审点

1、web接口支持查询主备状态和发送主备倒换命令
2、cli接口支持查询主备状态和发送主备倒换命令
3、redfish接口支持查询主备状态和发送主备倒换命令

详细描述

评审点一：web接口支持查询主备状态和发送主备倒换命令

1.1 查询主备状态

资源URI：/UI/Rest/BMCSettings/Failover

操作类型：GET

操作权限：ReadOnly

变更点 ：接口文档已有接口，需实现

属性输出说明

一级属性 二级属性 类型 示例 描述
ActiveIndex / Number 1 原有属性，主用板索引
StandbyList / Array - 新增属性，备用节点列表
Index Number 2 原有属性，备用板索引
Present Number 1 原有属性，在位状态：1=在位，0=不在位
SyncStatus String “Synchronized” 原有属性，同步状态 
  {
      "ActiveIndex": 1,
      "StandbyList": [
          {
              "Index": 2,
              "Present": 1,
              "SyncStatus": "Synchronized"
          },
          {
              "Index": 3,
              "Present": 1,
              "SyncStatus": "Synchronized"
          },
          {
              "Index": 4,
              "Present": 0,
              "SyncStatus": "Unsynchronized"
          }
      ]
  }

1.2 执行主备倒换

资源URI：/UI/Rest/BMCSettings/Failover/ForceFailover

操作类型：POST

请求参数：{}

操作权限 ： BasicSetting

变更点 ：接口文档已有接口，需实现

实现方式：调用 D-Bus 服务 bmc.kepler.active_standby_mgmt 的 SwitchStatus 方法

评审点二：cli接口支持查询主备状态和发送主备倒换命令

2.1 查询主备状态

资源URI ：ipmcget -d redundancy

操作类型 ：GET

操作权限：ReadOnly

变更点 ：新增接口

属性输出示例

ipmcget -d redundancy
The Redundancy States of SMMs:
SMM1: Present(active)*
SMM2: Present(standby)

* = The SMM you are currently logged into.

2.2 执行主备倒换

资源URI：ipmcset -d failover

操作类型：PATCH

操作权限 ： BasicSetting

变更点 ：新增接口

实现方式：调用 D-Bus 服务 bmc.kepler.active_standby_mgmt 的 SwitchStatus 方法

正常回显：Change current board status successful.

错误回显：

错误信息 原因分析 处理建议
1 Failed, (Remote) SMM has an upgrade in progress. 主板或备板正在升级中 等待升级完成后再尝试
2 Failed, Remote LSW fault. 对板LSW芯片异常 检查对板LSW告警
3 Failed, Config data synchronizing. 重要配置数据正在同步 等待数据同步完成后再尝试
4 Failed, Config file synchronizing. 重要配置文件正在同步 等待文件同步完成后再尝试
5 Fail, (Remote) SMM dump info is running. 主板或备板正在收集日志 等待一键收集完成后再尝试
6 Fail, (Remote) CPLD Validating. CPLD正在生效中 等待生效完成后再尝试
7 Fail, Remote smm not installed. 对板未插入或未插稳 检查单板是否插稳
8 Fail, Remote smm cpld heartbeat abnormal. 对板CPLD主备心跳信号异常 检查对板心跳信号
9 Fail, Network to remote smm disconnected. 连接至对板的网络通信异常 检查网络连接
10 Fail, Local smm abnormal. 本板内部错误 检查本板状态
11 Fail, Remote smm abnormal. 对板内部错误 检查对板状态
12 Fail, Remote smm is initializing. 对板正在初始化 等待初始化完成后再尝试
13 Fail, Failover temporarily not allow. Please wait for a second. 主备倒换抑制中 等待抑制时间结束后再尝试
14 Fail, Local board not in its position. 本板未插稳 检查本板是否正确插入机框
15 Fail, Remote smm has critical alarm. 对板存在致命告警 消除告警后再尝试
16 Fail, Local smm cpld heartbeat abnormal. 本板CPLD主备心跳信号异常 重启单板，如仍异常联系维护工程师

评审点三：redfish接口支持查询主备状态和发送主备倒换命令

3.1 查询主备状态

资源URI ：/redfish/v1/Managers/{ManagerId}

操作类型 ：GET

操作权限 ：ReadOnly

变更点 ：已有接口，主备状态字段适配

请求参数 ：无

属性输出说明

一级属性 二级属性 类型 示例/取值约束 操作权限 描述
Status / Object - ReadOnly 管理板状态对象
State String “Enabled/StandbySpare/Absent” ReadOnly 管理资源健康状态：Enabled=主用，StandbySpare=备用,Absent=不在位
Severity String “Normal/Minor/Major/Critical” ReadOnly 管理资源告警等级
Health String “OK/Warning/Critical” ReadOnly 管理资源健康状态

响应参数 ：

主用板响应示例（以SMM1为例）：

{
    "Id": "SMM1",
    "Name": "SMM1 Management Board",
    "Status": {
        "State": "Enabled",
        "Severity": "Normal",
        "Health": "OK"
    }
}

备用板响应示例（以SMM2为例）：

json
{
    "Id": "SMM2",
    "Name": "SMM2 Management Board",
    "Status": {
        "State": "StandbySpare",
        "Severity": "Minor",
        "Health": "OK"
    }
}

Schema 定义

{
    "Status": {
        "description": "The status of the manager board.",
        "readonly": true,
        "type": "object",
        "properties": {
            "State": {
                "description": "The role state of the manager board. 'Enabled' indicates active/primary role, 'StandbySpare' indicates standby/redundant role.",
                "readonly": true,
                "type": "string",
                "enum": ["Enabled", "StandbySpare", "Absent"]
            },
            "Severity": {
                "description": "The severity level of the status.",
                "readonly": true,
                "type": "string"
            },
            "Health": {
                "description": "The health status of the manager board.",
                "readonly": true,
                "type": "string",
                "enum": ["OK", "Warning", "Critical"]
            }
        }
    }
}

3.2 执行主备倒换

资源URI：/redfish/v1/Managers/{ManagerId}/Actions/Manager.ForceFailover

操作类型：POST

变更点 ：新增接口

操作权限 ： ConfigureComponents

请求参数：{}

实现方式：调用 D-Bus 服务 bmc.kepler.active_standby_mgmt 的 SwitchStatus 方法

响应示例：

{
    "@odata.context": "/redfish/v1/$metadata#Task.Task",
    "@odata.id": "/redfish/v1/TaskService/Tasks/1",
    "@odata.type": "#Task.v1_0_2.Task",
    "Id": "1",
    "Name": "SwitchStatus",
    "TaskState": "Completed",
    "EndTime": "2026-05-22T10:30:12+00:00",
    "Messages": [
        {
            "MessageId": "Base.1.0.Success",
            "Message": "Successfully Completed Request",
            "Severity": "OK"
        }
    ],
    "Oem": {
        "Huawei": {
            "TaskPercentage": 100
        }
    }
}

Schema定义

{
    "uris": [
        "/redfish/v1/Managers/{ManagerId}/Actions/Manager.ForceFailover"
    ]
}

评审结论

1、同意统一错误描述信息格式，错误信息描述已与周边产业对齐
2、同意与其他产业对齐接口定义，优先复用现有接口能力，避免重复开发和接口冗余

遗留问题

1、错误描述信息需要和周边对齐是否可以优化（当前形式不统一）；
已对齐
2、和其他产业对齐接口是否可以复用；
已对齐