Update restore docs for foremanctl

guides/common/assembly_restoring-server-or-smart-proxy-from-a-backup.adoc → guides/common/assembly_restoring-project-from-backup.adoc

@@ -1,7 +1,9 @@
-include::modules/con_restoring-server-or-smart-proxy-from-a-backup.adoc[]
+include::modules/con_restoring-project-from-backup.adoc[]
 
 include::modules/proc_restoring-from-a-full-backup.adoc[leveloffset=+1]
 
+ifndef::containerized[]
 include::modules/proc_restoring-from-incremental-backups.adoc[leveloffset=+1]
 
 include::modules/proc_restoring-smartproxyserver-by-using-a-virtual-machine-snapshot.adoc[leveloffset=+1]
+endif::[]

guides/common/modules/con_restoring-server-or-smart-proxy-from-a-backup.adoc → guides/common/modules/con_restoring-project-from-backup.adoc

@@ -1,9 +1,14 @@
 :_mod-docs-content-type: CONCEPT
 
-[id="restoring-{project-context}-server-or-{smart-proxy-context}-from-a-backup_{context}"]
-= Restoring {ProjectServer} or {SmartProxyServer} from a backup
+[id="restoring-{project-context}-from-backup"]
+= Restoring {Project} from backup
 
 [role="_abstract"]
+ifdef::containerized[]
+You can restore your {ProjectServer} from a backup to recover after failure or data loss.
+endif::[]
+ifndef::containerized[]
 You can restore {ProjectServer} or {SmartProxyServer} from a backup to recover after failure or data loss.
+endif::[]
 This process outlines how to restore the backup on the same server that generated the backup, and all data covered by the backup is deleted on the target system.
 If the original system is unavailable, provision a system with the same configuration settings and host name.

guides/common/modules/proc_estimating-the-size-of-a-backup.adoc

@@ -1,19 +1,11 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="Estimating_the_Size_of_a_Backup_{context}"]
+[id="estimating-the-size-of-a-backup"]
 = Estimating the size of a backup
 
 [role="_abstract"]
 Estimate how much disk space a {Project} backup requires so you can ensure enough storage is available and avoid backup failures.
 
-A full backup requires space to store the following data:
-
-* Uncompressed {Project} database and configuration files
-* Compressed {Project} database and configuration files
-* An extra 20% of the total estimated space to ensure a reliable backup
-
-Compression occurs after the archives are created to decrease the time when {Project} services are unavailable.
-
 ifdef::satellite[]
 [NOTE]
 ====
@@ -22,14 +14,35 @@ Backups do not include container images for {insights-iop}.
 endif::[]
 
 .Procedure
-. Estimate the size of uncompressed directories containing {Project} database and configuration files:
+. Calculate the size of the uncompressed backup data:
+.. Determine the size of PostgreSQL database data:
 +
 [options="nowrap", subs="+quotes,attributes"]
 ----
-# du -sh {postgresql-data-dir} /var/lib/pulp
+# du -sh {postgresql-data-dir}
 100G    {postgresql-data-dir}
+----
+.. Determine the size of Pulp data:
++
+[options="nowrap", subs="+quotes,attributes"]
+----
+# du -sh /var/lib/pulp
 100G	/var/lib/pulp
-
+----
+ifdef::containerized[]
+.. Determine the size of the {foremanctl} configuration files:
++
+[options="nowrap", subs="+quotes,attributes"]
+----
+# du -sh /var/lib/foremanctl
+10MB	/var/lib/pulp
+----
+endif::[]
+ifndef::containerized[]
+.. Determine the size of the configuration files:
++
+[options="nowrap", subs="+quotes,attributes"]
+----
 # du -csh /var/lib/tftpboot /etc /root/ssl-build \
 /var/www/html/pub /opt/puppetlabs
 16M   /var/lib/tftpboot
@@ -39,10 +52,36 @@ endif::[]
 2M    /opt/puppetlabs
 942M  total
 ----
-. Calculate how much space is required to store the compressed data.
+endif::[]
+. Calculate the expected size of the compressed backup data:
 +
-The following table describes the compression ratio of all data items included in the backup:
+The compression ratio of the backup data is as follows:
 +
+ifdef::containerized[]
+.Backup data compression ratio
+|===
+|Data type |Directory |Compression ratio
+
+|PostgreSQL database files
+|`{postgresql-data-dir}`
+|80{range}85%
+
+|Pulp data
+|`/var/lib/pulp`
+|Not compressed
+
+|{foremanctl} configuration
+|`/var/lib/foremanctl`
+|85%
+|===
++
+In this example, the backup data is compressed as follows:
++
+* 100 GB of PostgreSQL database data is compressed to 15-20 GB
+* 100 GB of Pulp data is not compressed and occupies 100 GB of space
+* 10 MB of {foremanctl} configuration is compressed to 1.5 MB
+endif::[]
+ifndef::containerized[]
 .Backup data compression ratio
 [cols="4,6,3,5"]
 |===
@@ -73,7 +112,21 @@ a|`/var/lib/tftpboot`
 |===
 +
 In this example, the compressed backup data occupies 120 GB in total.
-. To calculate the amount of available space you require to store a backup, calculate the sum of the estimated values of compressed and uncompressed backup data, and add an extra 20% to ensure a reliable backup.
+endif::[]
+. Add up the size of the uncompressed and compressed data, and add a 20% safety margin.
+ifdef::containerized[]
+For example:
++
+--
+* 201 GB of uncompressed data + 120 GB of compressed data = 321 GB
+* 20% safety margin = 64 GB
+* Total space required: 321 GB + 64 GB = 385 GB
+--
++
+To ensure a successful backup or restore, 385 GB of space must be allocated for the backup location.
+endif::[]
+ifndef::containerized[]
 +
 This example requires 201 GB plus 120 GB for the uncompressed and compressed backup data, 321 GB in total.
-With 64 GB of extra space, 385 GB must be allocated for the backup location.
+With 64 GB of extra space, allocate 385 GB of space for the backup location.
+endif::[]

guides/common/modules/proc_performing-a-backup-without-pulp-content.adoc

@@ -19,7 +19,7 @@ endif::[]
 
 .Prerequisites
 * Your backup location must have sufficient available disk space to store the backup.
-For more information, see xref:Estimating_the_Size_of_a_Backup_{context}[].
+For more information, see xref:estimating-the-size-of-a-backup[].
 
 .Procedure
 * Back up your {ProjectServer} without Pulp content:

guides/common/modules/proc_performing-a-full-backup.adoc

@@ -15,7 +15,7 @@ A full backup is useful when you want to prepare for a future restore from scrat
 .Prerequisites
 * Your backup location must have sufficient available disk space to store the backup.
 ifdef::katello,orcharhino,satellite[]
-For more information, see xref:Estimating_the_Size_of_a_Backup_{context}[].
+For more information, see xref:estimating-the-size-of-a-backup[].
 endif::[]
 ifdef::containerized[]
 * To enable {Project} to save the backup to an NFS share, the `root` user of your {ProjectServer} must be able to write to the NFS share.

guides/common/modules/proc_performing-an-incremental-backup.adoc

@@ -13,7 +13,7 @@ Keep the most recent full backup and a complete sequence of incremental backups
 .Prerequisites
 * Your backup location must have sufficient available disk space to store the backup.
 ifdef::katello,orcharhino,satellite[]
-For more information, see xref:Estimating_the_Size_of_a_Backup_{context}[].
+For more information, see xref:estimating-the-size-of-a-backup[].
 endif::[]
 
 .Procedure

guides/common/modules/proc_performing-an-online-backup.adoc

@@ -18,7 +18,7 @@ endif::[]
 .Prerequisites
 * Your backup location must have sufficient available disk space to store the backup.
 ifdef::katello,orcharhino,satellite[]
-For more information, see xref:Estimating_the_Size_of_a_Backup_{context}[].
+For more information, see xref:estimating-the-size-of-a-backup[].
 endif::[]
 
 .Procedure

guides/common/modules/proc_preparing-for-disaster-recovery-with-active-and-passive-project-server-and-backup-and-restore.adoc

@@ -15,7 +15,7 @@ Configure periodic backups of the active server.
 . Define a schedule for periodic offline backups of your active {ProjectServer}.
 Consider your tolerance for potential data loss and your storage options: Taking backups frequently will result in smaller amounts of data loss in case of a disaster, but backups require a significant amount of storage space.
 ifdef::katello,satellite[]
-For information about the size of {Project} backups, see xref:Estimating_the_Size_of_a_Backup_admin[].
+For information about the size of {Project} backups, see xref:estimating-the-size-of-a-backup[].
 endif::[]
 +
 You can combine full backups with incremental backups.
@@ -34,7 +34,7 @@ endif::[]
 Encrypting or moving the backups to a secure location helps minimize the risk of damage or unauthorized access to the hosts.
 ====
 . Restore the most recent backup on a system that will serve as your passive {ProjectServer}.
-For information about restoring backups, see xref:restoring-{project-context}-server-or-{smart-proxy-context}-from-a-backup_admin[].
+For information about restoring backups, see xref:restoring-{project-context}-from-backup[].
 . Optional: Automate backup restoration to keep the passive server periodically updated with the latest backup.
 A regularly restored passive server helps reduce switchover time if the active server fails.
 +

guides/common/modules/proc_preparing-for-disaster-recovery-with-active-and-passive-project-server-with-external-storage.adoc

@@ -27,7 +27,7 @@ For more information, see xref:cloning-{project-context}-server[].
 endif::[]
 ifndef::satellite[]
 . Back up your active {ProjectServer} and restore it on a system that will serve as your passive {ProjectServer}.
-For more information, see xref:backing-up-{project-context}[] and xref:restoring-{project-context}-server-or-{smart-proxy-context}-from-a-backup_admin[].
+For more information, see xref:backing-up-{project-context}[] and xref:restoring-{project-context}-from-backup[].
 endif::[]
 . Keep the source server powered on.
 Power off the new server.

guides/common/modules/proc_preparing-for-disaster-recovery-with-two-active-project-servers.adoc

@@ -21,7 +21,7 @@ For more information, see {AnsibleDocURL}[_{AnsibleDocTitle}_].
 . Back up your {ProjectServer}.
 For more information, see xref:backing-up-{project-context}[].
 . Restore the backup on a system that will serve as your other {ProjectServer}.
-For more information, see xref:restoring-{project-context}-server-or-{smart-proxy-context}-from-a-backup_admin[].
+For more information, see xref:restoring-{project-context}-from-backup[].
 +
 [NOTE]
 ====

guides/common/modules/proc_restoring-from-a-full-backup.adoc

@@ -4,18 +4,39 @@
 = Restoring from a full backup
 
 [role="_abstract"]
-Restore {ProjectServer} or {SmartProxyServer} from a full backup return the system to the state at the time of the backup.
+ifdef::containerized[]
+Restore your {ProjectServer} from a full backup to return the system to the state at the time of the backup.
+endif::[]
+ifndef::containerized[]
+Restore {ProjectServer} or {SmartProxyServer} from a full backup to return the system to the state at the time of the backup.
+endif::[]
 When the restore process completes, all processes are online, and all databases and system configuration revert to the state at the time of the backup.
 
+ifdef::containerized[]
+The restore process can take a long time to complete.
+The restoration script deployed by the `{foremanctl} restore` command includes the following actions:
+
+* Validation checks to verify the backup integrity, disk space, and system requirements
+* Restoring databases, Pulp content, encryption keys, OAuth secrets, and passwords
+* Configuring and starting of services by using `{foremanctl} deploy`
+* Confirming that services are running as expected
+endif::[]
+
 .Prerequisites
 * Your {ProjectServer} must have the same host name, configuration, and be the same minor version (X.Y) as the original system.
 * The target directory must exist and be writable.
 The target directory is read from the configuration files contained within the backup archive.
 ifndef::foreman-deb[]
 * If the backed up system had FIPS enabled, the system on which you are restoring must also have FIPS enabled.
 endif::[]
+ifdef::containerized[]
+* Your system must have enough space to extract the backup data.
+Your system must also have enough space left for the backup data after the restoration.
+For more information, see xref:estimating-the-size-of-a-backup[].
+endif::[]
 
 .Procedure
+ifndef::containerized[]
 . Ensure that you have enough space to store the backup data on the base system of {ProjectServer} or {SmartProxyServer} as well as enough space after the restoration to contain all the data in the `/etc/` and `/var/` directories contained within the backup.
 +
 To check the space used by a directory:
@@ -33,6 +54,7 @@
 ----
 +
 Add the ``--total`` option to get a total of the results from more than one directory.
+endif::[]
 ifndef::foreman-deb[]
 . Restore the correct SELinux contexts:
 +
@@ -41,6 +63,11 @@
 # restorecon -Rv /
 ----
 endif::[]
+ifdef::containerized[]
+. Install {ProjectServer} on the system where you want to restore the backup.
+For more information, see {InstallingServerDocURL}[{InstallingServerDocTitle}].
+endif::[]
+ifndef::containerized[]
 . Choose the appropriate method to install {Project} or {SmartProxy}:
 ** To install {ProjectServer} from a connected network, follow the procedures in {InstallingServerDocURL}[{InstallingServerDocTitle}].
 ifdef::satellite[]
@@ -53,21 +80,41 @@
 For more information, see {InstallingServerDisconnectedDocURL}installing-and-configuring-{insights-iop-id}[Installing and configuring {insights-iop}].
 endif::[]
 ** To install a {SmartProxyServer}, follow the procedures in {InstallingSmartProxyDocURL}[{InstallingSmartProxyDocTitle}].
+endif::[]
 . Copy the backup data to the local file system on {ProjectServer}.
 Use `/var/` or `/var/tmp/`.
-. Run the restoration script.
+ifdef::containerized[]
+. Optional: Validate the backup to ensure that all files required for the restore process exist and the backup metadata is valid:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
-# {foreman-maintain} restore __/var/backup_directory__
+# {foremanctl} restore _/var/backup_directory_ --validate
 ----
+endif::[]
+. Run the restoration script:
 +
-Where _backup_directory_ is the time-stamped directory or subdirectory containing the backed-up data.
+ifdef::containerized[]
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {foremanctl} restore _/var/backup_directory_ --force
+----
 +
-The restore process can take a long time to complete, because of the amount of data to copy.
+The `--force` option is required to confirm that the data from the fresh {Project} deployment installed on the system will be permanently deleted and replaced by the data from the backup.
+endif::[]
+ifndef::containerized[]
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {foreman-maintain} restore __/var/backup_directory__
+----
+endif::[]
 
 .Next steps
+ifdef::containerized[]
+* If you create a new instance of your {ProjectServer}, decommission the old instance after restoring the backup.
+endif::[]
+ifndef::containerized[]
 * If you create a new instance of {ProjectServer} or {SmartProxyServer}, decommission the old instance after restoring the backup.
+endif::[]
 Cloned instances are not supposed to run in parallel in a production environment.
 
 .Troubleshooting

guides/doc-Administering_Project/master.adoc

@@ -70,9 +70,9 @@ endif::[]
 
 include::common/assembly_backing-up-project.adoc[leveloffset=+1]
 
-ifndef::containerized[]
-include::common/assembly_restoring-server-or-smart-proxy-from-a-backup.adoc[leveloffset=+1]
+include::common/assembly_restoring-project-from-backup.adoc[leveloffset=+1]
 
+ifndef::containerized[]
 ifdef::katello,orcharhino,satellite[]
 include::common/assembly_renaming-server-or-smart-proxy.adoc[leveloffset=+1]
 endif::[]