Add some notes for users Migrating to Kolla Monasca

This commit should help guide people migrating to Kolla Monasca
through the murky depths of the migration process. Since Kolla
did not support Monasca in Queens, some of these steps which
could be automated are not.

Change-Id: I79051cca27178c3cf1671f5c603e38baf929c55c

doc/source/reference/logging-and-monitoring/monasca-guide.rst

@@ -232,6 +232,88 @@ internal and external VIPs. Currently the Keystone authentication plugin is
 not configured and the HAProxy endpoints are protected by a password which is
 defined in `/etc/kolla/passwords.yml` under `kibana_password`.
 
+Migrating state from an existing Monasca deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These steps should be considered after Monasca has been deployed by Kolla. The
+aim here is to provide some general guidelines on how to migrate service
+databases. Migration of time series or log data is not considered.
+
+Migrating service databases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first step is to dump copies of the existing databases from wherever
+they are deployed. For example:
+
+.. code-block:: console
+
+   mysqldump -h 10.0.0.1 -u grafana_db_user -p grafana_db > grafana_db.sql
+   mysqldump -h 10.0.0.1 -u monasca_db_user -p monasca_db > monasca_db.sql
+
+These can then be loaded into the Kolla managed databases. Note that it
+simplest to get the database password, IP and port from the Monasca API Kolla
+config file in `/etc/kolla/monasca-api`. Note that the commands below drop and
+recreate each database before loading in the existing database.
+
+.. code-block:: console
+
+   mysql -h 192.168.0.1 -u monasca -p -e "drop database monasca_grafana; create database monasca_grafana;"
+   mysql -h 192.168.0.1 -u monasca -p monasca_grafana < grafana_db.sql
+
+A similar procedure is used to load the Monasca service database:
+
+.. code-block:: console
+
+   mysql -h 192.168.0.1 -u monasca -p -e "drop database monasca; create database monasca;"
+   mysql -h 192.198.0.1 -u monasca -p monasca < monasca_db.sql
+
+Migrating passwords
+^^^^^^^^^^^^^^^^^^^
+
+The next step is to set the Kolla Ansible service passwords so that they
+match the legacy services. The alternative of changing the passwords to match
+the passwords generated by Kolla Ansible is not considered here.
+
+The passwords which you may wish to set to match the original passwords are:
+
+.. code-block:: console
+
+   monasca_agent_password:
+   monasca_grafana_admin_password:
+
+These can be found in the Kolla Ansible passwords file.
+
+Stamping the database with an Alembic revision ID (migrations from pre-Rocky)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Kolla Ansible supports deploying Monasca from the Rocky release onwards. If
+you are migrating from Queens or below, your database will not have been
+stamped with a revision ID by Alembic, and this will not be automatic.
+Support for Alembic migrations was added to Monasca in the Rocky release.
+You will first need to make sure that the database you have loaded in has
+been manually migrated to the Queens schema. You can then stamp the database
+from any Monasca API container running the Rocky release onwards. An example
+of how this can be done is given below:
+
+.. code-block:: console
+
+   sudo docker exec -it monasca_api monasca_db stamp --from-fingerprint
+
+Applying the configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Restart Monasca services on all nodes, for example:
+
+.. code-block:: console
+
+   for service in `docker ps | grep monasca_ | awk '{print $11}'`; do docker restart $service; done
+
+Apply the password changes by running the following command:
+
+.. code-block:: console
+
+   kolla-ansible reconfigure -t monasca
+
 System requirements and performance impact
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~