From c77360ff6f178c5f7d7571e8701cb6d958904ef0 Mon Sep 17 00:00:00 2001 From: Ilya Etingof Date: Tue, 12 Mar 2019 18:21:23 +0100 Subject: [PATCH] Add docs on UEFI boot libvirt-based emulation Change-Id: I44ceed5b0b37c6ca169d6aa5d7e30ed123445129 --- doc/source/user/dynamic-emulator.rst | 205 +++++++++++++++++++++++++++ doc/source/user/index.rst | 188 ++---------------------- doc/source/user/static-emulator.rst | 44 ++++++ 3 files changed, 257 insertions(+), 180 deletions(-) create mode 100644 doc/source/user/dynamic-emulator.rst create mode 100644 doc/source/user/static-emulator.rst diff --git a/doc/source/user/dynamic-emulator.rst b/doc/source/user/dynamic-emulator.rst new file mode 100644 index 00000000..8997a056 --- /dev/null +++ b/doc/source/user/dynamic-emulator.rst @@ -0,0 +1,205 @@ + +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. The following command will create a new +virtual machine i.e. libvirt domain `vbmc-node`: + +.. code-block:: bash + + tmpfile=$(mktemp /tmp/sushy-domain.XXXXXX) + virt-install \ + --name vbmc-node \ + --ram 1024 \ + --disk size=1 \ + --vcpus 2 \ + --os-type linux \ + --os-variant fedora28 \ + --graphics vnc \ + --print-xml > $tmpfile + virsh define --file $tmpfile + rm $tmpfile + +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*. + +UEFI boot ++++++++++ + +By default, `legacy` or `BIOS` mode is used to boot the instance. However, +libvirt domain can be configured to boot via UEFI firmware. This process +requires additional preparation on the host side. + +On the host you need to have OVMF firmware binaries installed. Fedora users +could pull them as `edk2-ovmf` RPM. On Ubuntu, `apt-get install ovmf` should +do the job. + +Then you need to create a VM by running `virt-install` with the `--boot uefi` +option: + +Example: + +.. code-block:: bash + + tmpfile=$(mktemp /tmp/sushy-domain.XXXXXX) + virt-install \ + --name vbmc-node \ + --ram 1024 \ + --boot uefi \ + --disk size=1 \ + --vcpus 2 \ + --os-type linux \ + --os-variant fedora28 \ + --graphics vnc \ + --print-xml > $tmpfile + virsh define --file $tmpfile + rm $tmpfile + +This will create a new `libvirt` domain with path to OVMF images properly +configured. Let's take a note on the path to the blob: + +.. code-block:: bash + + $ virsh dumpxml vbmc-node | grep loader + /usr/share/edk2/ovmf/OVMF_CODE.fd + +Because now we need to add this path to emulator's configuration matching +VM architecture we are running. Make a copy of stock configuration file +and edit it accordingly: + +.. code-block:: bash + + $ cat sushy-tools/doc/source/admin/emulator.conf + ... + SUSHY_EMULATOR_BOOT_LOADER_MAP = { + 'Uefi': { + 'x86_64': '/usr/share/edk2/ovmf/OVMF_CODE.fd', + ... + } + ... + +Now you can run `sushy-emulator` with the updated configuration file: + +.. code-block:: bash + + sushy-emulator --config emulator.conf + +.. note:: + + The images you will serve to your VMs need to be UEFI-bootable. + +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 Virtual 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 emulator alongside the +`openstackbmc `_ +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 Virtual 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. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 8071f41b..f1106eb8 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -2,186 +2,14 @@ Using Redfish emulators ======================= -The sushy-tools package includes two emulators - static Redfish responder -and virtual Redfish BMC that is backed by libvirt or OpenStack cloud. +The sushy-tools package includes two emulators - static and dynamic. -Static Redfish BMC ------------------- +Static emulator could be used to serve Redfish mocks in form of static +JSON documents. Dynamic emulator relies upon either `libvirt` or `OpenStack` +virtualization backend to mimic baremetal nodes behind 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. +.. toctree:: + :maxdepth: 2 -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 emulator 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 Virtual 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 emulator 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 Virtual 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 `_. + static-emulator + dynamic-emulator diff --git a/doc/source/user/static-emulator.rst b/doc/source/user/static-emulator.rst new file mode 100644 index 00000000..652c061a --- /dev/null +++ b/doc/source/user/static-emulator.rst @@ -0,0 +1,44 @@ + +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 emulator 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. +