From 2bb48c6196584807222fd0b19f002a096cb2ede9 Mon Sep 17 00:00:00 2001
From: Dmitry Tantsur <divius.inside@gmail.com>
Date: Thu, 3 Nov 2016 13:18:13 +0100
Subject: [PATCH] Document upgrade procedure

Change-Id: I4f013488ef1b7a605cca909e12f2b84c133ff3f4
---
 doc/source/index.rst   |  1 +
 doc/source/upgrade.rst | 29 +++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 doc/source/upgrade.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 5eb46ae6a..d2392152a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -18,6 +18,7 @@ Admin Guide
   :maxdepth: 2
 
   Installation <install>
+  Upgrade <upgrade>
 
 Developer Guide
 ===============
diff --git a/doc/source/upgrade.rst b/doc/source/upgrade.rst
new file mode 100644
index 000000000..549aed214
--- /dev/null
+++ b/doc/source/upgrade.rst
@@ -0,0 +1,29 @@
+==============================================
+Bare Metal Introspection Service Upgrade Guide
+==============================================
+
+The `release notes <http://docs.openstack.org/releasenotes/ironic-inspector/>`_
+should always be read carefully when upgrading the ironic-inspector service.
+Starting with the Mitaka series, specific upgrade steps and considerations are
+well-documented in the release notes.
+
+Upgrades are only supported one series at a time, or within a series.
+Only offline (with downtime) upgrades are currently supported.
+
+When upgrading ironic-inspector, the following steps should always be taken:
+
+* Update ironic-inspector code, without restarting the service yet.
+
+* Stop the ironic-inspector service.
+
+* Run database migrations::
+
+    ironic-inspector-dbsync --config-file <PATH-TO-INSPECTOR.CONF> upgrade
+
+* Start the ironic-inspector service.
+
+* Upgrade the ironic-python-agent image used for introspection.
+
+.. note::
+    There is no implicit upgrade order between ironic and ironic-inspector,
+    unless the `release notes`_ say otherwise.