From a6eeeb82e32d401fd4e8c9ce0a6e209862c681dd Mon Sep 17 00:00:00 2001 From: Lucas Alvares Gomes Date: Wed, 15 Feb 2017 14:02:35 +0000 Subject: [PATCH] Add some documentation about VirtualBMC and pxe_ipmitool This patch is adding some information about what is VirtualBMC, how it can be setup and how one could migrate a cloud from pxe_ssh to pxe_ipmitool + VirtualBMC. The patch also add notes about the deprecation of the pxe_ssh driver. Co-Authored-By: Dmitry Tantsur Change-Id: Ia023278744d937406101746905da2716e4e72b68 --- .../baremetal_overcloud.rst | 45 ++++--- doc/source/environments/baremetal.rst | 30 +++-- doc/source/environments/environments.rst | 1 + doc/source/environments/virtualbmc.rst | 113 ++++++++++++++++++ doc/source/introduction/components.rst | 15 +++ 5 files changed, 179 insertions(+), 25 deletions(-) create mode 100644 doc/source/environments/virtualbmc.rst diff --git a/doc/source/advanced_deployment/baremetal_overcloud.rst b/doc/source/advanced_deployment/baremetal_overcloud.rst index 566ff396..912f2010 100644 --- a/doc/source/advanced_deployment/baremetal_overcloud.rst +++ b/doc/source/advanced_deployment/baremetal_overcloud.rst @@ -40,12 +40,13 @@ three nodes in the ``instackenv.json``, you can split them:: The format of the remaining nodes is TripleO-specific, so we need to convert it to something Ironic can understand without using -TripleO workflows:: +TripleO workflows. E.g. for node using IPMI:: jq '.nodes[2:3] | {nodes: map({driver: .pm_type, name: .name, - driver_info: {ssh_username: .pm_user, ssh_address: .pm_addr, - ssh_key_contents: .pm_password, ssh_virt_type: "virsh"}, - properties: {cpus: .cpu, cpu_arch: .arch, local_gb: .disk, memory_mb: .memory}, + driver_info: {ipmi_username: .pm_user, ipmi_address: .pm_addr, + ipmi_password: .pm_password}, + properties: {cpus: .cpu, cpu_arch: .arch, + local_gb: .disk, memory_mb: .memory}, ports: .mac | map({address: .})})}' instackenv.json > overcloud-nodes.yaml .. note:: @@ -53,6 +54,12 @@ TripleO workflows:: TripleO-specific, e.g. they force local boot instead of network boot used by default in Ironic. +.. note:: + If you use :doc:`../environments/virtualbmc`, make sure to follow + :ref:`create-vbmc` for the overcloud nodes as well, and correctly populate + ``ipmi_port``. If needed, change ``ipmi_address`` to the address of the + virtual host, which is accessible from controllers. + Then enroll only ``undercloud.json`` in your undercloud:: source stackrc @@ -92,21 +99,27 @@ environment file (``ironic-config.yaml`` in this guide): .. admonition:: Virtual :class: virtual - Testing on a virtual environment requires the ``pxe_ssh`` driver to be - explicitly enabled, for example:: + Starting with the Ocata release, testing on a virtual environment + requires using :doc:`../environments/virtualbmc`. - parameter_defaults: - IronicEnabledDrivers: - - pxe_ssh + .. admonition:: Stable Branches + :class: stable - If you used **tripleo-quickstart** to build your environment, the - resulting configuration is a bit different:: + Before the Ocata release, a separate ``pxe_ssh`` driver has to be + enabled for virtual testing, for example:: - parameter_defaults: - IronicEnabledDrivers: - - pxe_ssh - ControllerExtraConfig: - ironic::drivers::ssh::libvirt_uri: 'qemu:///session' + parameter_defaults: + IronicEnabledDrivers: + - pxe_ssh + + If you used **tripleo-quickstart** to build your environment, the + resulting configuration is a bit different:: + + parameter_defaults: + IronicEnabledDrivers: + - pxe_ssh + ControllerExtraConfig: + ironic::drivers::ssh::libvirt_uri: 'qemu:///session' * ``NovaSchedulerDefaultFilters`` configures available scheduler filters. For a hybrid deployment it's important to prepend diff --git a/doc/source/environments/baremetal.rst b/doc/source/environments/baremetal.rst index 1dc8d5df..8095280b 100644 --- a/doc/source/environments/baremetal.rst +++ b/doc/source/environments/baremetal.rst @@ -247,17 +247,29 @@ The most up-to-date information about Ironic drivers is at http://docs.openstack.org/developer/ironic/deploy/drivers.html, but note that this page always targets Ironic git master, not the release we use. -There are 2 generic drivers: +This most generic driver is ``pxe_ipmitool``. It uses `ipmitool`_ utility +to manage a bare metal node, and supports a vast variety of hardware. -* ``pxe_ipmitool`` driver uses `ipmitool`_ utility to manage a bare metal - node, and supports vast variety of hardware. +.. admonition:: Virtual + :class: virtual -* ``pxe_ssh`` is a special driver for testing Ironic in the virtual - environment. This driver connects to the hypervisor to conduct management - operations on virtual nodes. In case of this driver, ``pm_addr`` is a - hypervisor address, ``pm_user`` is a SSH user name for accessing hypervisor, - ``pm_password`` is a private SSH key for accessing hypervisor. Note that - private key must not be encrypted. + When combined with :doc:`virtualbmc` this driver can be used for developing + and testing TripleO in a virtual environment as well. + + .. admonition:: Stable Branch + :class: stable + + Prior to the Ocata release, a special ``pxe_ssh`` driver was used for + testing Ironic in the virtual environment. This driver connects to the + hypervisor to conduct management operations on virtual nodes. In case of + this driver, ``pm_addr`` is a hypervisor address, ``pm_user`` is a SSH + user name for accessing hypervisor, ``pm_password`` is a private SSH + key for accessing hypervisor. Note that private key must not be + encrypted. + + .. warning:: + The ``pxe_ssh`` driver is deprecated and ``pxe_ipmitool`` + + :doc:`virtualbmc` should be used instead. Ironic also provides specific drivers for some types of hardware: diff --git a/doc/source/environments/environments.rst b/doc/source/environments/environments.rst index 6814bcbf..ef979a95 100644 --- a/doc/source/environments/environments.rst +++ b/doc/source/environments/environments.rst @@ -9,3 +9,4 @@ section contains instructions on how to setup your environments properly. virtual baremetal + virtualbmc diff --git a/doc/source/environments/virtualbmc.rst b/doc/source/environments/virtualbmc.rst new file mode 100644 index 00000000..e21976aa --- /dev/null +++ b/doc/source/environments/virtualbmc.rst @@ -0,0 +1,113 @@ +VirtualBMC +========== + +VirtualBMC_ is a small CLI that allows users to create a virtual BMC_ +to manage a virtual machines using the IPMI_ protocol, similar to how real +bare metal machines are managed. It can be used to to enable testing +bare metal deployments in completely virtual environments. + +.. admonition:: Stable Branch + :class: stable + + Ironic also ships a ``pxe_ssh`` driver that can be used for that purpose, + but it has been deprecated and its use is discouraged. + +.. warning:: + VirtualBMC is not meant for production environments. + +Installation +------------ + +VirtualBMC is available from RDO repositories starting with the Ocata release:: + + sudo yum install -y python-virtualbmc + +It is usually installed and used on the hypervisor where the virtual machines +reside. + +.. _create-vbmc: + +Creating virtual BMC +-------------------- + +Every virtual machine needs its own virtual BMC. Create it with:: + + vbmc add --port 6230 --username admin --password password + +.. note:: + You need to use a different port for each domain. Port numbers + lower than 1025 requires the user to have root privilege in the system. + +.. note:: + For **tripleo-quickstart** you may have to specify + ``--libvirt-uri=qemu:///session``. + +Start the virtual BMCs:: + + vbmc start + +.. warning:: + This step has to be repeated after virtual host reboot. + +Test the virtual BMC to see if it's working. For example, to power on +the virtual machine do:: + + ipmitool -I lanplus -U admin -P password -H 127.0.0.1 -p 6230 power on + +Enrolling virtual machines +-------------------------- + +In the undercloud, populate the ``instackenv.json`` with new "bare metals" +in a similar way to real bare metal machines (see :ref:`instackenv`) with +two exceptions: + +* set ``pm_port`` to the port you specified when `Creating virtual BMC` + +* populate ``mac`` field even if you plan to use introspection + +For example: + +.. code-block:: json + + { + "nodes": [ + { + "pm_type": "pxe_ipmitool", + "mac": [ + "00:0a:f2:88:12:aa" + ], + "pm_user": "admin", + "pm_password": "password", + "pm_addr": "172.16.0.1", + "pm_port": "6230", + "name": "compute-0" + } + ] + } + +Migrating from pxe_ssh to VirtualBMC +------------------------------------ + +If you already have a virtual cloud deployed and want to migrate from the +deprecated ``pxe_ssh`` driver to ``pxe_ipmitool`` using VirtualBMC, +follow `Creating virtual BMC`_, then update the existing nodes to change +their drivers and certain driver properties: + +.. code-block:: bash + + openstack baremetal node set $NODE_UUID_OR_NAME \ + --driver pxe_ipmitool \ + --driver-info ipmi_address= \ + --driver-info ipmi_port= \ + --driver-info ipmi_username="admin" \ + --driver-info ipmi_password="password" + +Then check that everything is populated properly: + +.. code-block:: bash + + openstack baremetal node validate $NODE_UUID_OR_NAME | grep power + +.. _VirtualBMC: https://git.openstack.org/cgit/openstack/virtualbmc +.. _IPMI: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface +.. _BMC: https://en.wikipedia.org/wiki/Baseboard_management_controller diff --git a/doc/source/introduction/components.rst b/doc/source/introduction/components.rst index d3952429..52c46f0e 100644 --- a/doc/source/introduction/components.rst +++ b/doc/source/introduction/components.rst @@ -231,6 +231,21 @@ for details. * Bugs: https://bugs.launchpad.net/ironic-inspector * Blueprints: https://blueprints.launchpad.net/ironic-inspector +VirtualBMC +^^^^^^^^^^ + +A helper command to translate IPMI calls into libvirt calls. Used for testing +bare metal provisioning on virtual environments. + +**How to contribute** + +VirtualBMC uses `tox `_ to manage the +development environment in a similar way to Ironic. + +**Useful links** + +* Source: https://git.openstack.org/cgit/openstack/virtualbmc +* Bugs: https://bugs.launchpad.net/virtualbmc Deployment & Orchestration