RECS Box Management API christmann informationstechnik + medien GmbH & Co. KG 14. März 2014 Dieses Dokument beschreibt die RECS Box Management API zur Überwachung und zum Management der einzelnen Komponenten in einer RECS Box. Ziel des Designs ist eine möglichst einfach nutzbare API. 1. Komponenten Die RECS Box Management API bildet die verschiedenen Hardwarekomponenten in die Software ab. Derzeit unterstützt die API folgende Komponenten: node Ein einzelner Rechner baseboard Ein Baseboard kann (derzeit) ein x86-modul oder vier ARM-Module fassen rcu RECS Compute Unit, eine dieser Einheiten kann bis zu 18 Baseboards fassen rack Ein Schrank, bestehend aus mehreren RCUs. Informationen über diese Komponenten werden als XML Code zurück gegeben. Eine genaue Beschreibung der Rückgabetypen kann Anhang A entnommen werden. 1.1. Node Abbildung 1 stellt die Attribute eines Rechners grafisch dar. Die einzelnen Attribute haben folgende Bedeutung: id im System eindeutige ID zur Referenzierung der Komponente actualpowerusage aktuelle Stromaufnahme des Rechners zum Zeitpunkt der letzten Messung in Watt maxpowerusage maximale Stromaufnahme, die der Rechner anfordern kann baseboardid ID des Baseboards, welches den Rechner beherbergt baseboardposition Position des Rechners auf dem Baseboard 1
Abbildung 1: Graphische Darstellung der Informationen eines Rechners state Status des Rechners (eingeschaltet, ausgeschaltet, Suspend to RAM, Suspend to Disk) architecture Architektur (x86, x86 32, x86 64, arm) temperature Temperatur des Rechners in health Gesundheitszustand des Rechners (OK, Warning, Critical) inlettemperature Temperatur der Ansaugluft in outlettemperature Temperatur der Abluft in voltage Versorgungsspannung in Volt description Beschreibung der Komponente Passend zur Komponente node gibt es eine Komponente nodevector, welche mehrere Instanzen von node zurückliefern kann. 1.2. Baseboard Abbildung 2 stellt die Attribute eines baseboard grafisch dar. Die einzelnen Attribute haben folgende Bedeutung: id im System eindeutige ID zur Referenzierung der Komponente rcuid ID der RECS Box Computing Unit, welche das Baseboard beherbergt rcuposition Position des Baseboards in der RECS Box Computing Unit infrastructurepower Stromverbrauch der Infrastrukturkomponenten auf dem Baseboard in Watt 2
Abbildung 2: Graphische Darstellung der Informationen eines Baseboards Abbildung 3: Graphische Darstellung der Informationen einer RECS Box Computing Unit baseboardtyoe Typ des Baseboards (CXP, APLS) description Beschreibung der Komponente nodeid Pro Rechner auf dem Baseboard ein Eintrag mit dessen ID Passend zur Komponente baseboard gibt es eine Komponente baseboardvector, welche mehrere Instanzen von baseboard zurückliefern kann. 1.3. RCU Abbildung 3 stellt die Attribute einer RECS Box Computing Unit grafisch dar. Die einzelnen Attribute haben folgende Bedeutung: id im System eindeutige ID zur Referenzierung der Komponente rackid ID des Racks, welches die RECS Box Computing Unit beherbergt 3
Abbildung 4: Graphische Darstellung der Informationen eines Racks rackposition Position der RECS Box Computing Unit im Rack name Name der RECS Box Computing Unit rcutype Typ der RECS Box Computing Unit (SIRIUS, ARNEB, ANTARES) kvmnode ID des Rechners, der aktuell auf die KVM-Anschlüsse der RCU geroutet ist description Beschreibung der Komponente baseboardid Pro Baseboard in der RECS Box Computing Unit ein Eintrag mit dessen ID Passend zur Komponente rcu gibt es eine Komponente rcuvector, welche mehrere Instanzen von rcu zurückliefern kann. 1.4. Rack Abbildung 4 stellt die Attribute eines Racks grafisch dar. Die einzelnen Attribute haben folgende Bedeutung: id im System eindeutige ID zur Referenzierung der Komponente description Beschreibung der Komponente rcuid Pro RECS Box Computing Unit im Rack ein Eintrag mit dessen ID Passend zur Komponente rack gibt es eine Komponente rackvector, welche mehrere mehrere Instanzen von rack zurückliefern kann. 2. Zugriff Die RECS Box Management API ist über die IP-Adresse bzw. den Hostname des TOR-Masters des Verbundes erreichbar. Die Basis-URL der Schnittstelle lautet http: //TOR-Master/REST. 4
3. Ressourcen Die Ressourcen unterteilen sich in reine Abfragen zur Überwachung und in änderbare Ressourcen zum Management. 3.1. Überwachung Zur Überwachung stehen folgende Ressourcen zur Verfügung: /node Gibt einen nodevector mit allen Rechnern im System zurück. /node/{node id} Gibt Informationen über den Rechner mit der gegebenen ID als node zurück. /baseboard Gibt einen baseboardvector mit allen Baseboards im System zurück. /baseboard/{baseboard id} Gibt Informationen über das Baseboard mit der gegebenen ID als baseboard zurück. /baseboard/{baseboard id}/node Gibt einen nodevector mit allen Rechnern zurück, die zu dem Baseboard mit der gegebenen ID gehören. /rcu Gibt einen rcuvector mit allen RECS Box Computing Units im System zurück. /rcu/{rcu id} Gibt Informationen über die RECS Box Computing Unit mit der gegebenen ID als rcu zurück. /rcu/{rcu id}/baseboard Gibt einen baseboardvector mit allen Baseboards zurück, die zu der RECS Box Computing Unit mit der gegebenen ID gehören. /rack Gibt einen rackvector mit allen Racks im System zurück. /rack/{rack id} Gibt Informationen über das Rack mit der gegebenen ID als rack zurück. /rack/{rack id}/rcu Gibt einen rcuvector mit allen RECS Box Computing Units zurück, die zu dem Rack mit der gegebenen ID gehören. 3.2. Management Das Management der jeweiligen Komponente findet sich jeweils unterhalb der Subadresse manage. Derzeit sind nur für die Rechner Managementfunktionen implementiert: /node/{node id}/manage/power on Schaltet den Rechner mit der gegebenen ID ein und gibt die aktualisierten Informationen des Rechners als node zurück. /node/{node id}/manage/power off Schaltet den Rechner mit der gegebenen ID aus und gibt die aktualisierten Informationen des Rechners als node zurück. 5
/node/{node id}/manage/reset Setzt den Rechner mit der gegebenen ID zurück und gibt die aktualisierten Informationen des Rechners als node zurück. /node/{node id}/manage/select kvm Routet den Rechner mit der gegebenen ID auf die KVM-Anschlüsse der zugehörigen RECS Box Computing Unit und gibt die aktualisierten Informationen des Rechners als node zurück. 3.3. Fehler Rückmeldungen über Fehler oder Erfolg von Anfragen erfolgen grundsätzlich durch den HTTP Status Code. Ein Übersicht über die definierten Stati findet sich beispielsweise unter http://www.w3.org/protocols/rfc2616/rfc2616-sec10.html. A. XML Schema der Komponenten Listing 1: XML Beschreibung der Komponenten, welche über die Restful API aufgerufen werden können <?xml v e r s i o n= 1. 0 encoding= UTF 8 standalone= yes?> <xs:schema v e r s i o n= 1. 0 xmlns:xs= h t t p : //www. w3. org /2001/ XMLSchema > <x s : e l e m e n t name= baseboard type= baseboard /> <x s : e l e m e n t name= baseboardlist type= baseboardvector /> <x s : e l e m e n t name= node type= node /> <x s : e l e m e n t name= nodelist type= nodevector /> <x s : e l e m e n t name= rack type= rack /> <x s : e l e m e n t name= r a c k L i s t type= rackvector /> <x s : e l e m e n t name= rcu type= rcu /> <x s : e l e m e n t name= r c u L i s t type= rcuvector /> <xs:complextype name= rackvector > <x s : e l e m e n t r e f= rack minoccurs= 0 maxoccurs= unbounded /> 6
<xs:complextype name= rack > <x s : e l e m e n t name= d e s c r i p t i o n type= x s : s t r i n g minoccurs= 0 /> <x s : e l e m e n t name= rcuid type= x s : s t r i n g minoccurs= 0 maxoccurs= unbounded /> <x s : a t t r i b u t e name= id type= x s : s t r i n g /> <xs:complextype name= rcuvector > <x s : e l e m e n t r e f= rcu minoccurs= 0 maxoccurs= unbounded /> <xs: complextype name= r c u > <x s : e l e m e n t name= d e s c r i p t i o n type= x s : s t r i n g minoccurs= 0 /> <x s : e l e m e n t name= baseboardid type= x s : s t r i n g minoccurs= 0 maxoccurs= unbounded /> <x s : a t t r i b u t e name= id type= x s : s t r i n g /> <x s : a t t r i b u t e name= rackid type= x s : s t r i n g /> <x s : a t t r i b u t e name= r a c k P o s i t i o n type= x s : i n t use= r e q u i r e d /> <xs: complextype name= baseboardvector > <x s : e l e m e n t name= rcu type= baseboard minoccurs= 0 maxoccurs= unbounded /> <xs: complextype name= baseboard > <x s : e l e m e n t name= d e s c r i p t i o n type= x s : s t r i n g minoccurs= 0 /> <x s : e l e m e n t name= nodeid type= x s : s t r i n g minoccurs= 0 maxoccurs= unbounded /> <x s : a t t r i b u t e name= id type= x s : s t r i n g /> 7
<x s : a t t r i b u t e name= rcuid type= x s : s t r i n g /> <x s : a t t r i b u t e name= r c u P o s i t i o n type= x s : i n t use= r e q u i r e d /> <xs: complextype name= nodevector > <x s : e l e m e n t r e f= node minoccurs= 0 maxoccurs= unbounded /> <xs: complextype name= node > <x s : e l e m e n t name= d e s c r i p t i o n type= x s : s t r i n g minoccurs= 0 /> <x s : a t t r i b u t e name= actualpowerusage type= x s : d o u b l e use = r e q u i r e d /> <x s : a t t r i b u t e name= baseboeardid type= x s : s t r i n g /> <x s : a t t r i b u t e name= baseboardposition type= x s : i n t use= r e q u i r e d /> <x s : a t t r i b u t e name= id type= x s : s t r i n g /> <x s : a t t r i b u t e name= a r c h i t e c t u r e type= x s : s t r i n g /> <x s : a t t r i b u t e name= maxpowerusage type= x s : d o u b l e use= r e q u i r e d /> <x s : a t t r i b u t e name= s t a t e type= x s : i n t use= r e q u i r e d /> <x s : a t t r i b u t e name= temperature type= x s : d o u b l e use= r e q u i r e d /> </ xs:schema> B. XML Beschreibung der Ressourcen Listing 2: XML Beschreibung der Ressourcen, welche über die Restful API aufgerufen werden können <?xml v e r s i o n= 1. 0 encoding= UTF 8 standalone= yes?> <a p p l i c a t i o n xmlns= h t t p : // wadl. dev. java. net /2009/02 > <doc x m l n s : j e r s e y= h t t p : // j e r s e y. java. net / j e r s e y : g e n e r a t e d B y= J e r s e y : 1.17 01/17/2013 03 : 3 1 PM /> <grammars> <i n c l u d e h r e f= a p p l i c a t i o n. wadl/ xsd0. xsd > <doc t i t l e= Generated xml:lang= en /> </ i n c l u d e> 8
</ grammars> <r e s o u r c e s base= h t t p : // l o c a l h o s t /REST/ > <r e s o u r c e path= / > <r e s o u r c e path= /node > <method i d= getnodes name= GET > /2009/02 xmlns= element= nodelist mediatype= t e x t /xml /> <r e s o u r c e path= /node /{ node }/manage/ power on > node s t y l e= template type= x s : s t r i n g /> <method id= startnode name= GET > /2009/02 xmlns= element= node mediatype= t e x t / xml /> <r e s o u r c e path= /node /{ node }/manage/ r e s e t > node s t y l e= template type= x s : s t r i n g /> <method id= resetnode name= GET > /2009/02 xmlns= element= node mediatype= t e x t / xml /> <r e s o u r c e path= / rcu > <method i d= getrcus name= GET > /2009/02 xmlns= element= r c u L i s t mediatype= t e x t /xml /> <r e s o u r c e path= / rcu /{ rcu } > 9
rcu s t y l e= template type= x s : s t r i n g /> <method i d= getrcu name= GET > <r e p r e s e n t a t i o n mediatype= t e x t /xml /> <r e s o u r c e path= /debugdata > <method id= getmonitoring name= GET > <r e p r e s e n t a t i o n mediatype= a p p l i c a t i o n /xml /> <r e s o u r c e path= / rack /{ rack }/ rcu > rack s t y l e= template type= x s : s t r i n g /> <method i d= getrackrcus name= GET > /2009/02 xmlns= element= r c u L i s t mediatype= t e x t /xml /> <r e s o u r c e path= /node /{ node }/manage/ select kvm > node s t y l e= template type= x s : s t r i n g /> <method i d= selectkvmnode name= GET > /2009/02 xmlns= element= node mediatype= t e x t / xml /> <r e s o u r c e path= /node /{ node }/manage/ p o w e r o f f > node s t y l e= template type= x s : s t r i n g /> <method i d= stopnode name= GET > /2009/02 xmlns= element= node mediatype= t e x t / xml /> 10
<r e s o u r c e path= / baseboard /{ baseboard } > baseboard s t y l e= template type= x s : s t r i n g /> <method i d= getbaseboard name= GET > /2009/02 xmlns= element= baseboard mediatype= t e x t /xml /> <r e s o u r c e path= / rack /{ rack } > rack s t y l e= template type= x s : s t r i n g /> <method i d= getrack name= GET > /2009/02 xmlns= element= rack mediatype= t e x t / xml /> <r e s o u r c e path= / baseboard > <method i d= getbaseboards name= GET > /2009/02 xmlns= element= baseboardlist mediatype = t e x t /xml /> <r e s o u r c e path= / rack > <method i d= getracks name= GET > /2009/02 xmlns= element= r a c k L i s t mediatype= t e x t /xml /> <r e s o u r c e path= / baseboard /{ baseboard }/ node > 11
baseboard s t y l e= template type= x s : s t r i n g /> <method i d= getbasebordnodes name= GET > /2009/02 xmlns= element= nodelist mediatype= t e x t /xml /> <r e s o u r c e path= / rcu /{ rcu }/ baseboard > rcu s t y l e= template type= x s : s t r i n g /> <method i d= getrcubaseboards name= GET > /2009/02 xmlns= element= baseboardlist mediatype = t e x t /xml /> <r e s o u r c e path= /node /{ node} > node s t y l e= template type= x s : s t r i n g /> <method i d= getnode name= GET > /2009/02 xmlns= element= node mediatype= t e x t / xml /> </ r e s o u r c e s> </ a p p l i c a t i o n> 12