diff --git a/README.rst b/README.rst index 89065deb..4441c906 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,24 @@ -=========== -sushy-tools -=========== +========================= +Redfish development tools +========================= -A set of tools to support the development and test of the Sushy library -(https://docs.openstack.org/sushy/) +This is a set of simple simulation tools aiming at supporting the +development and testing of the Redfish protocol implementations and, +in particular, Sushy library (https://docs.openstack.org/sushy/). + +The package ships two simulators - static Redfish responder and +cloud-backed virtual Redfish BMC. + +The static Redfish responder is a simple REST API server which +responds the same things to client queries. It is effectively +read-only. + +The virtual Redfish BMC resembles the real Redfish-controlled bare-metal +machine to some extent. Some client queries are translated to commands that +actually control VM instances simulating bare metal hardware. However some +of the Redfish commands just return static content never touching the +virtualization backend and, for that matter, virtual Redfish BMC is similar +to the static Redfish responser. * Free software: Apache license * Documentation: https://docs.openstack.org/sushy/ diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 662e14b0..09f87d95 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,5 +1,6 @@ -About Sushy Tools -================= +============ +Contributing +============ -.. include:: ../../../README.rst +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 7aa89c8c..18641e7f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,14 +1,19 @@ -Welcome to Sushy Tools documentation! -===================================== +.. include:: ../../README.rst - -The sushy-tools uses the main Sushy documentation, you can access it at the -`OpenStack Documentation `_ site. - -Contents: +Documentation +============= .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - contributor/index + install/index + user/index + contributor/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..66eb86b3 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,17 @@ +.. _installation: + +Installation +============ + +The sushy-tools Python package can be downloaded and installed with *pip*: + +.. code-block:: bash + + $ pip install sushy-tools + +Or, if you have virtualenvwrapper installed: + +.. code-block:: bash + + $ mkvirtualenv sushy-tools + $ pip install sushy-tools diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..3c6c6376 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,185 @@ + +Using Redfish simulators +======================== + +The sushy-tools package includes two simulators - static Redfish responder +and cloud-backed Redfish proxy. + +Static Redfish BMC +------------------ + +The static Redfish responder is a simple REST API server which serves +static contents down to the Redfish client. The tool emulates the +simple read-only BMC. + +The user is expected to supply the Redfish-compliant contents perhaps +downloaded from the `DMTF `_ web site. For +example, +`this .zip archive `_ +includes Redfish content mocks for Redfish 1.0.0. + +.. code-block:: bash + + $ curl -o DSP2043_1.0.0.zip \ + https://www.dmtf.org/sites/default/files/standards/documents/DSP2043_1.0.0.zip + $ unzip -d mockups DSP2043_1.0.0.zip + $ sushy-static -m mockups/public-rackmount + +Once you have the static simulator running, you can use it as it was a +read-only bare-metal controller listening at *localhost:8000* (by default): + +.. code-block:: bash + + $ curl http://localhost:8000/redfish/v1/Systems/ + { + "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", + "Name": "Computer System Collection", + "Members@odata.count": 1, + "Members": [ + { + "@odata.id": "/redfish/v1/Systems/437XR1138R2" + } + ], + "@odata.context": "/redfish/v1/$metadata#Systems", + "@odata.id": "/redfish/v1/Systems", + "@Redfish.Copyright": "Copyright 2014-2016 Distributed Management Task Force, Inc. (DMTF). For the full DMTF copyright policy, see http://www.dmtf.org/about/policies/copyright." + } + +You can mock different Redfish versions as well as different bare-metal +machines by providing appropriate Redfish contents. + +Virtual Redfish BMC +------------------- + +The virtual Redfish BMC is functionally similar to the +`Virtual BMC `_ tool except that the +frontend protocol is Redfish rather than IPMI. The Redfish commands coming +from the client get executed against the virtualization backend. That lets +you control virtual machine instances over Redfish. + +The libvirt backend ++++++++++++++++++++ + +First thing you need is to set up some libvirt-managed virtual machines +(AKA domains) to manipulate. + +.. code-block:: bash + + # virt-install \ + --name vbm-node \ + --ram 1024 \ + --disk path=/var/kvm/images/fedora26.img,size=30 \ + --vcpus 2 \ + --os-type linux \ + --os-variant fedora25 \ + --graphics none \ + --location 'https://dl.fedoraproject.org/pub/fedora/linux/releases/26/Server/x86_64/os/' + +Next you can fire up the Redfish virtual BMC which will listen at +*localhost:8000* (by default): + +.. code-block:: bash + + $ sushy-emulator + * Running on http://localhost:8000/ (Press CTRL+C to quit) + +Now you should be able to see your libvirt domain among the Redfish +*Systems*: + +.. code-block:: bash + + $ curl http://localhost:8000/redfish/v1/Systems/ + { + "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", + "Name": "Computer System Collection", + "Members@odata.count": 1, + "Members": [ + + { + "@odata.id": "/redfish/v1/Systems/vbmc-node" + } + + ], + "@odata.context": "/redfish/v1/$metadata#ComputerSystemCollection.ComputerSystemCollection", + "@odata.id": "/redfish/v1/Systems", + "@Redfish.Copyright": "Copyright 2014-2016 Distributed Management Task Force, Inc. (DMTF). For the full DMTF copyright policy, see http://www.dmtf.org/about/policies/copyright." + +You should be able to flip its power state via the Redfish call: + +.. code-block:: bash + + $ curl -d '{"ResetType":"On"}' \ + -H "Content-Type: application/json" -X POST \ + http://localhost:8000/redfish/v1/Systems/vbmc-node/Actions/ComputerSystem.Reset + + $ curl -d '{"ResetType":"ForceOff"}' \ + -H "Content-Type: application/json" -X POST \ + http://localhost:8000/redfish/v1/Systems/vbmc-node/Actions/ComputerSystem.Reset + +You can have as many domains as you need. The domains can be concurrently +managed over Redfish and some other tool like +`Virtual BMC `_. + +The OpenStack backend ++++++++++++++++++++++ + +You can use an OpenStack cloud instances to simulate Redfish-managed +baremetal machines. This setup is known under the name of +`OpenStack Virtial Baremetal `_. +We will largely re-use its OpenStack infrastructure and configuration +instructions. After all, what we are trying to do here is to set up the +Redfish simulator alongside the +`openstackvbmc `_ +tool which is used for exactly the same purpose at OVB with the only +difference that it works over the *IPMI* protocol as opposed to *Redfish*. + +The easiest way is probably to set up your OpenStack Virtial Baremetal cloud +by following +`its instructions `_. + +Once your OVB cloud operational, you log into the *BMC* instance and +:ref:`set up sushy-tools ` there. + +Next you can invoke the Redfish virtual BMC pointing it to your OVB cloud: + +.. code-block:: bash + + $ sushy-emulator --os-cloud rdo-cloud + * Running on http://localhost:8000/ (Press CTRL+C to quit) + +By this point you should be able to see your OpenStack instances among the +Redfish *Systems*: + +.. code-block:: bash + + $ curl http://localhost:8000/redfish/v1/Systems/ + { + "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", + "Name": "Computer System Collection", + "Members@odata.count": 1, + "Members": [ + + { + "@odata.id": "/redfish/v1/Systems/vbmc-node" + } + + ], + "@odata.context": "/redfish/v1/$metadata#ComputerSystemCollection.ComputerSystemCollection", + "@odata.id": "/redfish/v1/Systems", + "@Redfish.Copyright": "Copyright 2014-2016 Distributed Management Task Force, Inc. (DMTF). For the full DMTF copyright policy, see http://www.dmtf.org/about/policies/copyright." + +And flip its power state via the Redfish call: + +.. code-block:: bash + + $ curl -d '{"ResetType":"On"}' \ + -H "Content-Type: application/json" -X POST \ + http://localhost:8000/redfish/v1/Systems/vbmc-node/Actions/ComputerSystem.Reset + + $ curl -d '{"ResetType":"ForceOff"}' \ + -H "Content-Type: application/json" -X POST \ + http://localhost:8000/redfish/v1/Systems/vbmc-node/Actions/ComputerSystem.Reset + +You can have as many OpenStack instances as you need. The instances can be +concurrently managed over Redfish and functionally similar tools like +`Virtual BMC `_.