Merge pull request #2122 from mwringe/metrics-upgrade

Add docs on how to upgrade the metrics components between versions.

Author: tnguyen-rh

install_config/upgrading/automated_upgrades.adoc

@@ -210,9 +210,11 @@ used, if needed.
 ----
 
 When the upgrade finishes, a recommendation will be printed to reboot all hosts.
-After rebooting, continue to
-link:#automated-upgrading-efk-logging-stack[Upgrading the EFK Logging Stack] if
-you have aggregated logging enabled, otherwise proceed to
+After rebooting, if you have aggregated logging enable you will need to follow steps outlined in the
+link:#automated-upgrading-efk-logging-stack[Upgrading the EFK Logging Stack] section,
+if you have cluster metrics enabled you will need to follow the setps outlined in the 
+link:#automated-upgrading-cluster-metrics[Upgrading Cluster Metrics] section,
+ otherwise proceed to
 link:#verifying-the-upgrade[Verifying the Upgrade].
 
 [[upgrading-to-openshift-enterprise-3-2-asynchronous-releases]]
@@ -239,6 +241,16 @@ images, the steps must be performed manually as shown in
 link:../../install_config/upgrading/manual_upgrades.html#manual-upgrading-efk-logging-stack[Manual
 Upgrades].
 
+[[automated-upgrading-cluster-metrics]]
+== Upgrading Cluster Metrics
+
+If you have previously link:../../install_config/cluster_metrics.html[deployed
+cluster metrics] you will need to update to the latest metric components, the steps must 
+be performed manually as shown in 
+link:../../install_config/upgrading/manual_upgrades.html#manual-upgrading-cluster-metrics[Manual
+Upgrades].
+
+
 [[verifying-the-upgrade]]
 == Verifying the Upgrade
 

install_config/upgrading/manual_upgrades.adoc

@@ -908,6 +908,58 @@ in previous versions. There should be minimal performance impact to
 Elasticsearch while running this and it will not perform an install.
 ====
 
+[[manual-upgrading-cluster-metrics]]
+== Upgrading Cluster Metrics
+
+Use the following to upgrade an
+link:../../install_config/cluster_metrics.html[already-deployed Cluster Metrics install].
+
+To update to a newer version of the metrics components you will need to use the `refresh`
+mode of the deployer. This will stop all the metrics containers, update the metrics configuration
+files and redeploy the newer components. The `refresh` option will not change the metrics route or
+delete the metrics persistent volume claim.
+
+Metrics stored to persistent volumes will still contain the persisted data when the updated
+metrics are brought back online. 
+
+[IMPORTANT]
+====
+All non-persisted metric values will be lost during the metric `refresh`.
+
+All local changes to the metrics configurations will be overwritten with new configurations meant for the latest install.
+This includes things like number of instances in a replica set.
+====
+
+To perform the update you will need to follow the
+link:../../install_config/cluster_metrics.html#deploying-the-metrics-components[same steps]
+as when the metrics components were first deployed except this time you will need to specify the
+`MODE=refresh` option.
+
+You will also need to make sure you are using the correct template for your installation. Please see the following
+link:../../install_config/cluster_metrics.html#modifying-the-deployer-template[section] for the location of this template.
+
+For instance, if before you deployed metrics using:
+
+----
+$ oc new-app -f metrics-deployer.yaml \
+    -p HAWKULAR_METRICS_HOSTNAME=hawkular-metrics.example.com
+----
+
+You will now need to run:
+----
+$ oc new-app -f metrics-deployer.yaml \
+    -p HAWKULAR_METRICS_HOSTNAME=hawkular-metrics.example.com,MODE=redeploy
+----
+
+After this the metrics components should have been restarted and are now using the most recent versions.
+
+
+[NOTE]
+====
+It is normal to see a gap in the graphs during the time when the `refresh` is occuring. This is due to the
+metrics components not running and being available to gather metrics during this time.
+====
+
 [[additional-instructions-per-release]]
 == Additional Manual Steps Per Release