diff --git a/doc/source/deploy/upgrade-guide.rst b/doc/source/deploy/upgrade-guide.rst index 41ef7cd40d..b586ef1a5f 100644 --- a/doc/source/deploy/upgrade-guide.rst +++ b/doc/source/deploy/upgrade-guide.rst @@ -9,32 +9,56 @@ upgrading their ironic-driven clouds from previous versions of OpenStack. The ironic service is tightly coupled with the ironic driver that is shipped with nova. Some special considerations must be taken into account -when upgrading your cloud from previous versions of OpenStack. +when upgrading your cloud. -The `release notes `_ -should always be read carefully when upgrading the ironic service. Starting -with the Mitaka series, specific upgrade steps and considerations are -well-documented in the release notes. Specific upgrade considerations prior -to the Mitaka series are documented below. +Plan your Upgrade +================= -Upgrades are only supported one series at a time, or within a series. +* The `release notes `_ + should always be read carefully when upgrading the ironic service. Starting + with the Mitaka release, specific upgrade steps and considerations are + well-documented in the release notes. -General upgrades - all versions +* Upgrades are only supported one series at a time, or within a series. + +* Starting with the Liberty release, the ironic service should always be + upgraded before the nova service. + + .. note:: + The ironic virt driver in nova always uses a specific version of the + ironic REST API. This API version may be one that was introduced in the + same development cycle, so upgrading nova first may result in nova being + unable to use ironic's API. + +* When upgrading ironic, the following steps should always be taken: + + #. Update ironic code, without restarting services. + + #. Run database migrations. + + #. Restart ironic-conductor and ironic-api services. + + +Upgrading from Newton to Ocata +============================== + +There are no specific upgrade instructions other than the +`Ocata release notes `_. + + +Upgrading from Mitaka to Newton =============================== -Starting with the Liberty release, the ironic service should always be upgraded -before the nova service. The ironic virt driver in nova always uses a specific -version of the ironic REST API. This API version may be one that was introduced -in the same development cycle, so upgrading nova first may result in nova being -unable to use ironic's API. +There are no specific upgrade instructions other than the +`Newton release notes `_. -When upgrading ironic, the following steps should always be taken: -* Update ironic code, without restarting services yet. +Upgrading from Liberty to Mitaka +================================ -* Run database migrations +There are no specific upgrade instructions other than the +`Mitaka release notes `_. -* Restart ironic-conductor and ironic-api services. Upgrading from Kilo to Liberty ============================== @@ -42,47 +66,41 @@ Upgrading from Kilo to Liberty In-band Inspection ------------------ -If you used in-band inspection with **ironic-discoverd**, you have to install +If you used in-band inspection with **ironic-discoverd**, it is highly +recommended that you switch to using **ironic-inspector**, which is a newer +(and compatible on API level) version of the same service. You have to install **python-ironic-inspector-client** during the upgrade. This package contains a client module for the in-band inspection service, which was previously part of the **ironic-discoverd** package. Ironic Liberty supports the **ironic-discoverd** service, but does not support its in-tree client module. -Please refer to -`ironic-inspector version support matrix +Please refer to `ironic-inspector version support matrix `_ -for details on which ironic versions can work with which +for details on which ironic versions are compatible with which **ironic-inspector**/**ironic-discoverd** versions. -It's also highly recommended that you switch to using **ironic-inspector**, -which is a newer (and compatible on API level) version of the same service. - The discoverd to inspector upgrade procedure is as follows: -#. Install **ironic-inspector** on the machine where you have - **ironic-discoverd** (usually the same as conductor). +* Install **ironic-inspector** on the machine where you have + **ironic-discoverd** (usually the same as conductor). -#. (Recommended) update the **ironic-inspector** configuration file to stop - using deprecated configuration options, as marked by the comments in the - `example.conf - `_. +* Update the **ironic-inspector** configuration file to stop using deprecated + configuration options, as marked by the comments in the `example.conf + `_. + It is recommended you move the configuration file to + ``/etc/ironic-inspector/inspector.conf``. - The file name is provided on the command line when starting - **ironic-discoverd**, and the previously recommended default was - ``/etc/ironic-discoverd/discoverd.conf``. In this case, for the sake of - consistency it's recommended you move the configuration file to - ``/etc/ironic-inspector/inspector.conf``. +* Shutdown **ironic-discoverd**, and start **ironic-inspector**. -#. Shutdown **ironic-discoverd**, and start **ironic-inspector**. +* During upgrade of each conductor instance: -#. During upgrade of each conductor instance: + #. Shutdown the conductor. + #. Uninstall **ironic-discoverd**, + install **python-ironic-inspector-client**. + #. Update the conductor. + #. Update ``ironic.conf`` to use ``[inspector]`` section + instead of ``[discoverd]`` (option names are the same). + #. Start the conductor. - #. Shutdown the conductor - #. Uninstall **ironic-discoverd**, - install **python-ironic-inspector-client** - #. Update the conductor Kilo -> Liberty - #. (Recommended) update ``ironic.conf`` to use ``[inspector]`` section - instead of ``[discoverd]`` (option names are the same) - #. Start the conductor Upgrading from Juno to Kilo =========================== @@ -96,7 +114,7 @@ your nova and ironic services are as follows: - Edit nova.conf and ensure force_config_drive=False is set in the [DEFAULT] group. Restart nova-compute if necessary. -- Install new nova code, run database migrations +- Install new nova code, run database migrations. - Install new python-ironicclient code. - Restart nova services. - Install new ironic code, run database migrations, restart ironic services. @@ -110,15 +128,16 @@ upgrade has completed. Cleaning -------- -A new feature in Kilo is support for the automated cleaning of nodes between -workloads to ensure the node is ready for another workload. This can include -erasing the hard drives, updating firmware, and other steps. For more -information, see :ref:`automated_cleaning`. +A new feature starting from Kilo cycle is support for the automated cleaning +of nodes between workloads to ensure the node is ready for another workload. +This can include erasing the hard drives, updating firmware, and other steps. +For more information, see :ref:`automated_cleaning`. If ironic is configured with automated cleaning enabled (defaults to True) and -to use Neutron as the DHCP provider (also the default), you will need to set the -`cleaning_network_uuid` option in the ironic configuration file before starting -the Kilo ironic service. See `Configure the Bare Metal service for cleaning`_ -for information on how to set up the cleaning network for ironic. +neutron is set as the DHCP provider (also the default), you will need to set +the `cleaning_network_uuid` option in the ironic configuration file before +starting the ironic service. See +`Configure the Bare Metal service for cleaning`_ for information on how to set +up the cleaning network for ironic. .. _`Configure the Bare Metal service for cleaning`: http://docs.openstack.org/project-install-guide/baremetal/draft/configure-cleaning.html