leapp/0004-Post-release-doc-update-817.patch

From 5c4d39e33138fdaa5d65507581e9eb3703439cef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20Stod=C5=AFlka?= <pstodulk@redhat.com>
Date: Mon, 24 Apr 2023 12:57:04 +0200
Subject: [PATCH 04/18] Post release doc update (#817)

* Doc: update the list of environment variables

* Added:
  - LEAPP_DATABASE_FORCE_SYNC_ON
  - LEAPP_NOGPGCHECK
  - LEAPP_NO_INSIGHTS_REGISTER
  - LEAPP_NO_RHSM_FACTS
  - LEAPP_TARGET_ISO
  - LEAPP_DEVEL_INITRAM_NETWORK

Co-authored-by: Matej Matuska <mmatuska@redhat.com>
Co-authored-by: Miriam Portman <74915975+mportman12@users.noreply.github.com>

* Doc: replace tags & flags in the reporting guidelines

`reporting.Tags` and `reporting.Flags` have been deprecated by
`reporting.Groups` in the past. Even when they are still accepted,
it's better to learn people they should use `reporting.Groups`
nowadays.

Keeping reference about original divisions into Tags and Flags.

Co-authored-by: Miriam Portman <74915975+mportman12@users.noreply.github.com>

---------

Co-authored-by: Matej Matuska <mmatuska@redhat.com>
Co-authored-by: Miriam Portman <74915975+mportman12@users.noreply.github.com>
---
 docs/source/el7toel8/actor-rhel7-to-rhel8.md  | 19 +++++---
 docs/source/el7toel8/envars.md                | 46 ++++++++++++++++++-
 .../source/el7toel8/inhibit-rhel7-to-rhel8.md | 13 +++---
 3 files changed, 62 insertions(+), 16 deletions(-)

diff --git a/docs/source/el7toel8/actor-rhel7-to-rhel8.md b/docs/source/el7toel8/actor-rhel7-to-rhel8.md
index a6ecf37..f4e45d4 100644
--- a/docs/source/el7toel8/actor-rhel7-to-rhel8.md
+++ b/docs/source/el7toel8/actor-rhel7-to-rhel8.md
@@ -172,8 +172,7 @@ class MyNewActor(Actor):
                                 'adopting-rhel-8#btrfs-has-been-removed_file-systems-and-storage'
                         ),
                         reporting.Severity(reporting.Severity.HIGH),
-                        reporting.Flags([reporting.Flags.INHIBITOR]),
-                        reporting.Tags([reporting.Tags.FILESYSTEM]),
+                        reporting.Groups([reporting.Groups.INHIBITOR, reporting.Groups.FILESYSTEM]),
                         reporting.RelatedResource('driver', 'btrfs')
                     ])
                     break
@@ -238,20 +237,26 @@ reporting.Remediation(hint='Please remove the dropped options from your scripts.
 reporting.Remediation(playbook=<link_to_playbook>)
 ```
 
-**Available tags**
+**Available Groups**
 
+The following groups were originally known as **Tags**:
 ```
 'accessibility', 'authentication', 'boot', 'communication', 'drivers', 'email', 'encryption',
 'filesystem', 'firewall', 'high availability', 'kernel', 'monitoring', 'network', 'OS facts',
-'python', 'repository', 'sanity', 'security', 'selinux', 'services', 'time management',
+'post', 'python', 'repository', 'sanity', 'security', 'selinux', 'services', 'time management',
 'tools', 'upgrade process'
 ```
 
-In case of more report message tags then currently provided is needed, please open a GH issue or a PR.
+The following groups were originally known as **Flags**:
+```
+'failure', 'inhibitor'
+```
 
-**Flags**
+The **failure** Group is recommended to be used when the report is related to
+a command or other action failure.
 
-Besides the above mentioned **"inhibitor"** flag, there is also a **"failure"** flag which is recommended to use when we report a command or other action failure.
+If you need additional report groups, please open a GH issue or a PR,
+with the description why new required groups are needed.
 
 **Related resources**
 
diff --git a/docs/source/el7toel8/envars.md b/docs/source/el7toel8/envars.md
index fafadda..fcc1ea3 100644
--- a/docs/source/el7toel8/envars.md
+++ b/docs/source/el7toel8/envars.md
@@ -15,8 +15,9 @@ Overrides the automatically detected storage device with GRUB core (e.g.
 
 ## LEAPP_NO_RHSM
 
-Do not use Red Hat Subscription Management for the upgrade. Using it has the
-same effect as using the `--no-rhsm` leapp option.
+If set to 1, Leapp does not use Red Hat Subscription Management for the upgrade.
+It's equivalent to the `--no-rhsm` leapp option.
+
 
 ## LEAPP_OVL_SIZE
 
@@ -79,6 +80,34 @@ case they are changed. However, in some cases it's not wanted and it leads
 in malfunction network configuration (e.g. in case the bonding is configured
 on the system). It's expected that NICs have to be handled manually if needed.
 
+## LEAPP_DATABASE_FORCE_SYNC_ON
+
+If set to 1, Leapp will explicitly enable synchronization on the SQLite database.
+Enabling the synchronization has negative impact on the performance
+(sometimes very negative). However, it is more reliable in case of extreme
+situations (e.g. lost power).
+Note the synchronization is nowadays switched off by default only during the phases
+executed before the reboot of the system to the upgrade environment, which we consider
+safe. As a result, we do not expect that someone would want to use this option now.
+
+## LEAPP_NO_INSIGHTS_REGISTER
+
+If set to 1, Leapp does not register the system into Red Hat Insights automatically.
+It's equivalent to the `--no-insights-register` leapp option.
+
+## LEAPP_NO_RHSM_FACTS
+If set to 1, Leapp does not store migration information using Red Hat Subscription Manager.
+It's equivalent to the `--no-rhsm-facts` leapp option.
+
+## LEAPP_NOGPGCHECK
+Set to 1 to disable RPM GPG checks (same as yum/dnf --nogpgckeck option).
+It's equivalent to the `--nogpgcheck` leapp option.
+
+## LEAPP_TARGET_ISO
+Set the path to the target OS ISO image that should be used for the IPU.
+It's equivalent to the `--iso` leapp option.
+
+
 ## LEAPP_UNSUPPORTED
 
 Necessary to use in case you use any envar with the LEAPP_DEVEL prefix
@@ -146,3 +175,16 @@ If set to 1, leapp will disable explicit synchronization on the SQLite
 database. The positive effect is significant speed up of the leapp execution,
 however it comes at the cost of risking a corrupted database, so it is
 currently used for testing / development purposes, only.
+
+## LEAPP_DEVEL_INITRAM_NETWORK
+You can specify one of the following values: 'network-manager', 'scripts'.
+The 'scripts' value is used for a legacy dracut module when the network is not
+handled by NetworkManager.
+Using the option allows experimental upgrades, bringing up the networking inside
+the upgrade initramfs environment (upgrade phases after the first reboot).
+It also allows the upgrade e.g. when a network based storage is used
+on the system. Currently it works only for the most simple configurations
+(e.g. when only 1 NIC is present, no rdma, no bonding, ...). Network based
+storage is not handled anyhow during the upgrade, so it's possible that the network
+based storage will not be correctly initialized and usable as expected).
+
diff --git a/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md b/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md
index a20f258..5e97c78 100644
--- a/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md
+++ b/docs/source/el7toel8/inhibit-rhel7-to-rhel8.md
@@ -6,7 +6,7 @@ With latest changes on Leapp and with new actors added to the el7toel8 Leapp
 repository, any actor can inhibit the upgrade process by producing a specific
 message when a problem is found. The message model to use in this case is
 [Report](pydoc/leapp.reporting.html#leapp.reporting.Report).
-If there is at least one Report message with `'inhibitor'` flag produced before
+If there is at least one Report message with the `'inhibitor'` group produced before
 the Report phase, the upgrade will be stopped in the Reports phase, in which the
 messages are being collected. It means that any Report message produced
 **after** the Report phase will **not** have inhibiting effect. The details
@@ -57,7 +57,7 @@ If, instead of only adding a message to the log, the actor writer wants to make
 sure that the upgrade process will be stopped in case of unsupported arch, the
 actor needs to produce a [Report](/pydoc/leapp.reporting.html#leapp.reporting.Report)
 message using one of the `report_*` functions from the [reporting](https://github.com/oamg/leapp-repository/blob/master/repos/system_upgrade/el7toel8/libraries/reporting.py)
-shared library with `'inhibitor'` flag.
+shared library with the `'inhibitor'` group.
 
 ```python
 import platform
@@ -87,8 +87,7 @@ class CheckSystemArch(Actor):
                 reporting.Title('Unsupported architecture'),
                 reporting.Summary('Upgrade process is only supported on x86_64 systems.'),
                 reporting.Severity(reporting.Severity.HIGH),
-                reporting.Tags([reporting.Tags.SANITY]),
-                reporting.Flags([reporting.Flags.INHIBITOR])
+                reporting.Groups([reporting.Groups.INHIBITOR, reporting.Groups.SANITY]),
             ])
 ```
 
@@ -110,7 +109,7 @@ $ snactor run CheckSystemArch --verbose --print-output
     "phase": "NON-WORKFLOW-EXECUTION",
     "message": {
       "hash": "dc95adcfca56eae62b7fcceeb0477a6d8257c3dddd1b05b879ebdcf05f59d504",
-      "data": "{\"report\": \"{\\\"audience\\\": \\\"sysadmin\\\", \\\"flags\\\": [\\\"inhibitor\\\"], \\\"severity\\\": \\\"high\\\", \\\"summary\\\": \\\"Upgrade process is only supported on x86_64 systems.\\\", \\\"tags\\\": [\\\"sanity\\\"], \\\"title\\\": \\\"Unsupported architecture\\\"}\"}"
+      "data": "{\"report\": \"{\\\"audience\\\": \\\"sysadmin\\\", \\\"groups\\\": [\\\"inhibitor\\\", \\\"sanity\\\"], \\\"severity\\\": \\\"high\\\", \\\"summary\\\": \\\"Upgrade process is only supported on x86_64 systems.\\\", \\\"title\\\": \\\"Unsupported architecture\\\"}\"}"
     },
     "type": "Report"
   }
@@ -123,7 +122,7 @@ Or to inspect closely the message.data field, we could use `jq` tool:
 ```sh
 snactor run CheckSystemArch --verbose --print-output | jq '.[] | .message.data | fromjson'
 {
-  "report": "{\"audience\": \"sysadmin\", \"flags\": [\"inhibitor\"], \"severity\": \"high\", \"summary\": \"Upgrade process is only supported on x86_64 systems.\", \"tags\": [\"sanity\"], \"title\": \"Unsupported architecture\"}"
+  "report": "{\"audience\": \"sysadmin\", \"groups\": [\"inhibitor\", \"sanity\"], \"severity\": \"high\", \"summary\": \"Upgrade process is only supported on x86_64 systems.\", \"title\": \"Unsupported architecture\"}"
 }
 
 ```
@@ -134,7 +133,7 @@ present on the system and inhibit the upgrade process based on that check.
 After all the system checks are executed by different actors, an existing actor
 named [VerifyCheckResults](https://github.com/oamg/leapp-repository/tree/master/repos/system_upgrade/el7toel8/actors/verifycheckresults)
 is scheduled to run in the Leapp upgrade workflow. If some [Report](/pydoc/leapp.reporting.html#leapp.reporting.Report)
-message with `'inhibitor'` flag was generated by some previous execution of
+message with the `'inhibitor'` group was generated by some previous execution of
 another actor in any previous phase of the workflow, like the sample one we just
 wrote, the following output will be displayed to the user:
 
-- 
2.41.0