Add Prometheus 2.x deployment

It is now possible to deploy either 1.x or 2.x version of Prometheus.
The new 2.x version introduces breaking changes in terms of storage
format and command line options.

Change-Id: I80cc6f1947f3740ef04b29839bfa655b14fae146
Co-Authored-By: Radosław Piliszek <radoslaw.piliszek@gmail.com>

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/source/reference/logging-and-monitoring/prometheus-guide.rst b/doc/source/reference/logging-and-monitoring/prometheus-guide.rst
index 59afdda5b..ca5406fd1 100644
--- a/doc/source/reference/logging-and-monitoring/prometheus-guide.rst
+++ b/doc/source/reference/logging-and-monitoring/prometheus-guide.rst
@@ -20,6 +20,30 @@ and change the following:
 
    enable_prometheus: "yes"
 
+This will, by default, deploy Prometheus version 2.x. Since Prometheus 1.x data
+is not compatible with Prometheus 2.x and no automatic data migration is
+provided, any previous Prometheus 1.x deployment will be replaced and all its
+stored metrics will become inacessible (but still available in the old data
+volume: ``prometheus``; the new data volume defaults to ``prometheus_v2``).
+If you rely on Prometheus only as e.g. a source of alert notifications (in pair
+with Alertmanager), it might not be worth migrating old metrics and they could
+be discarded. Otherwise, it's either possible to use
+`remote storage <https://prometheus.io/docs/prometheus/latest/storage/#remote-storage-integrations>`_
+or scrape Kolla's Prometheus ``/federate`` endpoint with an external system.
+However, if you want to stay on 1.x series, set the following variable:
+
+.. code-block:: yaml
+
+   prometheus_use_v1: yes
+
+In order to remove leftover volume containing Prometheus 1.x data, execute:
+
+.. code-block:: console
+
+   docker volume rm prometheus
+
+on all hosts wherever Prometheus was previously deployed.
+
 Extending the default command line options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~