(SIMP-8081) Upgrade Instructions for SIMP 6.5.0 (#387)

* Updated the General instructions to include updating
  the generated types
* Added specific instructions for 6.5.0
* Fix content + changelog, add sub-TOCs
* Extensively wordsmithed the 6.5.0 upgrade guide and changelog
  for clarity and consistency.
* Changed major steps in 6.5.0 from list items to section headers
* Revised content to better summarize steps in headers and explain the
  cause -> effect -> user action in upgrade guide, also to use correct
  terminology (e.g., `SVCKILL` -> `svckill`)
* Hyperlinks have been added to provide context
* Added Per-release TOCs to keep the upgrade guides for
  different releases from blending together.
* Formatting for inline ``sample`` blocks is more consistent
* Provided correct lexer for each `.. code-block` (preparation for
  CI linters like `rstcheck`)
* Most passages follow 80-char wraparound, when feasible
 Moved puppet server migration to a HOWTO since it is no longer
  necessarily applicable to upgrades.
* Added a link to the latest changelog so that it can be easily directly
  linked.
* Fixed tag

SIMP-8081 #close
SIMP-8352 #close
SIMP-8350 #close

Co-authored-by: Chris Tessmer <chris.tessmer@onyxpoint.com>
Co-authored-by: Trevor Vaughan <tvaughan@onyxpoint.com>
Co-authored-by: lnemsick-simp <lnemsick-simp@users.noreply.github.com>
Co-authored-by: Judy Johnson <judyfinkjohnson@gmail.com>

CHANGELOG

@@ -1,3 +1,6 @@
+* Tue Oct 06 2020 Jeanne Greulich <jeanne.greulich@onyxpoint.com>
+- Added upgrade instructions for 6.4.0 to 6.5.0
+
 * Wed Sep 30 2020 Trevor Vaughan <tvaughan@onyxpoint.com>
 - Added HOWTO for managing simplib::reboot_notify
 

docs/user_guide/HOWTO.rst

@@ -18,6 +18,7 @@ with more commonly sought items towards the top.
   Set up SSH Authorized Keys <HOWTO/SSH_Keys>
   Disable SSH Management <HOWTO/Disable_Ssh>
   Restrict SSH Network Access <HOWTO/SSH_Restrict_Network_Access>
+  Migrate to a New Puppet Server <HOWTO/Migrate_to_New_Puppet_Server>
   Enable SFTP Restricted Accounts <HOWTO/SFTP_Restricted_Accounts>
   Manage Reboot Notify <HOWTO/Manage_reboot_notify>
   Modify the Nightly Package Update Schedule <HOWTO/Control_Nightly_Update_Schedule>

docs/user_guide/HOWTO/Migrate_to_New_Puppet_Server.rst

@@ -0,0 +1,83 @@
+.. _howto-migrate-to-new-puppet-server:
+
+HOWTO Migrate to a New Puppet Server
+====================================
+
+Creating a new server and migrating clients
+-------------------------------------------
+
+The recommended method for upgrading **major** breaking changes (``X`` bump) is
+to create a new Puppet Server and migrate your data and clients to it. This
+process follows the path of least destruction; we will guide you through how to
+back up the existing Puppet server, create a new server, and transfer your
+clients.
+
+#. Set up a new Puppet server that will house your new SIMP environment.
+
+   .. NOTE::
+
+      You must ensure that this node can be reached by any client that is to be
+      migrated. The new system will not interfere with your existing Puppet
+      system unless you specifically configure it to do so.
+
+   .. IMPORTANT::
+
+      Do **NOT** destroy your old Puppet server until everything has been
+      successfully migrated and is in production under the new server.
+
+#. Consider vital services other than Puppet that are housed on your current
+   Puppet server node (e.g., DNS, DHCP, LDAP, custom kickstart, YUM, NFS, etc.).
+   You may choose to keep many of these services running on your old Puppet
+   server node. Anything not preserved must be migrated to a new system.
+
+
+Back Up the Existing Puppet Server
+----------------------------------
+
+Prior to any modifications to your infrastructure, we **highly** recommend
+following :ref:`ug-howto-back-up-the-puppet-master`.
+
+
+Create a New Server
+-------------------
+
+Obtain an `official SIMP ISO <https://download.simp-project.com/simp/ISO/>`_ or point your
+server at the latest `YUM Repositories: <https://download.simp-project.com/simp/yum/releases/latest>`_
+and follow the :ref:`gsg_iso_installation_options` or
+:ref:`gsg-installing_simp_from_a_repository` as appropriate.
+
+Follow the :ref:`Client_Management` guide, and set up services as needed.
+Remember, you can opt-out of any core services (DNS, DHCP, etc.)  you want your
+clients or old Puppet server to run! If you want the new Puppet server to run
+services the existing Puppet server ran, you may be able to use the backup of
+the ``rsync`` directories from the old system.
+
+.. WARNING::
+
+   Do not blindly drop ``rsync`` (or other) materials from the old Puppet
+   server onto the new one. The required structures for these components may
+   have changed.
+
+When you :ref:`ug-apply-certificates` you may wish to transfer client certs to
+the new server.  If you are using the FakeCA and still wish to preserve the
+certificates, follow the :ref:`ug-apply-certificates-official-certificates`
+guidance, and treat the existing Puppet server as your 'proper CA'.
+
+
+Promote the New Puppet Server and Transfer Your Clients
+-------------------------------------------------------
+
+Follow the :ref:`ug-howto-change-puppet-masters` guide to begin integration
+of your new Puppet server into the existing environment.
+
+.. NOTE::
+
+   You should *always* start migration with a small number of
+   **least critical** clients!
+
+
+Retire the Old Puppet Server
+----------------------------
+
+Once you have transferred the management of all your clients over to
+the new Puppet server, you may safely retire the old Puppet server.

docs/user_guide/Upgrade_SIMP/General_Upgrade_Instructions.rst

@@ -15,6 +15,9 @@ major numbers, in the format `X.Y.Z`:
 
 * ``X`` is the MAJOR release number, and indicates severe API-breaking changes.
 
+  * Updates to packages in the `simp-extras` RPM do not constitute a severe
+    API-breaking change.
+
 * ``Y`` is the MINOR release number, and indicates the addition of features or
   minor API-breaking changes either due to functionality bugs or after at least
   one MINOR release announcing the deprecation.
@@ -98,7 +101,7 @@ steps as ``root``:
    For SIMP 6.4 and later, this will also update the system-local, SIMP-managed
    Puppet module :term:`Git` repositories.
 
-#. If you are upgrading from a version before SIMP 6.4 you can skip to the last
+#. If you are upgrading from a version prior to SIMP 6.4 you can skip to the last
    step, *Apply the changes by running puppet*.
 
    ** **The following steps only apply for upgrades from version 6.4 or later**
@@ -108,9 +111,16 @@ steps as ``root``:
    ** **This ends the steps that are only for 6.4 or later.**  The next steps apply
    to all systems.
 
+#. Update the generated types for the environment
+
+   .. code-block:: sh
+
+     /usr/local/sbin/simp_generate_types -p /etc/puppetlabs/code/environments/test
+
 
 #. Apply the changes by running ``puppet``
 
+
    .. code-block:: sh
 
       puppet agent -t
@@ -130,14 +140,14 @@ Breaking Changes
 ~~~~~~~~~~~~~~~~
 
 If the ``X`` version number has changed then you should expect **major**
-breaking changes to the way SIMP works. Please carefully read the Changelog and
-the :ref:`simp-user-guide` and do **not** deploy these changes directly on top
-of your ``production`` environment.
+breaking changes to the way SIMP works. Please carefully read the
+:ref:`CHANGELOG<changelog-latest>` and the :ref:`simp-user-guide` and do **not**
+deploy these changes directly on top of your ``production`` environment.
 
 If the ``Y`` version number has changed then there may either be deprecation
 notices or **minor** breaking changes to the way SIMP works. Please carefully
-read the CHANGELOG and the User's Guide and do **not** deploy these changes
-directly on top of your production environment.
+read the :ref:`CHANGELOG<changelog-latest>` and the associated
+:ref:`ug-version-specific-upgrade-instructions`.
 
 .. IMPORTANT::
 
@@ -151,77 +161,7 @@ sets as required by their environment. That being said, the SIMP team does not
 test all combinations of modules and may have difficulty providing support for
 untested combinations.
 
-Creating a new server and migrating clients
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The recommended method for upgrading **major** breaking changes (``X`` bump) is
-to create a new Puppet Server and migrate your data and clients to it. This
-process follows the path of least destruction; we will guide you through how to
-back up the existing Puppet server, create a new server, and transfer your
-clients.
-
-#. Set up a new Puppet server that will house your new SIMP environment.
-
-   .. NOTE::
-
-      You must ensure that this node can be reached by any client that is to be
-      migrated. The new system will not interfere with your existing Puppet
-      system unless you specifically configure it to do so.
-
-   .. IMPORTANT::
-
-      Do **NOT** destroy your old Puppet server until everything has been
-      successfully migrated and is in production under the new server.
-
-#. Consider vital services other than Puppet that are housed on your current
-   Puppet server node (e.g., DNS, DHCP, LDAP, custom kickstart, YUM, NFS, etc.).
-   You may choose to keep many of these services running on your old Puppet
-   server node. Anything not preserved must be migrated to a new system.
-
-Back Up the Existing Puppet Server
-""""""""""""""""""""""""""""""""""
-
-Prior to any modifications to your infrastructure, we **highly** recommend
-following :ref:`ug-howto-back-up-the-puppet-master`.
-
-Create a New Server
-"""""""""""""""""""
-
-Obtain an `official SIMP ISO <https://download.simp-project.com/simp/ISO/>`_ or point your
-server at the latest `YUM Repositories: <https://download.simp-project.com/simp/yum/releases/latest>`_
-and follow the :ref:`gsg_iso_installation_options` or
-:ref:`gsg-installing_simp_from_a_repository` as appropriate.
-
-Follow the :ref:`Client_Management` guide, and set up services as needed.
-Remember, you can opt-out of any core services (DNS, DHCP, etc.)  you want your
-clients or old Puppet server to run! If you want the new Puppet server to run
-services the existing Puppet server ran, you may be able to use the backup of
-the ``rsync`` directories from the old system.
-
-.. WARNING::
-
-   Do not blindly drop ``rsync`` (or other) materials from the old Puppet
-   server onto the new one. The required structures for these components may
-   have changed.
-
-When you :ref:`ug-apply-certificates` you may wish to transfer client certs to
-the new server.  If you are using the FakeCA and still wish to preserve the
-certificates, follow the :ref:`ug-apply-certificates-official-certificates`
-guidance, and treat the existing Puppet server as your 'proper CA'.
-
-Promote the New Puppet Server and Transfer Your Clients
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-Follow the :ref:`ug-howto-change-puppet-masters` guide to begin integration
-of your new Puppet server into the existing environment.
-
-.. NOTE::
-
-   You should *always* start migration with a small number of
-   **least critical** clients!
-
-Retire the Old Puppet Server
-""""""""""""""""""""""""""""
-
-Once you have transferred the management of all your clients over to
-the new Puppet server, you may safely retire the old Puppet server.
+For releases moving from version of SIMP earlier than 6.3 to versions 6.4+, see
+:ref:`howto-migrate-to-new-puppet-server` for the simplest migration path. Also
+be sure to read the :ref:`ug-version-specific-upgrade-instructions` for all of
+the intermediate versions.

docs/user_guide/Upgrade_SIMP/Version_Maps/6.0.0_6.1.0.inc

@@ -3,6 +3,9 @@
 Upgrading from SIMP-6.0.0 to SIMP-6.1.0
 ---------------------------------------
 
+.. contents:: :local:
+   :depth: 3
+
 .. IMPORTANT::
 
    It is *highly recommended* that you read the information in this section

docs/user_guide/Upgrade_SIMP/Version_Maps/6.1.0_6.2.0.inc

@@ -3,6 +3,10 @@
 Upgrading from SIMP-6.1.0 to SIMP-6.2.0
 ---------------------------------------
 
+.. contents:: :local:
+   :depth: 3
+
+
 .. IMPORTANT::
 
    It is *highly recommended* that you read the information in this section

docs/user_guide/Upgrade_SIMP/Version_Maps/6.2.0_6.3.0.inc

@@ -3,6 +3,10 @@
 Upgrading from SIMP-6.2.0 to SIMP-6.3.0
 ---------------------------------------
 
+.. contents:: :local:
+   :depth: 3
+
+
 The main purpose of the SIMP 6.3 release is to upgrade to Puppet 5/Hiera 5. You
 should familiarize yourself with the `Puppet 5 release notes`_ and the
 `Hiera 5 upgrade`_ documents.

docs/user_guide/Upgrade_SIMP/Version_Maps/6.3.0_6.3.2.inc

@@ -3,6 +3,9 @@
 Upgrading from SIMP-6.3.0 to SIMP-6.3.2
 ---------------------------------------
 
+.. contents:: :local:
+   :depth: 3
+
 The 6.3.2 release of SIMP is a major bugfix release.
 
 You can follow :ref:`ug-incremental-upgrades` for upgrading.

docs/user_guide/Upgrade_SIMP/Version_Maps/6.3.2_6.3.3.inc

@@ -3,6 +3,9 @@
 Upgrading from SIMP-6.3.2 to SIMP-6.3.3
 ---------------------------------------
 
+.. contents:: :local:
+   :depth: 3
+
 The 6.3.3 release of SIMP is a bugfix release focusing on a specific issue with
 the updated ``sssd`` module that may cause account lockouts on upgrade
 depending on how your LDAP accounts have been maintained.

docs/user_guide/Upgrade_SIMP/Version_Maps/6.3.3_6.4.0.inc

@@ -3,6 +3,9 @@
 Upgrading from SIMP-6.3.3 to SIMP-6.4.0
 ---------------------------------------
 
+.. contents:: :local:
+   :depth: 3
+
 .. WARNING::
 
    You **MUST** be on at least SIMP 6.3.3 to upgrade to 6.4.0 due to issues in
@@ -195,8 +198,8 @@ environment you are updating.)
 
    # Make sure the umask is set properly
 
-   # Set the umask and Run r10k as the puppet group to make sure the modules
-   # to make sure the permissions and ownership are correct on the modules
+   # Set the umask and Run r10k as the puppet group to make sure 
+   # the permissions and ownership are correct on the modules
    ( umask 0027 && sg puppet -c '/usr/share/simp/bin/r10k puppetfile install \
    --puppetfile /etc/puppetlabs/code/environments/myenv/Puppetfile \
    --moduledir /etc/puppetlabs/code/environments/myenv/modules' )