diff --git a/deploy-guide/source/app-upgrade-openstack.rst b/deploy-guide/source/app-upgrade-openstack.rst
index 449e237..bd237b2 100644
--- a/deploy-guide/source/app-upgrade-openstack.rst
+++ b/deploy-guide/source/app-upgrade-openstack.rst
@@ -340,3 +340,53 @@ longer recommended) *or* ``bridge-mappings`` and ``data-port``.  Unfortunately,
 when upgrading from OpenStack Mitaka to Newton the referenced bug above was
 been encountered, and therefore may require manual intervention to resolve the
 issue.
+
+cinder/ceph topology change: upgrading from Newton to Ocata
+-----------------------------------------------------------
+
+.. warning::
+
+    Do not attempt to migrate a deployment with existing volumes to use the
+    cinder-ceph charm prior to Ocata.
+
+If cinder is directly related to ceph-mon rather than via the cinder-ceph
+charm then upgrading from Newton to Ocata will result in the loss of some
+block storage functionality, specifically live migration and snapshotting.
+To remedy this situation the deployment should migrate to using the
+cinder-ceph charm, this can be done after the upgrade to Ocata.
+
+Step 0: Check existing configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Confirm existing volumes are in rbd pool called 'cinder'
+
+.. code:: bash
+
+    $ juju run --unit cinder/0 "rbd --name client.cinder -p cinder ls"
+    volume-b45066d3-931d-406e-a43e-ad4eca12cf34
+    volume-dd733b26-2c56-4355-a8fc-347a964d5d55
+
+Step 1: Deploy new topology
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Deploy cinder-ceph charm and set the rbd-pool-name to match the
+pool that any existing volumes are in (see above):
+
+.. code:: bash
+
+    juju deploy --config rbd-pool-name=cinder cs:~openstack-charmers-next/cinder-ceph
+    juju add-relation cinder cinder-ceph
+    juju add-relation cinder-ceph ceph-mon
+    juju remove-relation cinder ceph-mon
+    juju add-relation cinder-ceph nova-compute
+
+Step 2: Update volume configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The existing volumes now need to be updated to associate them
+with the newly defined cinder-ceph backend:
+
+.. code:: bash
+
+    juju run-action cinder/0 rename-volume-host currenthost='cinder' \
+        newhost='cinder@cinder-ceph#cinder.volume.drivers.rbd.RBDDriver'