(MODULES-10644)

Document the binary upgrade process.

Author: binford2k

README.md

@@ -113,10 +113,31 @@ tomcat::config::server::connector { 'tomcat7-ajp':
 
 > Note: look up the correct version you want to install on the [version list](http://tomcat.apache.org/whichversion.html).
 
+### I want to upgrade the version of Tomcat to use
+
+See information about running multiple versions above. Instead of upgrading in-place, install a second version to a new directory and then point the `catalina_home` of your instance to it. This gives you the ability to validate and rollback if needed. After validation, you may remove the older instance if you'd like.
+
+```puppet
+class { 'java': }
+
+tomcat::install { '/opt/tomcat/9.0.24':
+  source_url => 'https://www-us.apache.org/dist/tomcat/tomcat-9/v9.0.24/bin/apache-tomcat-9.0.24.tar.gz'
+}
+tomcat::install { '/opt/tomcat/9.0.44':
+  source_url => 'https://www-us.apache.org/dist/tomcat/tomcat-9/v9.0.44/bin/apache-tomcat-9.0.44.tar.gz'
+}
+tomcat::instance { 'my_tomcat_app':
+# catalina_home => '/opt/tomcat/9.0.24',
+  catalina_home => '/opt/tomcat/9.0.44',
+  catalina_base => '/opt/my_tomcat_app',
+}
+```
+
+
 ### I want to configure SSL and specify which protocols and ciphers to use
 
 ```puppet
-  file { $keystore_path: 
+  file { $keystore_path:
     ensure => present,
     source => $keystore_source,
     owner => $keystore_user,
@@ -139,7 +160,7 @@ tomcat::config::server::connector { 'tomcat7-ajp':
       'sslProtocol'         => $https_connector_ssl_protocol,
       'sslEnabledProtocols' => join($https_connector_ssl_protocols_enabled, ","),
       'ciphers'             => join($ciphers_enabled, ","),
-      
+
       'keystorePass'        => $keystore_pass.unwrap,
       'keystoreFile'        => $keystore_path,
     },