Add more context to containerized uninstall (#2679)

* Add more context to containerized uninstall

Adds information about preserving secret keys before performing a containerised uninstall with preserved database.

automation gateway migration exits with code 1 failing install on re-run of installer (documentation missing for indicating secret keys to reuse)

https://issues.redhat.com/browse/AAP-35751

* updates based on peer review feedback

Author: michellemacrh

downstream/assemblies/platform/assembly-aap-containerized-installation.adoc

@@ -71,6 +71,7 @@ include::platform/proc-add-eda-safe-plugin-var.adoc[leveloffset=+1]
 include::platform/proc-update-aap-container.adoc[leveloffset=+1]
 include::platform/proc-backup-aap-container.adoc[leveloffset=+1]
 include::platform/proc-uninstalling-containerized-aap.adoc[leveloffset=+1]
+include::platform/proc-reinstalling-containerized-aap.adoc[leveloffset=+1]
 
 
 ifdef::parent-context-of-aap-containerized-installation[:context: {parent-context-of-aap-containerized-installation}]

downstream/modules/platform/proc-reinstalling-containerized-aap.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="reinstalling-containerized-aap_{context}"]
+= Reinstalling containerized {PlatformNameShort}
+
+[role="_abstract"]
+
+To reinstall a containerized deployment after uninstalling and preserving the database, run the `install.yml` playbook and include the existing secret key value:
+----
+$ ansible-playbook -i inventory ansible.containerized_installer.install -e controller_secret_key=<secret_key_value>
+----
+
+For more information about the `*_secret_key` variables, see link:{URLContainerizedInstall}/appendix-inventory-files-vars[Inventory file variables].

downstream/modules/platform/proc-uninstalling-containerized-aap.adoc

@@ -5,6 +5,18 @@
 
 [role="_abstract"]
 
+When performing a reinstall following an uninstall that preserves the databases, you must use the previously generated {PlatformNameShort} secret key values to access the preserved databases.
+
+Before running the uninstall, collect the existing secret keys by running the following command:
+----
+$ podman secret inspect --showsecret <secret_key_variable> | jq -r .[].SecretData
+----
+For example:
+----
+$ podman secret inspect --showsecret controller_secret_key | jq -r .[].SecretData
+----
+
+For more information about the `*_secret_key` variables, see link:{URLContainerizedInstall}/appendix-inventory-files-vars[Inventory file variables].
 
 To uninstall a containerized deployment, run the `uninstall.yml` playbook:
 ----
@@ -13,22 +25,19 @@ $ ansible-playbook -i inventory ansible.containerized_installer.uninstall
 
 This stops all systemd units and containers and then deletes all resources used by the containerized installer such as:
 
-* config and data directories and files
+* configuration and data directories and files
 * systemd unit files
 * Podman containers and images
 * RPM packages
 
-To keep container images, you can set the `container_keep_images` variable to `true`.
+To keep container images, set the `container_keep_images` variable to `true`.
 ----
 $ ansible-playbook -i inventory ansible.containerized_installer.uninstall -e container_keep_images=true
 ----
 
-To keep PostgreSQL databases, you can set the `postgresql_keep_databases` variable to `true`.
+To keep PostgreSQL databases, set the `postgresql_keep_databases` variable to `true`.
 ----
 $ ansible-playbook -i inventory ansible.containerized_installer.uninstall -e postgresql_keep_databases=true
 ----
 
-[NOTE] 
-====
-Use the {PlatformNameShort} secret key values rather than the autogenerated ones.
-====
+

downstream/modules/platform/ref-controller-variables.adoc

@@ -152,8 +152,7 @@ Default = `5m`
 Default = `[TLSv1.2, TLSv1.3]`
 
 | | `controller_pg_socket` | PostgreSQL Controller UNIX socket.
-| | `controller_secret_key` | {ControllerNameStart} secret key.
-
+| | `controller_secret_key` | The secret key value used by {ControllerName} to sign and encrypt data, ensuring secure communication and data integrity between services.
 
 | | `controller_uwsgi_listen_queue_size` | {ControllerNameStart} uWSGI listen queue size.
 

downstream/modules/platform/ref-eda-controller-variables.adoc

@@ -183,7 +183,7 @@ Location of the {EDAcontroller} Redis TLS key.
 
 | | `eda_safe_plugins` | {EDAcontroller} safe plugins.
 
-| | `eda_secret_key` | {EDAcontroller} secret key.
+| | `eda_secret_key` | The secret key value used by {EDAcontroller} to sign and encrypt data, ensuring secure communication and data integrity between services.
 
 | | `eda_workers` | {EDAcontroller} workers count.
 

downstream/modules/platform/ref-gateway-variables.adoc

@@ -149,7 +149,7 @@ Location of the {Gateway} Redis TLS key.
 
 Default = `gateway`
 
-| | `gateway_secret_key` | {GatewayStart} secret key.
+| | `gateway_secret_key` | The secret key value used by {Gateway} to sign and encrypt data, ensuring secure communication and data integrity between services.
 
 | | `gateway_tls_remote` | {GatewayStart} TLS remote files.
 

downstream/modules/platform/ref-hub-variables.adoc

@@ -218,9 +218,9 @@ Default = `8444`
 
 Default = `[TLSv1.2, TLSv1.3]`
 
-|  | `hub_pg_socket` | PostgreSQL {HubNameStart} UNIX socket. 
+|  | `hub_pg_socket` | PostgreSQL {HubName} UNIX socket. 
 
-|  | `hub_secret_key` | {HubNameStart} secret key. 
+|  | `hub_secret_key` | The secret key value used by {HubName} to sign and encrypt data, ensuring secure communication and data integrity between services. 
 
 |  | `hub_storage_backend` | {HubNameStart} storage backend.