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 怎麼描述，所以這篇文章的大鋼如下

• CSDL schema
• Redfish Services validator 
• 下載
• 執行
• 常見被驗出的問題 (這邊我想到的不多)

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

*如果對Redfish schema 和 specifications 的概念不太清楚的話，可參考 如何描述 Redfish 版本

OData CSDL (Common Schema Definition Language)

Overview

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了

我目前想到的就這些