diff --git a/install-guide/source/advanced.rst b/install-guide/source/advanced.rst index 9ddf4e7079..fc0c1461ef 100644 --- a/install-guide/source/advanced.rst +++ b/install-guide/source/advanced.rst @@ -1,7 +1,7 @@ .. _advanced: Advanced features -~~~~~~~~~~~~~~~~~ +================= .. include:: include/local-boot-partition-images.rst @@ -9,6 +9,12 @@ Advanced features .. include:: include/kernel-boot-parameters.rst +.. include:: include/boot-mode.rst + +.. include:: include/disk-label.rst + .. include:: include/trusted-boot.rst .. include:: include/notifications.rst + +.. include:: include/console.rst diff --git a/install-guide/source/configure-ipmi.rst b/install-guide/source/configure-ipmi.rst new file mode 100644 index 0000000000..7412ecaad0 --- /dev/null +++ b/install-guide/source/configure-ipmi.rst @@ -0,0 +1,78 @@ +Configuring IPMI support +------------------------ + +Installing ipmitool command +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable one of the drivers that use IPMI_ protocol for power and management +actions (e.g. ``ipmi``, ``pxe_ipmitool`` and ``agent_ipmitool``), the +``ipmitool`` command must be present on the service node(s) where +``ironic-conductor`` is running. On most distros, it is provided as part +of the ``ipmitool`` package. Source code is available at +http://ipmitool.sourceforge.net/. + +.. warning:: + Certain distros, notably Mac OS X and SLES, install ``openipmi`` + instead of ``ipmitool`` by default. This driver is not compatible with + ``openipmi`` as it relies on error handling options not provided by + this tool. + +Check that you can connect to, and authenticate with, the IPMI +controller in your bare metal server by running ``ipmitool``:: + + ipmitool -I lanplus -H -U -P chassis power status + +where ```` is the IP of the IPMI controller you want to access. +This is not the bare metal node's main IP. The IPMI controller should have +its own unique IP. + +If the above command doesn't return the power status of the +bare metal server, check that + +- ``ipmitool`` is installed and is available via the ``$PATH`` environment + variable. +- The IPMI controller on your bare metal server is turned on. +- The IPMI controller credentials and IP address passed in the command + are correct. +- The conductor node has a route to the IPMI controller. This can be + checked by just pinging the IPMI controller IP from the conductor + node. + +IPMI configuration +~~~~~~~~~~~~~~~~~~ + +If there are slow or unresponsive BMCs in the environment, the +``retry_timeout`` configuration option in the ``[ipmi]`` section may need +to be lowered. The default is fairly conservative, as setting this timeout +too low can cause older BMCs to crash and require a hard-reset. + +Collecting sensor data +~~~~~~~~~~~~~~~~~~~~~~ + +Bare Metal service supports sending IPMI sensor data to Telemetry with +certain drivers, such as drivers ending with ``ipmitool``, ``ilo`` and +``irmc``. By default, support for sending IPMI sensor data to Telemetry is +disabled. If you want to enable it, you should make the following two changes +in ``ironic.conf``: + +.. code-block:: ini + + [DEFAULT] + notification_driver = messaging + [conductor] + send_sensor_data = true + +If you want to customize the sensor types which will be sent to Telemetry, +change the ``send_sensor_data_types`` option. For example, the below +settings will send information about temperature, fan, voltage from sensors +to the Telemetry service: + +.. code-block:: ini + + send_sensor_data_types=Temperature,Fan,Voltage + +Supported sensor types are defined by the Telemetry service, currently +these are ``Temperature``, ``Fan``, ``Voltage``, ``Current``. +Special value ``All`` (the default) designates all supported sensor types. + +.. _IPMI: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface diff --git a/install-guide/source/configure-iscsi.rst b/install-guide/source/configure-iscsi.rst new file mode 100644 index 0000000000..ce90376f58 --- /dev/null +++ b/install-guide/source/configure-iscsi.rst @@ -0,0 +1,5 @@ +Configuring iSCSI-based drivers +------------------------------- + +Ensure that the ``qemu-img`` and ``iscsiadm`` tools are installed on the +**ironic-conductor** host(s). diff --git a/install-guide/source/configure-pxe.rst b/install-guide/source/configure-pxe.rst new file mode 100644 index 0000000000..29082c7b51 --- /dev/null +++ b/install-guide/source/configure-pxe.rst @@ -0,0 +1,421 @@ +Configuring PXE and iPXE +======================== + +PXE setup +--------- + +If you will be using PXE, it needs to be set up on the Bare Metal service +node(s) where ``ironic-conductor`` is running. + +#. Make sure the tftp root directory exist and can be written to by the + user the ``ironic-conductor`` is running as. For example:: + + sudo mkdir -p /tftpboot + sudo chown -R ironic /tftpboot + +#. Install tftp server and the syslinux package with the PXE boot images: + + Ubuntu (Up to and including 14.04):: + + sudo apt-get install xinetd tftpd-hpa syslinux-common syslinux + + Ubuntu (14.10 and after):: + + sudo apt-get install xinetd tftpd-hpa syslinux-common pxelinux + + Fedora 21/RHEL7/CentOS7:: + + sudo yum install tftp-server syslinux-tftpboot xinetd + + Fedora 22 or higher:: + + sudo dnf install tftp-server syslinux-tftpboot xinetd + + SUSE:: + + sudo zypper install tftp syslinux xinetd + +#. Using xinetd to provide a tftp server setup to serve ``/tftpboot``. + Create or edit ``/etc/xinetd.d/tftp`` as below:: + + service tftp + { + protocol = udp + port = 69 + socket_type = dgram + wait = yes + user = root + server = /usr/sbin/in.tftpd + server_args = -v -v -v -v -v --map-file /tftpboot/map-file /tftpboot + disable = no + # This is a workaround for Fedora, where TFTP will listen only on + # IPv6 endpoint, if IPv4 flag is not used. + flags = IPv4 + } + + and restart the ``xinetd`` service: + + Ubuntu:: + + sudo service xinetd restart + + Fedora/RHEL7/CentOS7/SUSE:: + + sudo systemctl restart xinetd + +#. Copy the PXE image to ``/tftpboot``. The PXE image might be found at [1]_: + + Ubuntu (Up to and including 14.04):: + + sudo cp /usr/lib/syslinux/pxelinux.0 /tftpboot + + Ubuntu (14.10 and after):: + + sudo cp /usr/lib/PXELINUX/pxelinux.0 /tftpboot + + RHEL7/CentOS7/SUSE:: + + sudo cp /usr/share/syslinux/pxelinux.0 /tftpboot + +#. If whole disk images need to be deployed via PXE-netboot, copy the + chain.c32 image to ``/tftpboot`` to support it: + + Ubuntu (Up to and including 14.04):: + + sudo cp /usr/lib/syslinux/chain.c32 /tftpboot + + Ubuntu (14.10 and after):: + + sudo cp /usr/lib/syslinux/modules/bios/chain.c32 /tftpboot + + Fedora:: + + sudo cp /boot/extlinux/chain.c32 /tftpboot + + RHEL7/CentOS7/SUSE:: + + sudo cp /usr/share/syslinux/chain.c32 /tftpboot/ + +#. If the version of syslinux is **greater than** 4 we also need to make sure + that we copy the library modules into the ``/tftpboot`` directory [2]_ + [1]_. For example, for Ubuntu run:: + + sudo cp /usr/lib/syslinux/modules/*/ldlinux.* /tftpboot + +#. Create a map file in the tftp boot directory (``/tftpboot``):: + + echo 're ^(/tftpboot/) /tftpboot/\2' > /tftpboot/map-file + echo 're ^/tftpboot/ /tftpboot/' >> /tftpboot/map-file + echo 're ^(^/) /tftpboot/\1' >> /tftpboot/map-file + echo 're ^([^/]) /tftpboot/\1' >> /tftpboot/map-file + +.. [1] On **Fedora/RHEL** the ``syslinux-tftpboot`` package already install + the library modules and PXE image at ``/tftpboot``. If the TFTP server + is configured to listen to a different directory you should copy the + contents of ``/tftpboot`` to the configured directory +.. [2] http://www.syslinux.org/wiki/index.php/Library_modules + + +PXE UEFI setup +-------------- + +If you want to deploy on a UEFI supported bare metal, perform these additional +steps on the ironic conductor node to configure the PXE UEFI environment. + +#. Install Grub2 and shim packages: + + Ubuntu (14.04LTS and later):: + + sudo apt-get install grub-efi-amd64-signed shim-signed + + Fedora 21/RHEL7/CentOS7:: + + sudo yum install grub2-efi shim + + Fedora 22 or higher:: + + sudo dnf install grub2-efi shim + + SUSE:: + + sudo zypper install grub2-x86_64-efi shim + +#. Copy grub and shim boot loader images to ``/tftpboot`` directory: + + Ubuntu (14.04LTS and later):: + + sudo cp /usr/lib/shim/shim.efi.signed /tftpboot/bootx64.efi + sudo cp /usr/lib/grub/x86_64-efi-signed/grubnetx64.efi.signed /tftpboot/grubx64.efi + + Fedora: (21 and later):: + + sudo cp /boot/efi/EFI/fedora/shim.efi /tftpboot/bootx64.efi + sudo cp /boot/efi/EFI/fedora/grubx64.efi /tftpboot/grubx64.efi + + RHEL7/CentOS7:: + + sudo cp /boot/efi/EFI/centos/shim.efi /tftpboot/bootx64.efi + sudo cp /boot/efi/EFI/centos/grubx64.efi /tftpboot/grubx64.efi + + SUSE:: + + sudo cp /usr/lib64/efi/shim.efi /tftpboot/bootx64.efi + sudo cp /usr/lib/grub2/x86_64-efi/grub.efi /tftpboot/grubx64.efi + +#. Create master grub.cfg: + + Ubuntu: Create grub.cfg under ``/tftpboot/grub`` directory:: + + GRUB_DIR=/tftpboot/grub + + Fedora: Create grub.cfg under ``/tftpboot/EFI/fedora`` directory:: + + GRUB_DIR=/tftpboot/EFI/fedora + + RHEL7/CentOS7: Create grub.cfg under ``/tftpboot/EFI/centos`` directory:: + + GRUB_DIR=/tftpboot/EFI/centos + + SUSE: Create grub.cfg under ``/tftpboot/boot/grub`` directory:: + + GRUB_DIR=/tftpboot/boot/grub + + Create directory ``GRUB_DIR``:: + + sudo mkdir -p $GRUB_DIR + + This file is used to redirect grub to baremetal node specific config file. + It redirects it to specific grub config file based on DHCP IP assigned to + baremetal node. + + .. literalinclude:: ../../ironic/drivers/modules/master_grub_cfg.txt + + Change the permission of grub.cfg:: + + sudo chmod 644 $GRUB_DIR/grub.cfg + +#. Update the bare metal node with ``boot_mode`` capability in node's properties + field:: + + ironic node-update add properties/capabilities='boot_mode:uefi' + +#. Make sure that bare metal node is configured to boot in UEFI boot mode and + boot device is set to network/pxe. + + NOTE: ``pxe_ilo`` driver supports automatic setting of UEFI boot mode and + boot device on the bare metal node. So this step is not required for + ``pxe_ilo`` driver. + +.. note:: + For more information on configuring boot modes, see :ref:`boot_mode_support`. + + +iPXE setup +---------- + +If you will be using iPXE to boot instead of PXE, iPXE needs to be set up +on the Bare Metal service node(s) where ``ironic-conductor`` is running. + +#. Make sure these directories exist and can be written to by the user + the ``ironic-conductor`` is running as. For example:: + + sudo mkdir -p /tftpboot + sudo mkdir -p /httpboot + sudo chown -R ironic /tftpboot + sudo chown -R ironic /httpboot + +#. Create a map file in the tftp boot directory (``/tftpboot``):: + + echo 'r ^([^/]) /tftpboot/\1' > /tftpboot/map-file + echo 'r ^(/tftpboot/) /tftpboot/\2' >> /tftpboot/map-file + + .. _HTTP server: + +#. Set up TFTP and HTTP servers. + + These servers should be running and configured to use the local + /tftpboot and /httpboot directories respectively, as their root + directories. (Setting up these servers is outside the scope of this + install guide.) + + These root directories need to be mounted locally to the + ``ironic-conductor`` services, so that the services can access them. + + The Bare Metal service's configuration file (/etc/ironic/ironic.conf) + should be edited accordingly to specify the TFTP and HTTP root + directories and server addresses. For example: + + .. code-block:: ini + + [pxe] + + # Ironic compute node's tftp root path. (string value) + tftp_root=/tftpboot + + # IP address of Ironic compute node's tftp server. (string + # value) + tftp_server=192.168.0.2 + + [deploy] + # Ironic compute node's http root path. (string value) + http_root=/httpboot + + # Ironic compute node's HTTP server URL. Example: + # http://192.1.2.3:8080 (string value) + http_url=http://192.168.0.2:8080 + +#. Install the iPXE package with the boot images: + + Ubuntu:: + + apt-get install ipxe + + Fedora 21/RHEL7/CentOS7:: + + yum install ipxe-bootimgs + + Fedora 22 or higher:: + + dnf install ipxe-bootimgs + + .. note:: + SUSE does not provide a package containing iPXE boot images. If you are + using SUSE or if the packaged version of the iPXE boot image doesn't + work, you can download a prebuilt one from http://boot.ipxe.org or build + one image from source, see http://ipxe.org/download for more information. + +#. Copy the iPXE boot image (``undionly.kpxe`` for **BIOS** and + ``ipxe.efi`` for **UEFI**) to ``/tftpboot``. The binary might + be found at: + + Ubuntu:: + + cp /usr/lib/ipxe/{undionly.kpxe,ipxe.efi} /tftpboot + + Fedora/RHEL7/CentOS7:: + + cp /usr/share/ipxe/{undionly.kpxe,ipxe.efi} /tftpboot + +#. Enable/Configure iPXE in the Bare Metal Service's configuration file + (/etc/ironic/ironic.conf): + + .. code-block:: ini + + [pxe] + + # Enable iPXE boot. (boolean value) + ipxe_enabled=True + + # Neutron bootfile DHCP parameter. (string value) + pxe_bootfile_name=undionly.kpxe + + # Bootfile DHCP parameter for UEFI boot mode. (string value) + uefi_pxe_bootfile_name=ipxe.efi + + # Template file for PXE configuration. (string value) + pxe_config_template=$pybasedir/drivers/modules/ipxe_config.template + + # Template file for PXE configuration for UEFI boot loader. + # (string value) + uefi_pxe_config_template=$pybasedir/drivers/modules/ipxe_config.template + + +#. It is possible to configure the Bare Metal service in such a way + that nodes will boot into the deploy image directly from Object Storage. + Doing this avoids having to cache the images on the ironic-conductor + host and serving them via the ironic-conductor's `HTTP server`_. + This can be done if: + + #. the Image Service is used for image storage; + #. the images in the Image Service are internally stored in + Object Storage; + #. the Object Storage supports generating temporary URLs + for accessing objects stored in it. + Both the OpenStack Swift and RADOS Gateway provide support for this. + + * See `Ceph Object Gateway support`_ on how to configure + the Bare Metal Service with RADOS Gateway as the Object Storage. + + Configure this by setting the ``[pxe]/ipxe_use_swift`` configuration + option to ``True`` as follows: + + .. code-block:: ini + + [pxe] + + # Download deploy images directly from swift using temporary + # URLs. If set to false (default), images are downloaded to + # the ironic-conductor node and served over its local HTTP + # server. Applicable only when 'ipxe_enabled' option is set to + # true. (boolean value) + ipxe_use_swift=True + + Although the `HTTP server`_ still has to be deployed and configured + (as it will serve iPXE boot script and boot configuration files for nodes), + such configuration will shift some load from ironic-conductor hosts + to the Object Storage service which can be scaled horizontally. + + Note that when SSL is enabled on the Object Storage service + you have to ensure that iPXE firmware on the nodes can indeed + boot from generated temporary URLs that use HTTPS protocol. + + .. _Ceph Object Gateway support: http://docs.openstack.org/developer/ironic/deploy/radosgw.html + +#. Restart the ``ironic-conductor`` process: + + Fedora/RHEL7/CentOS7/SUSE:: + + sudo systemctl restart openstack-ironic-conductor + + Ubuntu:: + + sudo service ironic-conductor restart + + +PXE multi-architecture setup +---------------------------- + +It is possible to deploy servers of different architecture by one conductor. +To use this feature, architecture-specific boot and template files must +be configured using the configuration options +``[pxe]pxe_bootfile_name_by_arch`` and ``[pxe]pxe_config_template_by_arch`` +respectively, in the Bare Metal service's configuration file +(/etc/ironic/ironic.conf). + +These two options are dictionary values; the key is the architecture and the +value is the boot (or config template) file. A node's ``cpu_arch`` property is +used as the key to get the appropriate boot file and template file. If the +node's ``cpu_arch`` is not in the dictionary, the configuration options (in +[pxe] group) ``pxe_bootfile_name``, ``pxe_config_template``, +``uefi_pxe_bootfile_name`` and ``uefi_pxe_config_template`` will be used +instead. + +In the following example, since 'x86' and 'x86_64' keys are not in the +``pxe_bootfile_name_by_arch`` or ``pxe_config_template_by_arch`` options, x86 +and x86_64 nodes will be deployed by 'pxelinux.0' or 'bootx64.efi', depending +on the node's ``boot_mode`` capability ('bios' or 'uefi'). However, aarch64 +nodes will be deployed by 'grubaa64.efi', and ppc64 nodes by 'bootppc64':: + + [pxe] + + # Bootfile DHCP parameter. (string value) + pxe_bootfile_name=pxelinux.0 + + # On ironic-conductor node, template file for PXE + # configuration. (string value) + pxe_config_template = $pybasedir/drivers/modules/pxe_config.template + + # Bootfile DHCP parameter for UEFI boot mode. (string value) + uefi_pxe_bootfile_name=bootx64.efi + + # On ironic-conductor node, template file for PXE + # configuration for UEFI boot loader. (string value) + uefi_pxe_config_template=$pybasedir/drivers/modules/pxe_grub_config.template + + # Bootfile DHCP parameter per node architecture. (dict value) + pxe_bootfile_name_by_arch=aarch64:grubaa64.efi,ppc64:bootppc64 + + # On ironic-conductor node, template file for PXE + # configuration per node architecture. For example: + # aarch64:/opt/share/grubaa64_pxe_config.template (dict value) + pxe_config_template_by_arch=aarch64:pxe_grubaa64_config.template,ppc64:pxe_ppc64_config.template diff --git a/install-guide/source/enabling-drivers.rst b/install-guide/source/enabling-drivers.rst new file mode 100644 index 0000000000..17000c2453 --- /dev/null +++ b/install-guide/source/enabling-drivers.rst @@ -0,0 +1,196 @@ +Enabling drivers and hardware types +=================================== + +Introduction +------------ + +The Bare Metal service delegates actual hardware management to **drivers**. +Starting with the Ocata release, two types of drivers are supported: +*classic drivers* (for example, ``pxe_ipmitool``, ``agent_ilo``, etc.) and +the newer *hardware types* (for example, generic ``redfish`` and ``ipmi`` +or vendor-specific ``ilo`` and ``irmc``). + +Drivers, in turn, consist of *hardware interfaces*: sets of functionality +dealing with some aspect of bare metal provisioning in a vendor-specific way. +*Classic drivers* have all *hardware interfaces* hardcoded, while *hardware +types* only declare which *hardware interfaces* they are compatible with. + +Please refer to the `driver composition reform specification`_ +for technical details behind *hardware types*. + +.. TODO(dtantsur): write devdocs on the driver composition and stop linking + to the specification. + +From API user's point of view, both *classic drivers* and *hardware types* can +be assigned to the ``driver`` field of a node. However, they are configured +differently. + +Enabling hardware types +----------------------- + +Hardware types are enabled in the configuration file of the +**ironic-conductor** service by setting the ``enabled_hardware_types`` +configuration option, for example: + +.. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,redfish + +However, due to their dynamic nature, they also require configuring enabled +hardware interfaces. + +.. note:: + All available hardware types and interfaces are listed in setup.cfg_ file + in the source code tree. + +There are several types of hardware interfaces: + +boot + manages booting of both the deploy ramdisk and the user instances on the + bare metal node. Boot interface implementations are often vendor specific, + and can be enabled via the ``enabled_boot_interfaces`` option: + + .. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,ilo + enabled_boot_interfaces = pxe,ilo-virtual-media + + Boot interfaces with ``pxe`` in their name require :doc:`configure-pxe`. +console + manages access to the serial console of a bare metal node. + See `Configuring Web or Serial Console`_ for details. +deploy + defines how the image gets transferred to the target disk. + + * With ``iscsi`` deploy method the deploy ramdisk publishes node's hard + drive as an iSCSI_ share. The ironic-conductor then copies the image + to this share. Requires :doc:`configure-iscsi`. + + * With ``direct`` deploy method, the deploy ramdisk fetches the image + from an HTTP location (object storage temporary URL or user-provided + HTTP URL). + + .. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,redfish + enabled_deploy_interfaces = iscsi,direct +inspect + implements fetching hardware information from nodes. Can be implemented + out-of-band (via contacting the node's BMC) or in-band (via booting + a ramdisk on a node). The latter implementation is called ``inspector`` + and uses a separate service called ironic-inspector_. Example: + + .. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,ilo,irmc + enabled_inspect_interfaces = ilo,irmc,inspector + + See `inspection documentation`_ for more details. +management + provides additional hardware management actions, like getting or setting + boot devices. This interface is usually vendor-specific, and its name + often matches the name of the hardware type (with ``ipmitool`` being + a notable exception). For example: + + .. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,redfish,ilo,irmc + enabled_management_interfaces = ipmitool,redfish,ilo,irmc + + Using ``ipmitool`` requires :doc:`configure-ipmi`. See + `driver-specific documentation`_ for required configuration of each driver. +network + connects/disconnects bare metal nodes to/from virtual networks. This is + the only interface that is also pluggable for classic drivers. See + :doc:`configure-tenant-networks` for more details. +power + runs power actions on nodes. Similar to the management interface, it is + usually vendor-specific, and its name often matches the name of the + hardware type (with ``ipmitool`` being again an exception). For example: + + .. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,redfish,ilo,irmc + enabled_power_interfaces = ipmitool,redfish,ilo,irmc + + Using ``ipmitool`` requires :doc:`configure-ipmi`. See + `driver-specific documentation`_ for required configuration of each driver. +raid + manages building and tearing down RAID on nodes. Similar to inspection, + it can be implemented either out-of-band or in-band (via ``agent`` + implementation). See `RAID documentation`_ for details. + + .. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,redfish,ilo,irmc + enabled_raid_interfaces = agent,no-raid +vendor + is a place for vendor extensions to be exposed in API. See `vendor + methods documentation`_ for details. + +Here is a complete configuration example, enabling two generic protocols, +IPMI and Redfish, with a few additional features: + +.. code-block:: ini + + [DEFAULT] + enabled_hardware_types = ipmi,redfish + enabled_boot_interfaces = pxe + enabled_console_interfaces = ipmitool-socat,no-console + enabled_deploy_interfaces = iscsi,direct + enabled_inspect_interfaces = inspector + enabled_management_interfaces = ipmitool,redfish + enabled_network_interfaces = flat,neutron + enabled_power_interfaces = ipmitool,redfish + enabled_raid_interfaces = agent + enabled_vendor_interfaces = no-vendor + +Note that some interfaces have implementations named ``no-`` where +```` is the interface type. These implementations do nothing and return +errors when used from API. + +.. TODO(dtantsur): create dev documentation on defaults calculation, and link + it here. Add explanation of default__interface options. + +Enabling classic drivers +------------------------ + +Classic drivers are enabled in the configuration file of the +**ironic-conductor** service by setting the ``enabled_drivers`` configuration +option, for example: + +.. code-block:: ini + + [DEFAULT] + enabled_drivers = pxe_ipmitool,pxe_ilo,pxe_drac + +The names in this comma-separated list are entry point names of the drivers. +They have to be available at conductor start-up, and all dependencies must +be installed locally. For example, + +* drivers starting with ``pxe`` and some drivers starting with ``agent`` + require :doc:`configure-pxe`, + +* drivers starting with ``pxe`` or having ``iscsi`` in their name require + :doc:`configure-iscsi`, + +* drivers ending with ``ipmitool`` require :doc:`configure-ipmi`. + +See `driver-specific documentation`_ for required configuration of each driver. + +.. _driver composition reform specification: http://specs.openstack.org/openstack/ironic-specs/specs/approved/driver-composition-reform.html +.. _driver-specific documentation: https://docs.openstack.org/developer/ironic/deploy/drivers.html +.. _setup.cfg: https://git.openstack.org/cgit/openstack/ironic/tree/setup.cfg +.. _`Configuring Web or Serial Console`: http://docs.openstack.org/developer/ironic/deploy/console.html +.. _iSCSI: https://en.wikipedia.org/wiki/ISCSI +.. _ironic-inspector: https://docs.openstack.org/developer/ironic-inspector/ +.. _inspection documentation: https://docs.openstack.org/developer/ironic/deploy/inspection.html +.. _RAID documentation: https://docs.openstack.org/developer/ironic/deploy/raid.html +.. _vendor methods documentation: https://docs.openstack.org/developer/ironic/dev/vendor-passthru.html diff --git a/install-guide/source/include/boot-mode.rst b/install-guide/source/include/boot-mode.rst new file mode 100644 index 0000000000..ded5843058 --- /dev/null +++ b/install-guide/source/include/boot-mode.rst @@ -0,0 +1,43 @@ +.. _boot_mode_support: + +Boot mode support +----------------- + +The following drivers support setting of boot mode (Legacy BIOS or UEFI). + +* ``pxe_ipmitool`` + +The boot modes can be configured in Bare Metal service in the following way: + +* When no boot mode setting is provided, these drivers default the boot_mode + to Legacy BIOS. + +* Only one boot mode (either ``uefi`` or ``bios``) can be configured for + the node. + +* If the operator wants a node to boot always in ``uefi`` mode or ``bios`` + mode, then they may use ``capabilities`` parameter within ``properties`` + field of an bare metal node. The operator must manually set the appropriate + boot mode on the bare metal node. + + To configure a node in ``uefi`` mode, then set ``capabilities`` as below:: + + ironic node-update add properties/capabilities='boot_mode:uefi' + + Nodes having ``boot_mode`` set to ``uefi`` may be requested by adding an + ``extra_spec`` to the Compute service flavor:: + + nova flavor-key ironic-test-3 set capabilities:boot_mode="uefi" + nova boot --flavor ironic-test-3 --image test-image instance-1 + + If ``capabilities`` is used in ``extra_spec`` as above, nova scheduler + (``ComputeCapabilitiesFilter``) will match only bare metal nodes which have + the ``boot_mode`` set appropriately in ``properties/capabilities``. It will + filter out rest of the nodes. + + The above facility for matching in the Compute service can be used in + heterogeneous environments where there is a mix of ``uefi`` and ``bios`` + machines, and operator wants to provide a choice to the user regarding + boot modes. If the flavor doesn't contain ``boot_mode`` and ``boot_mode`` + is configured for bare metal nodes, then nova scheduler will consider all + nodes and user may get either ``bios`` or ``uefi`` machine. diff --git a/install-guide/source/include/configure-ironic-conductor.rst b/install-guide/source/include/configure-ironic-conductor.rst index 9afae78d0e..235cd939a5 100644 --- a/install-guide/source/include/configure-ironic-conductor.rst +++ b/install-guide/source/include/configure-ironic-conductor.rst @@ -1,9 +1,7 @@ Configuring ironic-conductor service ------------------------------------ -#. Replace ``HOST_IP`` with IP of the conductor host, and replace ``DRIVERS`` - with a comma-separated list of drivers you chose for the conductor service - as follows: +#. Replace ``HOST_IP`` with IP of the conductor host. .. code-block:: ini @@ -14,16 +12,6 @@ Configuring ironic-conductor service # (string value) my_ip=HOST_IP - # Specify the list of drivers to load during service - # initialization. Missing drivers, or drivers which fail to - # initialize, will prevent the conductor service from - # starting. The option default is a recommended set of - # production-oriented drivers. A complete list of drivers - # present on your system may be found by enumerating the - # "ironic.drivers" entrypoint. An example may be found in the - # developer documentation online. (list value) - enabled_drivers=DRIVERS - .. note:: If a conductor host has multiple IPs, ``my_ip`` should be set to the IP which is on the same network as the bare metal nodes. @@ -171,9 +159,8 @@ Configuring ironic-conductor service # HTTPs connections. (string value) cafile=/opt/stack/data/ca-bundle.pem -#. Make sure that ``qemu-img`` and ``iscsiadm`` (in the case of using iscsi-deploy driver) - binaries are installed and prepare the host system as described at - `Setup the drivers for the Bare Metal service `_ +#. Configure enabled drivers and hardware types as described in + :doc:`enabling-drivers`. #. Restart the ironic-conductor service: @@ -186,5 +173,4 @@ Configuring ironic-conductor service Ubuntu: sudo service ironic-conductor restart - .. _Keystoneauth documentation: http://docs.openstack.org/developer/keystoneauth/ diff --git a/install-guide/source/include/console.rst b/install-guide/source/include/console.rst new file mode 100644 index 0000000000..392d37350f --- /dev/null +++ b/install-guide/source/include/console.rst @@ -0,0 +1,8 @@ +Configuring node web console +---------------------------- + +See `Configuring Web or Serial Console`_. + +.. TODO(dtantsur): move the installation documentation here + +.. _`Configuring Web or Serial Console`: http://docs.openstack.org/developer/ironic/deploy/console.html diff --git a/install-guide/source/include/disk-label.rst b/install-guide/source/include/disk-label.rst new file mode 100644 index 0000000000..ab131dcbc4 --- /dev/null +++ b/install-guide/source/include/disk-label.rst @@ -0,0 +1,62 @@ +.. _choosing_the_disk_label: + +Choosing the disk label +----------------------- + +.. note:: + The term ``disk label`` is historically used in Ironic and was taken + from `parted `_. Apparently + everyone seems to have a different word for ``disk label`` - these + are all the same thing: disk type, partition table, partition map + and so on... + +Ironic allows operators to choose which disk label they want their +bare metal node to be deployed with when Ironic is responsible for +partitioning the disk; therefore choosing the disk label does not apply +when the image being deployed is a ``whole disk image``. + +There are some edge cases where someone may want to choose a specific +disk label for the images being deployed, including but not limited to: + +* For machines in ``bios`` boot mode with disks larger than 2 terabytes + it's recommended to use a ``gpt`` disk label. That's because + a capacity beyond 2 terabytes is not addressable by using the + MBR partitioning type. But, although GPT claims to be backward + compatible with legacy BIOS systems `that's not always the case + `_. + +* Operators may want to force the partitioning to be always MBR (even + if the machine is deployed with boot mode ``uefi``) to avoid breakage + of applications and tools running on those instances. + +The disk label can be configured in two ways; when Ironic is used with +the Compute service or in standalone mode. The following bullet points +and sections will describe both methods: + +* When no disk label is provided Ironic will configure it according + to the boot mode (see :ref:`boot_mode_support`); ``bios`` boot mode will use + ``msdos`` and ``uefi`` boot mode will use ``gpt``. + +* Only one disk label - either ``msdos`` or ``gpt`` - can be configured + for the node. + +When used with Compute service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When Ironic is used with the Compute service the disk label should be +set to node's ``properties/capabilities`` field and also to the flavor +which will request such capability, for example:: + + ironic node-update add properties/capabilities='disk_label:gpt' + +As for the flavor:: + + nova flavor-key baremetal set capabilities:disk_label="gpt" + +When used in standalone mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When used without the Compute service, the disk label should be set +directly to the node's ``instance_info`` field, as below:: + + ironic node-update add instance_info/capabilities='{"disk_label": "gpt"}' diff --git a/install-guide/source/include/kernel-boot-parameters.rst b/install-guide/source/include/kernel-boot-parameters.rst index ae23f29f9b..86acf35c12 100644 --- a/install-guide/source/include/kernel-boot-parameters.rst +++ b/install-guide/source/include/kernel-boot-parameters.rst @@ -8,7 +8,7 @@ users' requirements. The way to append the kernel parameters is depending on how Network boot -============ +~~~~~~~~~~~~ Currently, the Bare Metal service supports assigning unified kernel parameters to PXE booted instances by: @@ -28,7 +28,7 @@ booted instances by: Local boot -========== +~~~~~~~~~~ For local boot instances, users can make use of configuration drive (see :ref:`configdrive`) to pass a custom @@ -70,7 +70,7 @@ to fit their use case: Console -======= +~~~~~~~ In order to change default console configuration in the Bare Metal service configuration file (``[pxe]`` section in ``/etc/ironic/ironic.conf``), diff --git a/install-guide/source/include/local-boot-partition-images.rst b/install-guide/source/include/local-boot-partition-images.rst index cb892806be..b0a758c155 100644 --- a/install-guide/source/include/local-boot-partition-images.rst +++ b/install-guide/source/include/local-boot-partition-images.rst @@ -8,6 +8,9 @@ after the deployment the node's subsequent reboots won't happen via PXE or Virtual Media. Instead, it will boot from a local boot loader installed on the disk. +.. note:: Whole disk images, on the contrary, support only local boot, and use + it by default. + It's important to note that in order for this to work the image being deployed with Bare Metal service **must** contain ``grub2`` installed within it. @@ -19,7 +22,7 @@ The following sections will describe both methods. Enabling local boot with Compute service -======================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable local boot we need to set a capability on the bare metal node, for example:: @@ -42,7 +45,7 @@ an ``extra_spec`` to the Compute service flavor, for example:: .. _local-boot-without-compute: Enabling local boot without Compute -=================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since adding ``capabilities`` to the node's properties is only used by the nova scheduler to perform more advanced scheduling of instances, diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst index 163137c764..a71eaa13cf 100644 --- a/install-guide/source/index.rst +++ b/install-guide/source/index.rst @@ -16,10 +16,10 @@ It contains the following sections: install.rst configure-integration.rst deploy-ramdisk.rst + setup-drivers.rst enrollment.rst standalone.rst configdrive.rst - setup-drivers.rst advanced.rst troubleshooting.rst next-steps.rst diff --git a/install-guide/source/setup-drivers.rst b/install-guide/source/setup-drivers.rst index fcfd7db134..41abd1f496 100644 --- a/install-guide/source/setup-drivers.rst +++ b/install-guide/source/setup-drivers.rst @@ -1,630 +1,10 @@ +Set up the drivers for the Bare Metal service +============================================= -Setup the drivers for the Bare Metal service -============================================ - -PXE setup ---------- - -If you will be using PXE, it needs to be set up on the Bare Metal service -node(s) where ``ironic-conductor`` is running. - -#. Make sure the tftp root directory exist and can be written to by the - user the ``ironic-conductor`` is running as. For example:: - - sudo mkdir -p /tftpboot - sudo chown -R ironic /tftpboot - -#. Install tftp server and the syslinux package with the PXE boot images:: - - Ubuntu: (Up to and including 14.04) - sudo apt-get install xinetd tftpd-hpa syslinux-common syslinux - - Ubuntu: (14.10 and after) - sudo apt-get install xinetd tftpd-hpa syslinux-common pxelinux - - Fedora 21/RHEL7/CentOS7: - sudo yum install tftp-server syslinux-tftpboot xinetd - - Fedora 22 or higher: - sudo dnf install tftp-server syslinux-tftpboot xinetd - - SUSE: - sudo zypper install tftp syslinux xinetd - -#. Using xinetd to provide a tftp server setup to serve ``/tftpboot``. - Create or edit ``/etc/xinetd.d/tftp`` as below:: - - service tftp - { - protocol = udp - port = 69 - socket_type = dgram - wait = yes - user = root - server = /usr/sbin/in.tftpd - server_args = -v -v -v -v -v --map-file /tftpboot/map-file /tftpboot - disable = no - # This is a workaround for Fedora, where TFTP will listen only on - # IPv6 endpoint, if IPv4 flag is not used. - flags = IPv4 - } - - and restart xinetd service:: - - Ubuntu: - sudo service xinetd restart - - Fedora/SUSE: - sudo systemctl restart xinetd - -#. Copy the PXE image to ``/tftpboot``. The PXE image might be found at [1]_:: - - Ubuntu (Up to and including 14.04): - sudo cp /usr/lib/syslinux/pxelinux.0 /tftpboot - - Ubuntu (14.10 and after): - sudo cp /usr/lib/PXELINUX/pxelinux.0 /tftpboot - - SUSE: - sudo cp /usr/share/syslinux/pxelinux.0 /tftpboot - -#. If whole disk images need to be deployed via PXE-netboot, copy the - chain.c32 image to ``/tftpboot`` to support it. The chain.c32 image - might be found at:: - - Ubuntu (Up to and including 14.04): - sudo cp /usr/lib/syslinux/chain.c32 /tftpboot - - Ubuntu (14.10 and after): - sudo cp /usr/lib/syslinux/modules/bios/chain.c32 /tftpboot - - Fedora/RHEL7/CentOS7: - sudo cp /boot/extlinux/chain.c32 /tftpboot - - SUSE: - sudo cp /usr/share/syslinux/chain.c32 /tftpboot/ - -#. If the version of syslinux is **greater than** 4 we also need to make sure - that we copy the library modules into the ``/tftpboot`` directory [2]_ - [1]_:: - - Ubuntu: - sudo cp /usr/lib/syslinux/modules/*/ldlinux.* /tftpboot - -#. Create a map file in the tftp boot directory (``/tftpboot``):: - - echo 're ^(/tftpboot/) /tftpboot/\2' > /tftpboot/map-file - echo 're ^/tftpboot/ /tftpboot/' >> /tftpboot/map-file - echo 're ^(^/) /tftpboot/\1' >> /tftpboot/map-file - echo 're ^([^/]) /tftpboot/\1' >> /tftpboot/map-file - -.. [1] On **Fedora/RHEL** the ``syslinux-tftpboot`` package already install - the library modules and PXE image at ``/tftpboot``. If the TFTP server - is configured to listen to a different directory you should copy the - contents of ``/tftpboot`` to the configured directory -.. [2] http://www.syslinux.org/wiki/index.php/Library_modules - - -PXE UEFI setup --------------- - -If you want to deploy on a UEFI supported bare metal, perform these additional -steps on the ironic conductor node to configure the PXE UEFI environment. - -#. Install Grub2 and shim packages:: - - Ubuntu: (14.04LTS and later) - sudo apt-get install grub-efi-amd64-signed shim-signed - - Fedora 21/RHEL7/CentOS7: - sudo yum install grub2-efi shim - - Fedora 22 or higher: - sudo dnf install grub2-efi shim - - SUSE: - sudo zypper install grub2-x86_64-efi shim - -#. Copy grub and shim boot loader images to ``/tftpboot`` directory:: - - Ubuntu: (14.04LTS and later) - sudo cp /usr/lib/shim/shim.efi.signed /tftpboot/bootx64.efi - sudo cp /usr/lib/grub/x86_64-efi-signed/grubnetx64.efi.signed \ - /tftpboot/grubx64.efi - - Fedora: (21 and later) - sudo cp /boot/efi/EFI/fedora/shim.efi /tftpboot/bootx64.efi - sudo cp /boot/efi/EFI/fedora/grubx64.efi /tftpboot/grubx64.efi - - CentOS: (7 and later) - sudo cp /boot/efi/EFI/centos/shim.efi /tftpboot/bootx64.efi - sudo cp /boot/efi/EFI/centos/grubx64.efi /tftpboot/grubx64.efi - - SUSE: - sudo cp /usr/lib64/efi/shim.efi /tftpboot/bootx64.efi - sudo cp /usr/lib/grub2/x86_64-efi/grub.efi /tftpboot/grubx64.efi - -#. Create master grub.cfg:: - - Ubuntu: Create grub.cfg under ``/tftpboot/grub`` directory. - GRUB_DIR=/tftpboot/grub - - Fedora: Create grub.cfg under ``/tftpboot/EFI/fedora`` directory. - GRUB_DIR=/tftpboot/EFI/fedora - - CentOS: Create grub.cfg under ``/tftpboot/EFI/centos`` directory. - GRUB_DIR=/tftpboot/EFI/centos - - SUSE: Create grub.cfg under ``/tftpboot/boot/grub`` directory. - GRUB_DIR=/tftpboot/boot/grub - - Create directory GRUB_DIR - sudo mkdir -p $GRUB_DIR - - This file is used to redirect grub to baremetal node specific config file. - It redirects it to specific grub config file based on DHCP IP assigned to - baremetal node. - - .. literalinclude:: ../../ironic/drivers/modules/master_grub_cfg.txt - - Change the permission of grub.cfg:: - - sudo chmod 644 $GRUB_DIR/grub.cfg - -#. Update the bare metal node with ``boot_mode`` capability in node's properties - field:: - - ironic node-update add properties/capabilities='boot_mode:uefi' - -#. Make sure that bare metal node is configured to boot in UEFI boot mode and - boot device is set to network/pxe. - - NOTE: ``pxe_ilo`` driver supports automatic setting of UEFI boot mode and - boot device on the bare metal node. So this step is not required for - ``pxe_ilo`` driver. - -.. note:: - For more information on configuring boot modes, see boot_mode_support_. - - -Elilo: an alternative to Grub2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Elilo is a UEFI bootloader. It is an alternative to Grub2, although it -isn't recommended since it is not being supported. - -#. Download and untar the elilo bootloader version >= 3.16 from - http://sourceforge.net/projects/elilo/:: - - sudo tar zxvf elilo-3.16-all.tar.gz - -#. Copy the elilo boot loader image to ``/tftpboot`` directory:: - - sudo cp ./elilo-3.16-x86_64.efi /tftpboot/elilo.efi - -#. Update bootfile and template file configuration parameters for UEFI - PXE boot in the Bare Metal Service's configuration file - (/etc/ironic/ironic.conf):: - - [pxe] - - # Bootfile DHCP parameter for UEFI boot mode. (string value) - uefi_pxe_bootfile_name=elilo.efi - - # Template file for PXE configuration for UEFI boot loader. - # (string value) - uefi_pxe_config_template=$pybasedir/drivers/modules/elilo_efi_pxe_config.template - - -iPXE setup ----------- - -If you will be using iPXE to boot instead of PXE, iPXE needs to be set up -on the Bare Metal service node(s) where ``ironic-conductor`` is running. - -#. Make sure these directories exist and can be written to by the user - the ``ironic-conductor`` is running as. For example:: - - sudo mkdir -p /tftpboot - sudo mkdir -p /httpboot - sudo chown -R ironic /tftpboot - sudo chown -R ironic /httpboot - -#. Create a map file in the tftp boot directory (``/tftpboot``):: - - echo 'r ^([^/]) /tftpboot/\1' > /tftpboot/map-file - echo 'r ^(/tftpboot/) /tftpboot/\2' >> /tftpboot/map-file - - .. _HTTP server: - -#. Set up TFTP and HTTP servers. - - These servers should be running and configured to use the local - /tftpboot and /httpboot directories respectively, as their root - directories. (Setting up these servers is outside the scope of this - install guide.) - - These root directories need to be mounted locally to the - ``ironic-conductor`` services, so that the services can access them. - - The Bare Metal service's configuration file (/etc/ironic/ironic.conf) - should be edited accordingly to specify the TFTP and HTTP root - directories and server addresses. For example: - - .. code-block:: ini - - [pxe] - - # Ironic compute node's tftp root path. (string value) - tftp_root=/tftpboot - - # IP address of Ironic compute node's tftp server. (string - # value) - tftp_server=192.168.0.2 - - [deploy] - # Ironic compute node's http root path. (string value) - http_root=/httpboot - - # Ironic compute node's HTTP server URL. Example: - # http://192.1.2.3:8080 (string value) - http_url=http://192.168.0.2:8080 - -#. Install the iPXE package with the boot images:: - - Ubuntu: - apt-get install ipxe - - Fedora 21/RHEL7/CentOS7: - yum install ipxe-bootimgs - - Fedora 22 or higher: - dnf install ipxe-bootimgs - - .. note:: - SUSE does not provide a package containing iPXE boot images. If you are - using SUSE or if the packaged version of the iPXE boot image doesn't - work, you can download a prebuilt one from http://boot.ipxe.org or build - one image from source, see http://ipxe.org/download for more information. - -#. Copy the iPXE boot image (``undionly.kpxe`` for **BIOS** and - ``ipxe.efi`` for **UEFI**) to ``/tftpboot``. The binary might - be found at:: - - Ubuntu: - cp /usr/lib/ipxe/{undionly.kpxe,ipxe.efi} /tftpboot - - Fedora/RHEL7/CentOS7: - cp /usr/share/ipxe/{undionly.kpxe,ipxe.efi} /tftpboot - -#. Enable/Configure iPXE in the Bare Metal Service's configuration file - (/etc/ironic/ironic.conf): - - .. code-block:: ini - - [pxe] - - # Enable iPXE boot. (boolean value) - ipxe_enabled=True - - # Neutron bootfile DHCP parameter. (string value) - pxe_bootfile_name=undionly.kpxe - - # Bootfile DHCP parameter for UEFI boot mode. (string value) - uefi_pxe_bootfile_name=ipxe.efi - - # Template file for PXE configuration. (string value) - pxe_config_template=$pybasedir/drivers/modules/ipxe_config.template - - # Template file for PXE configuration for UEFI boot loader. - # (string value) - uefi_pxe_config_template=$pybasedir/drivers/modules/ipxe_config.template - - -#. It is possible to configure the Bare Metal service in such a way - that nodes will boot into the deploy image directly from Object Storage. - Doing this avoids having to cache the images on the ironic-conductor - host and serving them via the ironic-conductor's `HTTP server`_. - This can be done if: - - #. the Image Service is used for image storage; - #. the images in the Image Service are internally stored in - Object Storage; - #. the Object Storage supports generating temporary URLs - for accessing objects stored in it. - Both the OpenStack Swift and RADOS Gateway provide support for this. - - * See `Ceph Object Gateway support`_ on how to configure - the Bare Metal Service with RADOS Gateway as the Object Storage. - - Configure this by setting the ``[pxe]/ipxe_use_swift`` configuration - option to ``True`` as follows: - - .. code-block:: ini - - [pxe] - - # Download deploy images directly from swift using temporary - # URLs. If set to false (default), images are downloaded to - # the ironic-conductor node and served over its local HTTP - # server. Applicable only when 'ipxe_enabled' option is set to - # true. (boolean value) - ipxe_use_swift=True - - Although the `HTTP server`_ still has to be deployed and configured - (as it will serve iPXE boot script and boot configuration files for nodes), - such configuration will shift some load from ironic-conductor hosts - to the Object Storage service which can be scaled horizontally. - - Note that when SSL is enabled on the Object Storage service - you have to ensure that iPXE firmware on the nodes can indeed - boot from generated temporary URLs that use HTTPS protocol. - - .. _Ceph Object Gateway support: http://docs.openstack.org/developer/ironic/deploy/radosgw.html - -#. Restart the ``ironic-conductor`` process:: - - Fedora/RHEL7/CentOS7/SUSE: - sudo systemctl restart openstack-ironic-conductor - - Ubuntu: - sudo service ironic-conductor restart - - -PXE multi-architecture setup ----------------------------- - -It is possible to deploy servers of different architecture by one conductor. -To use this feature, architecture-specific boot and template files must -be configured using the configuration options -``[pxe]pxe_bootfile_name_by_arch`` and ``[pxe]pxe_config_template_by_arch`` -respectively, in the Bare Metal service's configuration file -(/etc/ironic/ironic.conf). - -These two options are dictionary values; the key is the architecture and the -value is the boot (or config template) file. A node's ``cpu_arch`` property is -used as the key to get the appropriate boot file and template file. If the -node's ``cpu_arch`` is not in the dictionary, the configuration options (in -[pxe] group) ``pxe_bootfile_name``, ``pxe_config_template``, -``uefi_pxe_bootfile_name`` and ``uefi_pxe_config_template`` will be used -instead. - -In the following example, since 'x86' and 'x86_64' keys are not in the -``pxe_bootfile_name_by_arch`` or ``pxe_config_template_by_arch`` options, x86 -and x86_64 nodes will be deployed by 'pxelinux.0' or 'bootx64.efi', depending -on the node's ``boot_mode`` capability ('bios' or 'uefi'). However, aarch64 -nodes will be deployed by 'grubaa64.efi', and ppc64 nodes by 'bootppc64':: - - [pxe] - - # Bootfile DHCP parameter. (string value) - pxe_bootfile_name=pxelinux.0 - - # On ironic-conductor node, template file for PXE - # configuration. (string value) - pxe_config_template = $pybasedir/drivers/modules/pxe_config.template - - # Bootfile DHCP parameter for UEFI boot mode. (string value) - uefi_pxe_bootfile_name=bootx64.efi - - # On ironic-conductor node, template file for PXE - # configuration for UEFI boot loader. (string value) - uefi_pxe_config_template=$pybasedir/drivers/modules/pxe_grub_config.template - - # Bootfile DHCP parameter per node architecture. (dict value) - pxe_bootfile_name_by_arch=aarch64:grubaa64.efi,ppc64:bootppc64 - - # On ironic-conductor node, template file for PXE - # configuration per node architecture. For example: - # aarch64:/opt/share/grubaa64_pxe_config.template (dict value) - pxe_config_template_by_arch=aarch64:pxe_grubaa64_config.template,ppc64:pxe_ppc64_config.template - - -Networking service configuration --------------------------------- - -DHCP requests from iPXE need to have a DHCP tag called ``ipxe``, in order -for the DHCP server to tell the client to get the boot.ipxe script via -HTTP. Otherwise, if the tag isn't there, the DHCP server will tell the -DHCP client to chainload the iPXE image (undionly.kpxe). -The Networking service needs to be configured to create this DHCP tag, -since it isn't created by default. - -#. Create a custom ``dnsmasq.conf`` file with a setting for the ipxe tag. For - example, create the file ``/etc/dnsmasq-ironic.conf`` with the content:: - - # Create the "ipxe" tag if request comes from iPXE user class - dhcp-userclass=set:ipxe,iPXE - - # Alternatively, create the "ipxe" tag if request comes from DHCP option 175 - # dhcp-match=set:ipxe,175 - -#. In the Networking service DHCP Agent configuration file (typically located at - /etc/neutron/dhcp_agent.ini), set the custom ``/etc/dnsmasq-ironic.conf`` - file as the dnsmasq configuration file:: - - [DEFAULT] - dnsmasq_config_file = /etc/dnsmasq-ironic.conf - - -#. Restart the ``neutron-dhcp-agent`` process:: - - service neutron-dhcp-agent restart - - -IPMI support ------------- - -If using the IPMITool driver, the ``ipmitool`` command must be present on the -service node(s) where ``ironic-conductor`` is running. On most distros, this -is provided as part of the ``ipmitool`` package. Source code is available at -http://ipmitool.sourceforge.net/ - -Note that certain distros, notably Mac OS X and SLES, install ``openipmi`` -instead of ``ipmitool`` by default. THIS DRIVER IS NOT COMPATIBLE WITH -``openipmi`` AS IT RELIES ON ERROR HANDLING OPTIONS NOT PROVIDED BY THIS TOOL. - -Check that you can connect to and authenticate with the IPMI -controller in your bare metal server by using ``ipmitool``:: - - ipmitool -I lanplus -H -U -P chassis power status - - = The IP of the IPMI controller you want to access - -*Note:* - -#. This is not the bare metal node's main IP. The IPMI controller - should have its own unique IP. - -#. In case the above command doesn't return the power status of the - bare metal server, check for these: - - - ``ipmitool`` is installed. - - The IPMI controller on your bare metal server is turned on. - - The IPMI controller credentials passed in the command are right. - - The conductor node has a route to the IPMI controller. This can be - checked by just pinging the IPMI controller IP from the conductor - node. - -.. note:: - If there are slow or unresponsive BMCs in the environment, the retry_timeout - configuration option in the [ipmi] section may need to be lowered. The - default is fairly conservative, as setting this timeout too low can cause - older BMCs to crash and require a hard-reset. - -Bare Metal service supports sending IPMI sensor data to Telemetry with -pxe_ipmitool, agent_ipmitool, agent_ilo, iscsi_ilo, pxe_ilo, and with pxe_irmc -driver. By default, support for sending IPMI sensor data to Telemetry is -disabled. If you want to enable it, you should make the following two changes -in ``ironic.conf``: - -* ``notification_driver = messaging`` in the ``DEFAULT`` section -* ``send_sensor_data = true`` in the ``conductor`` section - -If you want to customize the sensor types which will be sent to Telemetry, -change the ``send_sensor_data_types`` option. For example, the below -settings will send temperature, fan, voltage and these three sensor types -of data to Telemetry: - -* send_sensor_data_types=Temperature,Fan,Voltage - -If we use default value 'All' for all the sensor types which are supported by -Telemetry, they are: - -* Temperature, Fan, Voltage, Current - - -Configure node web console --------------------------- - -See `Configuring Web or Serial Console`_. - -.. _`Configuring Web or Serial Console`: http://docs.openstack.org/developer/ironic/deploy/console.html - -.. _boot_mode_support: - -Boot mode support ------------------ - -The following drivers support setting of boot mode (Legacy BIOS or UEFI). - -* ``pxe_ipmitool`` - -The boot modes can be configured in Bare Metal service in the following way: - -* When no boot mode setting is provided, these drivers default the boot_mode - to Legacy BIOS. - -* Only one boot mode (either ``uefi`` or ``bios``) can be configured for - the node. - -* If the operator wants a node to boot always in ``uefi`` mode or ``bios`` - mode, then they may use ``capabilities`` parameter within ``properties`` - field of an bare metal node. The operator must manually set the appropriate - boot mode on the bare metal node. - - To configure a node in ``uefi`` mode, then set ``capabilities`` as below:: - - ironic node-update add properties/capabilities='boot_mode:uefi' - - Nodes having ``boot_mode`` set to ``uefi`` may be requested by adding an - ``extra_spec`` to the Compute service flavor:: - - nova flavor-key ironic-test-3 set capabilities:boot_mode="uefi" - nova boot --flavor ironic-test-3 --image test-image instance-1 - - If ``capabilities`` is used in ``extra_spec`` as above, nova scheduler - (``ComputeCapabilitiesFilter``) will match only bare metal nodes which have - the ``boot_mode`` set appropriately in ``properties/capabilities``. It will - filter out rest of the nodes. - - The above facility for matching in the Compute service can be used in - heterogeneous environments where there is a mix of ``uefi`` and ``bios`` - machines, and operator wants to provide a choice to the user regarding - boot modes. If the flavor doesn't contain ``boot_mode`` and ``boot_mode`` - is configured for bare metal nodes, then nova scheduler will consider all - nodes and user may get either ``bios`` or ``uefi`` machine. - -.. _choosing_the_disk_label: - -Choosing the disk label ------------------------ - -.. note:: - The term ``disk label`` is historically used in Ironic and was taken - from `parted `_. Apparently - everyone seems to have a different word for ``disk label`` - these - are all the same thing: disk type, partition table, partition map - and so on... - -Ironic allows operators to choose which disk label they want their -bare metal node to be deployed with when Ironic is responsible for -partitioning the disk; therefore choosing the disk label does not apply -when the image being deployed is a ``whole disk image``. - -There are some edge cases where someone may want to choose a specific -disk label for the images being deployed, including but not limited to: - -* For machines in ``bios`` boot mode with disks larger than 2 terabytes - it's recommended to use a ``gpt`` disk label. That's because - a capacity beyond 2 terabytes is not addressable by using the - MBR partitioning type. But, although GPT claims to be backward - compatible with legacy BIOS systems `that's not always the case - `_. - -* Operators may want to force the partitioning to be always MBR (even - if the machine is deployed with boot mode ``uefi``) to avoid breakage - of applications and tools running on those instances. - -The disk label can be configured in two ways; when Ironic is used with -the Compute service or in standalone mode. The following bullet points -and sections will describe both methods: - -* When no disk label is provided Ironic will configure it according - to the `boot mode `_; ``bios`` boot mode will use - ``msdos`` and ``uefi`` boot mode will use ``gpt``. - -* Only one disk label - either ``msdos`` or ``gpt`` - can be configured - for the node. - -When used with Compute service -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When Ironic is used with the Compute service the disk label should be -set to node's ``properties/capabilities`` field and also to the flavor -which will request such capability, for example:: - - ironic node-update add properties/capabilities='disk_label:gpt' - -As for the flavor:: - - nova flavor-key baremetal set capabilities:disk_label="gpt" - -When used in standalone mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When used without the Compute service, the disk label should be set -directly to the node's ``instance_info`` field, as below:: - - ironic node-update add instance_info/capabilities='{"disk_label": "gpt"}' +.. toctree:: + :maxdepth: 1 + enabling-drivers + configure-pxe + configure-ipmi + configure-iscsi