diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 1bb6b7dfe3..b12df1e51e 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -14,6 +14,7 @@ the services.
Installation Guide </install/index>
gmr
Upgrade Guide <upgrade-guide>
+ upgrade-to-hardware-types
Release Notes <http://docs.openstack.org/releasenotes/ironic/>
Troubleshooting FAQ <troubleshooting>
diff --git a/doc/source/admin/upgrade-guide.rst b/doc/source/admin/upgrade-guide.rst
index d5f4edc45c..1b9570d351 100644
--- a/doc/source/admin/upgrade-guide.rst
+++ b/doc/source/admin/upgrade-guide.rst
@@ -48,6 +48,11 @@ Upgrading from Ocata to Pike
<https://docs.openstack.org/project-install-guide/baremetal/draft/enrollment.html#enrollment-process>`_
for details.
+#. It is recommended to move from old-style classic drivers to the new
+ hardware types after the upgrade to Pike. We expect the classic drivers to
+ be deprecated in the Queens release and removed in the Rocky release.
+ See :doc:`upgrade-to-hardware-types` for the details on the migration.
+
Other upgrade instructions are in the `Pike release notes
<https://docs.openstack.org/releasenotes/ironic/pike.html>`_.
diff --git a/doc/source/admin/upgrade-to-hardware-types.rst b/doc/source/admin/upgrade-to-hardware-types.rst
new file mode 100644
index 0000000000..90896951d3
--- /dev/null
+++ b/doc/source/admin/upgrade-to-hardware-types.rst
@@ -0,0 +1,199 @@
+Upgrading to Hardware Types
+===========================
+
+In the future, the Bare Metal service will stop supporting *classic drivers*
+and will only support *hardware types*. Please see
+:doc:`/install/enabling-drivers` for the detailed explanation of the
+difference between these two types of drivers.
+
+Planning the upgrade
+--------------------
+
+It is necessary to figure out which hardware types and hardware interfaces
+correspond to which classic drivers used in your deployment.
+Use the following table:
+
+================ ============= ======== ====== ========== =========
+ Classic Driver Hardware Type Boot Deploy Management Power
+================ ============= ======== ====== ========== =========
+pxe_ipmitool ipmi pxe iscsi ipmitool ipmitool
+agent_ipmitool ipmi pxe direct ipmitool ipmitool
+================ ============= ======== ====== ========== =========
+
+.. TODO(dtantsur): finish this table
+
+.. warning::
+ This table does not currently cover hardware interfaces other than
+ boot, deploy, management and power.
+
+.. note::
+ For out-of-tree drivers you may need to reach out to their maintainers or
+ figure out the appropriate interfaces by researching the source code.
+
+Configuration
+-------------
+
+You will need to enable hardware types and interfaces that correspond to your
+currently enabled classic drivers. For example, if you have the following
+configuration in your ``ironic.conf``:
+
+.. code-block:: ini
+
+ [DEFAULT]
+ enabled_drivers = pxe_ipmitool,agent_ipmitool
+
+You will have to add this configuration as well:
+
+.. code-block:: ini
+
+ [DEFAULT]
+ enabled_hardware_types = ipmi
+ enabled_boot_interfaces = pxe
+ enabled_deploy_interfaces = iscsi,direct
+ enabled_management_interfaces = ipmitool
+ enabled_power_interfaces = ipmitool
+
+.. note::
+ For every interface type there is an option
+ ``default_<INTERFACE>_interface``, where ``<INTERFACE>`` is the interface
+ type name. For example, one can make all nodes use the ``direct`` deploy
+ method by default by setting:
+
+ .. code-block:: ini
+
+ [DEFAULT]
+ default_deploy_interface = direct
+
+Migrating nodes
+---------------
+
+After the required items are enabled in the configuration, each node's
+``driver`` field has to be updated to a new value. You may need to also
+set new values for some or all interfaces:
+
+.. code-block:: console
+
+ export OS_BAREMETAL_API_VERSION=1.31
+
+ for uuid in $(openstack baremetal node list --driver pxe_ipmitool -f value -c UUID); do
+ openstack baremetal node set $uuid --driver ipmi --deploy-interface iscsi
+ done
+
+ for uuid in $(openstack baremetal node list --driver agent_ipmitool -f value -c UUID); do
+ openstack baremetal node set $uuid --driver ipmi --deploy-interface direct
+ done
+
+See :doc:`/install/enrollment` for more details on setting hardware types and
+interfaces.
+
+Other interfaces
+----------------
+
+Care has to be taken to migrate from classic drivers using non-default
+interfaces. This chapter covers a few of the most commonly used.
+
+Ironic Inspector
+~~~~~~~~~~~~~~~~
+
+Some classic drivers, notably ``pxe_ipmitool``, ``agent_ipmitool`` and
+``pxe_drac_inspector``, use ironic-inspector_ for their *inspect* interface.
+
+The same functionality is available for all hardware types, but the appropriate
+``inspect`` interface has to be enabled in the Bare Metal service configuration
+file, for example:
+
+.. code-block:: ini
+
+ [DEFAULT]
+ enabled_inspect_interfaces = inspector,no-inspect
+
+See :doc:`/install/enabling-drivers` for more details.
+
+.. note::
+ The configuration option ``[inspector]enabled`` does not affect hardware
+ types.
+
+Then you can tell your nodes to use this interface, for example:
+
+.. code-block:: console
+
+ export OS_BAREMETAL_API_VERSION=1.31
+ for uuid in $(openstack baremetal node list --driver ipmi -f value -c UUID); do
+ openstack baremetal node set $uuid --inspect-interface inspector
+ done
+
+.. note::
+ A node configured with the IPMI hardware type, will use the inspector
+ inspection implementation automatically if it is enabled. This is not
+ the case for the most of the vendor drivers.
+
+.. _ironic-inspector: https://docs.openstack.org/ironic-inspector/
+
+Console
+~~~~~~~
+
+Several classic drivers, notably ``pxe_ipmitool_socat`` and
+``agent_ipmitool_socat``, use socat-based serial console implementation.
+
+For the ``ipmi`` hardware type it is used by default, if enabled in the
+configuration file:
+
+.. code-block:: ini
+
+ [DEFAULT]
+ enabled_console_interfaces = ipmitool-socat,no-console
+
+If you want to use the ``shellinabox`` implementation instead, it has to be
+enabled as well:
+
+.. code-block:: ini
+
+ [DEFAULT]
+ enabled_console_interfaces = ipmitool-shellinabox,no-console
+
+Then you need to update some or all nodes to use it explicitly. For example,
+to update all nodes use:
+
+.. code-block:: console
+
+ export OS_BAREMETAL_API_VERSION=1.31
+ for uuid in $(openstack baremetal node list --driver ipmi -f value -c UUID); do
+ openstack baremetal node set $uuid --console-interface ipmitool-shellinabox
+ done
+
+RAID
+~~~~
+
+Many classic drivers, including ``pxe_ipmitool`` and ``agent_ipmitool`` use
+the IPA-based in-band RAID implementation by default.
+
+For the hardware types it is not used by default. To use it, you need to
+enable it in the configuration first:
+
+.. code-block:: ini
+
+ [DEFAULT]
+ enabled_raid_interfaces = agent,no-raid
+
+Then you can update those nodes that support in-band RAID to use the ``agent``
+RAID interface. For example, to update all nodes use:
+
+.. code-block:: console
+
+ export OS_BAREMETAL_API_VERSION=1.31
+ for uuid in $(openstack baremetal node list --driver ipmi -f value -c UUID); do
+ openstack baremetal node set $uuid --raid-interface agent
+ done
+
+.. note::
+ The ability of a node to use the ``agent`` RAID interface depends on
+ the ramdisk (more specifically, a `hardware manager`_ used in it),
+ not on the driver.
+
+.. _hardware manager: https://docs.openstack.org/ironic-python-agent/latest/contributor/hardware_managers.html
+
+Network and storage
+~~~~~~~~~~~~~~~~~~~
+
+The network and storage interfaces have always been dynamic, and thus do not
+require any special treatment during upgrade.
diff --git a/doc/source/install/enrollment.rst b/doc/source/install/enrollment.rst
index 6fc6d54d3f..148318a66e 100644
--- a/doc/source/install/enrollment.rst
+++ b/doc/source/install/enrollment.rst
@@ -178,7 +178,9 @@ and may be combined if desired.
pick which hardware interface to use with nodes that use hardware types.
Each interface is represented by a node field called ``<IFACE>_interface``
where ``<IFACE>`` in the interface type, e.g. ``boot``. See
- :doc:`enabling-drivers` for details on hardware interfaces.
+ :doc:`enabling-drivers` for details on hardware interfaces and
+ :doc:`/admin/upgrade-to-hardware-types` for the matching between classic
+ drivers and hardware types.
An interface can be set either separately: