Redfish 验证工具： Redfish Service Validator (OData CSDL)

这篇文章我去年就很想写了，因为当时身边有蛮多人对这个tool有些误解，对用来验证Redfish Schema来说它是个很好用的tool，快速又方便，现在社群也很活耀的持续开发，只是对第一次接触OData的人来说，可能会有点不知道怎么上手，但理解之后会发现其实它原理很简单的，然后如果还不认识OData的话可以先看 DMTF Redfish 介绍 ，里面有将官网连结都附上

Redfish Services validator 在 GitHub - DMTF/Redfish-Service-Validator的Readme中介绍是

Redfish Service Validator 是一个开源框架，用于检查启用了Redfish interface 的任何通用设备与DMTF 定义的Redfish schema 和specifications的一致性。该工具设计为与设备无关，并且完全基于旨在由设备支持的Redfish 规范驱动。

它是个检查Redfish Service 的Resource 是否符合DMTF定义的Schema 的工具，所以其实应该先了解CSDL Schema 怎么描述，所以这篇文章的目录如下

目录

OData CSDL（Common Schema Definition Language, 通用模式定义语言）

概述

CSDL format

Elements of CSDL namespaces

Qualified names

Entity type and complex type elements

Redfish Services validator

下载

不用安装，直接执行

常见被验出的问题

ERROR - Attributes: Property is null but is not Nullable

ERROR - XXX: Expected int, got type class 'str' (Type Error)

ERROR - Namespace of type xxx appears missing from SchemaXML xxx.xml, attempting highest type: #xxx.xxx.xxxERROR - New namespace: xxx.v1_0_2

---

*本篇文章使用到的Redfish Service 是用Redfish Mockup Server模拟的

*如果对Redfish schema 和specifications 的概念不太清楚的话，可参考如何描述Redfish 版本

OData CSDL（Common Schema Definition Language, 通用模式定义语言）

概述

OData CSDL 是定义在OData Version 4.0 Part 3: Common Schema Definition Language (CSDL) (oasis-open.org)中，Redfish 用它来描述resources 和resource collections的Schema

在service root URL(/redfish/v1) 后面加上$metadata可以看到Redfish Service的实体模型（entity model)，如下

[GET] /redfish/v1/$metadata
<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:Reference Uri="/redfish/v1/schema/AccountService_v1.xml">
        <edmx:Include Namespace="AccountService"/>
        <edmx:Include Namespace="AccountService.v1_0_0"/>
        <edmx:Include Namespace="AccountService.v1_0_2"/>
        <edmx:Include Namespace="AccountService.v1_0_3"/>
        <edmx:Include Namespace="AccountService.v1_0_4"/>
        <edmx:Include Namespace="AccountService.v1_0_5"/>
        <edmx:Include Namespace="AccountService.v1_0_6"/>
        <edmx:Include Namespace="AccountService.v1_0_7"/>
        <edmx:Include Namespace="AccountService.v1_0_8"/>
        <edmx:Include Namespace="AccountService.v1_0_9"/>

*metadata: a set of data that describes and gives information about other data.

metadata 原意是指描述数据的数据，在Redfish中就是用来描述Resource 的数据的数据，所以内容会包含该Resource 有哪些property，他们的type是int还是string，是不是required等

目前最新版的Redfish Services validator 是可以指定想要验证的schema folder，没有指定的话，就会从官网All Published Versions of DSP8010 | DMTF 抓最新版本 

 下载后就能在csdl folder中看到schema 文件了

Redfish CSDL schema文件的命名格式是 ResourceType_vMajorVersion.xml，例如AccountService：

$curl -k -u root:0penBmc -H "Content-Type: application/octet-stream" -X GET http://127.0.0.1:8000/redfish/v1/AccountService 
{ 
    "@odata.id": "/ redfish /v1/AccountService”，“@odata.type”：“#AccountService.v1_5_0.AccountService”， 
    “AccountLockoutDuration”：300，
    “AccountLockoutThreshold”：10，
    “Accounts”：{
    

@odata.type 格式：#< ResourceType>.< MajorVersion _MinorVersion_ErrataVersion>.<TermName>

因此"@odata.type": "#AccountService.v1_5_0.AccountService"对应到的schema 文件就是 AccountService_v1.xml ，所以其实从AccountService.v1.0.0到目前最新的AccountService.v1.4.0 对应的csdl 文件都是AccountService_v1.xml 

CSDL format

CSDL 文件可以根据标记先分为两个部分，Referencing other CSDL files 和  CSDL data services

我们直接看CSDL data services的部分， </DataServices> 标记中的内容就是CSDL data services，里面使用</Schema > 标记来定义Schema，使用Namespace属性来声明namespace的名称。

</Schema > 中的Namespace分为两类 unversioned  和 versioned 

• unversioned resource and resource collection definitions  <ResourceType>
  放一些共同的属性，例如uri，可否Delete、Update or Insert
• versioned resource definitions <ResourceType>.v<MajorVersion>_<MinorVersion>_<Errata>
  这边会定义property有哪些和他们对应的属性

Elements of CSDL namespaces

Qualified names

如果想要参考或继承某特定</schema>中的element，那该element的 Qualified names就会是

<Namespace>.<TypeName>

其中

• <Namespace> is the namespace name.
• <TypeName> is the name of the element in the namespace.

Entity type and complex type elements

</Schema > 中能使用</EntityType> 和</ComplexType> 标签分别定义entity type 和complex type 元素。标签内可以用</Property> 或是</NavigationProperty>

ComplexType 通常是给EntityType引用的，底下我用 /redfish/v1/Managers/bmc/NetworProtocol 为例子，它的ResourceType是 ManagerNetworkProtocol ，可以看到他的架构大概是

ManagerNetworkProtocol (EntityType)
|__FQDN
|__ HTTP
|     | _Protocol ( ComplexType)
|

这边的HTTP 的Type 指向 ManagerNetworkProtocol.v1_0_0.Protocol，所以要到<Schema namespace=ManagerNetworkProtocol.v1_0_0 > 中找到<ComplexType Name= Protocol >

在<ComplexType Name=Protocol >中会定义结构，例如它有两个property ，ProtocolEnabled 和 Port，他们的type 分别是bool和int 

那其實還有很多內容，這邊就不多介紹了，詳細可以看DMTF出的教學 Redfish_School-Introduction_to_CSDL (dmtf.org) ，或是Redfish Spec

Redfish Services validator

GitHub - DMTF/Redfish-Service-Validator: The Redfish Service Validator is a Python3 tool for checking conformance of any "device" with a Redfish service interface against Redfish CSDL schema

下载

git clone https://github.com/DMTF/Redfish-Service-Validator.git

不用安装，直接执行

python3 RedfishServiceValidator.py -i https://{bmcip} -u {id}-p {password}

如果执行失败，可能是少装了一些library

python3 -m pip install redfish
python3 -m pip install bs4
python3 -m pip install lxml

执行期间它会GET 所有能见的Resource，之后就会产生报告了

 

常见被验出的问题

ERROR - Attributes: Property is null but is not Nullable

Nullable="false" 表示当property存在时，它的值不可为空

ERROR - XXX: Expected int, got type class 'str' (Type Error)

"0" 这是字串，0 这是数字，这条我还真遇过类似的

ERROR - Namespace of type xxx appears missing from SchemaXML xxx.xml, attempting highest type: #xxx.xxx.xxx
ERROR - New namespace: xxx.v1_0_2

这条其实蛮重点的，validator 会根据@odata.type去抓你的ResourceType和其版本，当它在CSDL 中找不到匹配的namespace 的时候，就会出现一排Error，这只是其中两条

那validator 拿来做验证的CSDL 文件是网路上下载的，还是BMC吐给他的？答案是用网路上或你指定的Schema folder来做验证的，所以我最后在validator 指向的Schema folder 中加上namespace 其实就可以pass了

 我目前想到的大概就这些