stx-metal team,
As a result of time spent within stx-metal, we have some initial questions
with respect to documentation and source code so we are kindly requesting your
comments for questions "?" under each section [ Section ] [Sub Section]
Please assume:
- The require X-Auth-Token is in place to authenticate, only URLs might be shown.
- StarlingX is configured as Standard Controller: 2 Controllers, 2 Computes.
[ Project Information ]
When we look at the name and description reported out by
curl -i http://10.10.10.2:6385/
there is a mismatch between documentation [0] and information via API Query:
API Documentation:
Name: StarlingX SysInv API
Description: StarlingX System API allows for the management of physical servers.
This includes inventory collection and configuration of hosts, ports, interfaces, CPUs,
disk, memory, and system configuration.
The API also supports the configuration of the cloud's SNMP interface.
Source Code via API Query:
Name: Titanium SysInv API
Description: Titanium Cloud System API allows for the management of physical servers.
This includes inventory collection and configuration of hosts, ports, interfaces, CPUs,
disk, memory, and system configuration.
The API also supports alarms and fault collection for the cloud itself as well as the
configuration of the cloud's SNMP interface.
? Can you please let us know where the modifications are required? API Documentation
or Source Code?
[ v1/ ]
Here we are showing 3 different views of what we are seeing within stx-metal
project:
- Our initial "Migration WADL to RST", see history here [1]
- What we have documented in our "Current Official API Documentation" pages [0]
- What the "API Query Output" is actually showing with
curl -i http://10.10.10.2:6385/v1/...
[ v1/ ] [ Migration WADL to RST ]
Migration analysis from WADL to RST format gave us the endpoints below to include,
we are adding in the second column what it seems to be the match for the valid
API endpoint name:
Hosts > ihosts
Ports > ports
CPUs > icpu
Memory > imemorys
Disks > idisks
SensorGroup > isensorgroups
Sensor > isensors
LLDP Agents > lldp_agents
LLDP Neighbors > lldp_neighbours
? Are all the names and API nodes correctly matched?
? Are all the valid API node names correct? E.g. imemorys Vs imemories
[ v1/ ] [ Current Official API Documentation ]
Current Official API documentation [0] includes the following 5 endpoints
under "API Versions" v1/ details:
- LLDP Neighbors: http://10.10.10.2:6385/v1/lldp_neighbours/
- Hosts: http://10.10.10.2:6385/v1/ihosts/
- CPUs: http://10.10.10.2:6385/v1/icpu/
- LLDP Agents: http://10.10.10.2:6385/v1/lldp_agents/
- Ports: http://10.10.10.2:6385/v1/iports/
? All of them are valid endpoints except for:
- icpu is not found, the correct working endpoint is:
http://10.10.10.2:6385/v1/icpus/
- iports is not found, the correct working endpoint is:
http://10.10.10.2:6385/v1/ports/
Any objection to make the documentation change?
The following 3 endpoints are not shown under "API Versions" v1/ details but they
have a valid top level v1/ endpoint:
- Memory Documentation pointing to: /v1/ihosts/{host_id}/imemorys
and a valid top level v1/ endpoint: http://10.10.10.2:6385/v1/imemorys/
- SensorGroup Documentation pointing to: /v1/ihosts/{host_id}/isensorgroups
and a valid top level v1/ endpoint: http://10.10.10.2:6385/v1/isensorgroups/
- Sensor Documentation pointing to: /v1/ihosts/{host_id}/isensors
and a valid top level v1/ endpoint: http://10.10.10.2:6385/v1/isensors/
? Since they a valid top level v1/ endpoint, do we need to add them under our
"API Versions" v1/ details documentation [2]?
idisks does not have a valid v1/ endpoint, it is accessed only through v1/ihosts:
- Disks > http://10.10.10.2:6385/v1/ihosts/{host_id}/idisks/
? It seems ok, anything to add here? anything to modify?
[ v1/ ] [ API Query Output ]
API queries output shows these endpoints:
- lldp_neighbours
- ihosts
- icpu
- lldp_agents
Plus additional ones, some other are assigned to other StarlingX repos:
- firewallrules
- addresses
- links
- remotelogging
- ceph_mon
- itrapdest
- iextoam
- intp
- storage_file
- storage_lvm
- interface_networks
- inode
- id
- ptp
- media_types
- servicegroup
- upgrade
- imemory
- networks
- storage_ceph_external
- health
- clusters
- drbdconfig
- icommunity
- helm_charts
- iprofile
- servicenodes
- iinfra
- storage_backend
- controller_fs
- services
- sdn_controller
- addrpools
- license
- service_parameter
- storage_ceph
- idns
- isystems
- storage_external
- iuser
Important!
Focusing on endpoints related to stx-metal, let's take a look at this
v1/ API Query Output and choose "imemory":
"imemory": [
{
"href": "http://10.10.10.2:6385/v1/imemory/",
"rel": "self"
},
{
"href": "http://10.10.10.2:6385/imemory/",
"rel": "bookmark"
}
],
When we query "imemory" endpoint based in the information presented above,
we find this endpoint as not valid, knowing from previous procedures the
endpoint name "imemorys" is the valid one.
? Do we need another level of review?
? Should we target an update to the documentation in terms of number
of services we are documenting comparing the 3 perspectives?
[ v1/ihosts ]
Some fields might be different. API Documentation does not include the field "tboot"
but our API query shows this "tboot" field under each host:
"tboot": "false",
? Is this different since it could have been queried in a AIO Vs a our Controller Storage?
In general:
? Is there any need to go deeper into reviewing the content fo the rest of the endpoints outputs?
We understand this might be a job for the API testing @ Zuul so let us know how can we help from
the documentation perspective.
? Anything else to add? mention? required?
Thanks for your initial support.
[0] https://docs.starlingx.io/api-ref/stx-metal/
[1] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Analysis
[2] https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#api-versions
[3] https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#memory
_______________________________________________
Starlingx-discuss mailing list
Starlingx-discuss@lists.starlingx.io
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss