redhat-cop · jwesterd-redhat · Jul 3, 2023 · Jul 3, 2023 · Jul 5, 2023 · Jul 6, 2023
diff --git a/roles/analysis/README.md b/roles/analysis/README.md
@@ -1,26 +1,63 @@
 # Analysis
 
-The `analysis` role is used to create the Leapp pre-upgrade report on the target hosts. It also saves a copy of the current ansible facts under the `/etc/ansible/facts.d` directory for validation after upgrade.
+The `analysis` role is used to create the Leapp pre-upgrade report on the target hosts. This is used for IPU planning, as well as during execution of the IPU `upgrade` role.
+This role also saves a copy of the current ansible facts under the `/etc/ansible/facts.d` directory for validation after upgrade.
 
-The role is considered minimally invasive and hopefully will fly under the radar of your enterprise change management policy. That said, it does install the RHEL rpm packages that provide the Leapp framework if they are not already present. While application impact is very low, it may require a change ticket depending on how pedantic your policies are.
+The role is considered minimally invasive and as such should not complicate compliance with enterprise change management policy.  Installation of the software is isolated to dedicated RPMS.
+
+This could simplify use of a blanket change control for installation and execution. Running this role does install specific packages for the Leapp framework, if not already present.
+
+Leapp typically requires the following RPMs:  ( where X is current and Y is X+1 RHEL version )
+ - leapp
+ - leapp-deps
+ - leapp-upgrade-elXtoelY
+ - leapp-upgrade-elXtoelY-deps
+ - python3-leapp
+
+These RPMs do not overlap with typical system function, which reduces impact during their install.
 
 ## Requirements
 
-For non-CDN environments including Satellite, package metadata files needs to be provided. These files can be put on the host under the `/etc/leapp/files` directory before running the role. Alternatively, the `leapp_metadata_url` can be defined to tell the role where it can access the metadata tarball. For more information, refer to the knowledge article [Leapp utility metadata in-place upgrades of RHEL for disconnected upgrades (including Satellite)](https://access.redhat.com/articles/3664871).
+Metadata is required for leap preupgrade analysis to run.  When a system uses CDN, this is provided automatically.  For systems not on CDN, package metadata files needs to be provided by URL in leapp_metadata_url. Once obtained during IPU, file is unpacked on IPU host under `/etc/leapp/files` directory.
+
+For more information, refer to the knowledge article [Leapp utility metadata in-place upgrades of RHEL for disconnected upgrades (including Satellite)](https://access.redhat.com/articles/3664871).
 
 ## Role variables
 
-| Name                    | Default value         | Description                                         |
-|-------------------------|-----------------------|-----------------------------------------------------|
-| leapp_upgrade_type      | "satellite"           | Set to "cdn" for hosts registered with Red Hat CDN and "rhui" for hosts using rhui repos. |
-| leapp_metadata_url      |                       | See Requirements section above.                     |
-| leapp_answerfile        |                       | Optional multi-line string. If defined, this will be used as the contents of `/var/log/leapp/answerfile`. |
-| leapp_preupg_opts       |                       | Optional string to define command line options to be passed to the `leapp` command when running the pre-upgrade. |
-| post_reboot_delay       | 120                   | Optional integer to pass to the reboot post_reboot_delay option. |
+| Name                  | Type | Default value         | Description                                         |
+|-----------------------|------|-------------------------|-------------------------------------------------|
+| analysis_packages_el6 | List | leapp-upgrade             | RPMS that need to be installed for IPU to RHEL7 |
+| analysis_repos_el6    | List | rhel-7-server-extras-rpms | Repo to be enabled for IPU to RHEL7             |
+| analysis_packages_el7 | List | leapp-upgrade             | RPMS that need to be installed for IPU to RHEL7 |
+| analysis_repos_el7    | List | rhel-7-server-extras-rpms | Repo to be enabled for IPU to RHEL7 |
+| analysis_packages_el8 | List | leapp-upgrade | RPMS that need to be installed for IPU to RHEL8 |
+| analysis_repos_el8 | List | rhel-7-server-extras-rpms | Repo to be enabled for IPU to RHEL7             |
+| leapp_upgrade_type    | String  | satellite | satellite, cdn or rhui |
+| leapp_preupg_opt | String | --no-rhsm when leapp_upgrade_type is connected | Upstream repository usage - whether to use RHSM |
+| leapp_metadata_url      | String |  | URL to the leapp metadata, usually over https   |
+| leapp_enable_repos_args | String |  | --enablerepo (leapp_repos_enabled) or blank |
+| leapp_repos_enabled    | List | [] | Satellite repo for the satellite client RPM install |
+| result_filename | String |  | Path to file for the output of leapp (preupg) |
+| satellite_organization  | String | Example | Organization used in Satellite definition |
+| satellite_activation_key_leapp | String |  | Key used to identify activation key |
+| satellite_activation_key_pre_leapp | String |  | initial state of subscriptions and svc level |
+| satellite_activation_key_leapp     | String |  | Post-IPU state of subscriptions and svc level |
+| leapp_upgrade_type      | String | "disconnected"| Set to "connected" for hosts registered with Red Hat Subscription Manager and Red Hat CDN package repos. |
+| leapp_metadata_url | URL | | See Requirements section above. |
+| leapp_answerfile | TXT file | /var/log/leapp/answerfile | Optional - Source for Alternate AnswerFile needed during leapp process while upgrading  |
+| leapp_preupg_opts | String | | Optional string to define command line options to be passed to the `leapp` command when running the pre-upgrade. |
 
 ## Example playbook
 
-See [`analysis.yml`](../../playbooks/analysis.yml).
+See [`analysis.yml`](../../playbooks/analysis.yml)
+```
+- name: Include task for leapp preupgrade analysis
+  ansible.builtin.include_tasks: analysis-leapp.yml
+  when: ansible_distribution_major_version|int >= 7
+```
+
+## Authors
+author: Bob Mader, Mike Savage, Jeffrey Cutter, David Danielsson
 
 ## License
 

diff --git a/roles/common/README.md b/roles/common/README.md
@@ -1,21 +1,47 @@
-# Logging
+# Common role
 
-The `common` role is used to manage local log files that may help with debugging playbooks that include the `analysis` or `upgrade` roles. This role also implements a mutex locking mechanism that protects against accidentally running simultaneous playbook jobs on the same host.  Additionally this role provides common variables used by both `analysis` and `upgrade`.
+The `common` role is used to manage local log files that may help with debugging playbooks that include the `analysis` or `upgrade` roles.
 
-> **TODO**: The logging capability of this role currently deals only with writing local log files, but could be later extended to support logging to an aggregator like Logstash or Splunk.
+This role also implements a mutex locking mechanism that protects against accidentally running simultaneous playbook jobs on the same host.
 
-## Role variables
+Additionally this role provides common variables used by both `analysis` and `upgrade`.
 
-| Name                    | Default value         | Description                                         |
-|-------------------------|-----------------------|-----------------------------------------------------|
-| job_name                |                       | String to describe the job run.                     |
-| log_directory           | "/var/log/ripu"       | Directory under which local log files will be written. This directory will be created is it is not already present. |
-| log_file                | "{{ log_directory }}/ripu.log" | Local log filename. When a playbook job finishes, a timestamp suffix is appended to the end of the filename. |
+# Requirements
 
-## Example playbook
+Define job_name in the import as seen below
+
+# Role variables
+| Name                  | Type | Optional? | Default value | Description                                         |
+|-----------------------|--------|-----------|---------------|-------------------------------------------------|
+| job_name | String | No | The string describes the job run |
+| log_directory | DirPath | Yes | "/var/log/ripu" | Directory under which local log files will be written. This directory will be created is it is not already present. |
+| log_file | FilePath | Yes | "{{ log_directory }}/ripu.log" | Local log filename. When a playbook job finishes, a timestamp suffix is appended to the end of the specified filename. |
+
+ # Logging
+
+Logs will accumulate in the directory referenced by logfile, with a suffixed datestamp upon completion.
+
+If a log file exists during execution of this role (without suffixed datestamp), execution will terminate.
+
+Logs will not survive a rollback. They need to be removed off the system prior to a snapshot revert.
+
+# Example invocation
+```
+- name: Initialize lock, logging, and common vars
+  ansible.builtin.import_role:
+    name: infra.leapp.common
+  vars:
+    job_name: 'RIPU in-place OS upgrade'
+```
 
 This is a common role included by the `analysis` and `upgrade` roles. It does not need to be explicitly included in your playbook.
 
-## License
+
+# Authors
+Bob Mader, Scott Vick, Mike Savage, Jeffrey Cutter, David Danielsson
+
+# License
 
 MIT
+
+**TODO**: The logging capability of this role currently deals only with writing local log files, but could be later extended to support logging to an aggregator like Logstash or Splunk in support rollbacks and dashboard initiatives.