Merge "Add some notes for users Migrating to Kolla Monasca"

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~