Skip to content

Commit 3c3af92

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-7495: add backup and restore
1 parent a0787c8 commit 3c3af92

File tree

10 files changed

+217
-1
lines changed

10 files changed

+217
-1
lines changed

‎_topic_maps/_topic_map_ms.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,11 +154,20 @@ Topics:
154154
- Name: Greenboot workload health check scripts
155155
File: microshift-greenboot-workload-scripts
156156
---
157+
Name: Backup and restore
158+
Dir: microshift_backup_and_restore
159+
Distros: microshift
160+
Topics:
161+
- Name: Backing up and restoring data
162+
File: microshift-backup-and-restore
163+
---
157164
Name: Troubleshooting
158165
Dir: microshift_troubleshooting
159166
Distros: microshift
160167
Topics:
161168
- Name: Checking your version
162169
File: microshift-version
170+
- Name: Troubleshooting backup and restore
171+
File: microshift-troubleshoot-backup-restore
163172
- Name: Additional information
164173
File: microshift-things-to-know

‎microshift_backup_and_restore/_attributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../_attributes

‎microshift_backup_and_restore/images‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images

‎microshift_backup_and_restore/microshift-backup-and-restore.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
:_content-type: ASSEMBLY
2+
[id="microshift-backup-and-restore"]
3+
= Backing up and restoring {product-title} data
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-backup-and-restore
6+
7+
toc::[]
8+
9+
You can manually back up and restore the {product-title} database on all supported systems. The {product-title} service must be stopped and Greenboot health checks must be completed prior to any backups.
10+
11+
* On `rpm-ostree` systems, {product-title} automatically creates a backup on every start. These automatic backups are deleted and replaced with the latest backup each time the system restarts.
12+
* If you are using an `rpm-ostree` system, restoring data is also automated. Otherwise, you must back up and restore data manually.
13+
14+
include::modules/microshift-service-stopping.adoc[leveloffset=+1]
15+
16+
include::modules/microshift-backing-up-manually.adoc[leveloffset=+1]
17+
18+
//additional resources for backing-up module
19+
[role="_additional-resources"]
20+
.Additional resources
21+
* xref:../microshift_install/microshift-install-rpm.adoc#microshift-service-stopping_microshift-install-rpm[Stopping the MicroShift service]
22+
* xref:../microshift_install/microshift-install-rpm.adoc#microshift-service-starting_microshift-install-rpm[Starting the MicroShift service]
23+
24+
include::modules/microshift-restoring-data-backups.adoc[leveloffset=+1]
25+
26+
//additional resources for restoring-data module
27+
[role="_additional-resources"]
28+
.Additional resources
29+
* xref:../microshift_install/microshift-install-rpm.adoc#microshift-service-stopping_microshift-install-rpm[Stopping the MicroShift service]
30+
* xref:../microshift_install/microshift-install-rpm.adoc#microshift-service-starting_microshift-install-rpm[Starting the MicroShift service]

‎microshift_backup_and_restore/modules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules

‎microshift_backup_and_restore/snippets‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../snippets/

‎microshift_troubleshooting/microshift-troubleshoot-backup-restore.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
:_content-type: ASSEMBLY
2+
[id="microshift-troubleshoot-backup-restore.adoc"]
3+
= Troubleshooting data backup and restore
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-troubleshoot-data-backup-and-restore
6+
7+
toc::[]
8+
9+
To troubleshoot failed data backups and restorations, check the basics first, such as data paths, storage configuration, and storage capacity.
10+
11+
[id="troubleshoot-backup-restore-microshift-backup-data-failed"]
12+
== Backing up data failed
13+
Data backups are automatic on `rpm-ostree` systems. If you are not using an `rpm-ostree` system and attempted to create a manual backup, the following reasons can cause the backup to fail:
14+
15+
* Not waiting several minutes after a system start to successfully stop {product-title}. The system must complete health checks and any other background processes before a back up can succeed.
16+
* If {product-title} stopped running because of an error, you cannot perform a backup of the data.
17+
** Make sure the system is healthy.
18+
** Stop it in a healthy state before attempting a backup.
19+
* If you do not have sufficient storage for the data, the backup fails. Ensure that you have enough storage for the {product-title} data.
20+
* If you do not have sufficient permissions, a backup can fail. Ensure you have the correct user permissions to create a backup and perform the required configurations.
21+
22+
[id="troubleshoot-backup-restore-microshift-backup-logs"]
23+
== Backup logs
24+
* Logs print to the console during manual backups.
25+
* Logs are automatically generated for `rpm-ostree` system automated backups as part of the {product-title} journal logs. You can check the logs by running the following command:
26+
+
27+
[source, terminal]
28+
----
29+
$ sudo journalctl -u microshift
30+
----
31+
32+
[id="troubleshoot-backup-restore-microshift-restore-data-failed"]
33+
== Restoring data failed
34+
The restoration of data can fail for many reasons, including storage and permission issues. Mismatched data versions can cause failures when {product-title} restarts.
35+
36+
[id="troubleshoot-backup-restore-microshift-RPM-OSTree-data-restore-failed"]
37+
=== RPM-OSTree-based systems data restore failed
38+
Data restorations are automatic on `rpm-ostree` systems, but can fail, for example:
39+
40+
* The only backups that are restored on `rpm-ostree` systems are backups from the current deployment or a rollback deployment. Backups are not taken on an unhealthy system.
41+
42+
** Only the latest backups that have corresponding deployments are retained. Outdated backups that do not have a matching deployment are automatically removed.
43+
44+
** Data is usually not restored from a newer version of {product-title}.
45+
46+
** Ensure that the data you are restoring follows same versioning pattern as the update path. For example, if the destination version of {product-title} is an older version than the version of the {product-title} data you are currently using, the restoration can fail.
47+
48+
[id="troubleshoot-backup-restore-microshift-rpm-manual-restore-data-failed"]
49+
=== RPM-based manual data restore failed
50+
If you are using an RPM system that is not `rpm-ostree` and tried to restore a manual backup, the following reasons can cause the restoration to fail:
51+
52+
* If {product-title} stopped running because of an error, you cannot restore data.
53+
** Make sure the system is healthy.
54+
** Start it in a healthy state before attempting to restore data.
55+
56+
* If you do not have enough storage space allocated for the incoming data, the restoration fails.
57+
** Make sure that your current system storage is configured to accept the restored data.
58+
59+
* You are attempting to restore data from a newer version of {product-title}.
60+
** Ensure that the data you are restoring follows same versioning pattern as the update path. For example, if the destination version of {product-title} is an older version than the version of the {product-title} data you are attempting to use, the restoration can fail.
61+
62+
[id="troubleshoot-backup-restore-microshift-storage-migration-failed"]
63+
== Storage migration failed
64+
Storage migration failures are typically caused by substantial changes in custom resources (CRs) from one {product-title} to the next. If a storage migration fails, there is usually an unresolvable discrepancy between versions that requires manual review.
65+

‎modules/images‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
../images/
1+
../images

‎modules/microshift-backing-up-manually.adoc‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
//Module included in the following assemblies:
2+
//
3+
// * microshift_updating/microshift-update-options.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-backing-up-manually_{context}"]
7+
= Backing up {product-title} data manually
8+
9+
You can back up {product-title} data manually at any time. Data backups are advised before any system updates. Backups are created in the `/var/lib/microshift-backups` directory by default. You can also specify a directory by adding custom parameters to the required backup command.
10+
11+
[NOTE]
12+
====
13+
On `rpm-ostree` systems, {product-title} creates an automatic backup on every start and restores data automatically.
14+
====
15+
16+
.Prerequisites
17+
* You have root access to the host.
18+
* {product-title} is stopped.
19+
20+
.Procedure
21+
. Manually create a backup by using the default name and parent directory, `/var/lib/microshift-backups/<default-backup-name>`, by running the following command:
22+
+
23+
[source, terminal]
24+
----
25+
$ sudo microshift backup
26+
----
27+
.Example output
28+
+
29+
[source, terminal]
30+
----
31+
??? I0829 07:32:12.313961 6586 run_check.go:28] "Service state" service="microshift.service" state="inactive"
32+
??? I0829 07:32:12.318803 6586 run_check.go:28] "Service state" service="microshift-etcd.scope" state="inactive"
33+
??? I0829 07:32:12.318897 6586 version.go:227] "START reading version file"
34+
??? I0829 07:32:12.319122 6586 version.go:233] "END reading version file" contents={"version":"4.14.0","deployment_id":"rhel-35d7b5c80f0f1378d6846f6dc1304bbf1dcdc5847198fcd4e6099364eaf99048.0","boot_id":"80364fcf3df54284a6902687e2cdd4c2"}
35+
??? I0829 07:32:12.319256 6586 data_manager.go:82] "Copying data to backup directory" storage="/var/lib/microshift-backups" name="4.14.0__20230829_113212" data="/var/lib/microshift"
36+
??? I0829 07:32:12.319423 6586 data_manager.go:186] "Starting copy" cmd="/bin/cp --verbose --recursive --preserve --reflink=auto /var/lib/microshift /var/lib/microshift-backups/4.14.0__20230829_113212"
37+
??? I0829 07:32:12.324955 6586 data_manager.go:200] "Finished copy" cmd="/bin/cp --verbose --recursive --preserve --reflink=auto /var/lib/microshift /var/lib/microshift-backups/4.14.0__20230829_113212"
38+
??? I0829 07:32:12.325014 6586 data_manager.go:115] "Copied data to backup directory" backup="/var/lib/microshift-backups/4.14.0__20230829_113212" data="/var/lib/microshift"
39+
----
40+
41+
. Optional: Manually create a backup with a specific name in the default directory by running the following command:
42+
+
43+
[source, terminal]
44+
----
45+
$ sudo microshift backup --name <my-custom-backup>
46+
----
47+
48+
. Optional: Manually create a backup in a specific parent directory by running the following command:
49+
+
50+
[source, terminal]
51+
----
52+
$ sudo microshift backup --storage /var/lib/<custom-storage-location>
53+
----
54+
55+
. Optional: Manually create a backup in a specific parent directory with a custom name by running the following command:
56+
+
57+
[source, terminal]
58+
----
59+
$ sudo microshift backup --storage /var/lib/<custom-storage-location>/ --name <my-custom-backup>
60+
----
61+
62+
.Verification
63+
* You can verify that the backup exists by viewing the data in the directory you chose. For example, `/var/lib/microshift-backups/<my-custom-backup>/` or `/var/lib/<custom-storage-location>/<my-custom-backup>/`.

‎modules/microshift-restoring-data-backups.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
//Module included in the following assemblies:
2+
//
3+
// * microshift_updating/microshift-update-options.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-restoring-data-backups-manually_{context}"]
7+
= Restoring application data backups manually
8+
9+
You can restore application data from a backup manually. Backups can be restored after updates, or after other system events that remove or damage required data. Backups are in the `/var/lib/microshift-backups` directory by default. When you restore a backup, you must use the entire file path.
10+
11+
[NOTE]
12+
====
13+
On an `rpm-ostree` system, {product-title} backs up and restores data automatically.
14+
====
15+
16+
.Prerequisites
17+
* Root access to the host.
18+
* Full path of the data backup file.
19+
* {product-title} is stopped.
20+
21+
.Procedure
22+
23+
. Manually restore an application backup file by using the full file path of the backup you want to restore by running the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ sudo microshift restore /var/lib/<custom_backups>/<my_backup>
28+
----
29+
+
30+
.Example output
31+
+
32+
[source,terminal]
33+
----
34+
??? I0829 07:33:04.715104 6654 run_check.go:28] "Service state" service="microshift.service" state="inactive"
35+
??? I0829 07:33:04.719562 6654 run_check.go:28] "Service state" service="microshift-etcd.scope" state="inactive"
36+
??? I0829 07:33:04.719681 6654 data_manager.go:121] "Copying backup to data directory" storage="/var/lib/microshift-backups" name="4.14.0__20230829_113212" data="/var/lib/microshift"
37+
??? I0829 07:33:04.719802 6654 data_manager.go:138] "Renaming existing data dir" data="/var/lib/microshift" renamedTo="/var/lib/microshift.saved"
38+
??? I0829 07:33:04.719913 6654 data_manager.go:186] "Starting copy" cmd="/bin/cp --verbose --recursive --preserve --reflink=auto /var/lib/microshift-backups/4.14.0__20230829_113212 /var/lib/microshift"
39+
??? I0829 07:33:04.725032 6654 data_manager.go:200] "Finished copy" cmd="/bin/cp --verbose --recursive --preserve --reflink=auto /var/lib/microshift-backups/4.14.0__20230829_113212 /var/lib/microshift"
40+
??? I0829 07:33:04.725091 6654 data_manager.go:160] "Removing temporary data directory" path="/var/lib/microshift.saved"
41+
??? I0829 07:33:04.727461 6654 data_manager.go:165] "Copied backup to data directory" name="4.14.0__20230829_113212" data="/var/lib/microshift"
42+
----
43+
+
44+
.Verification
45+
* Verify that your backup is restored by restarting {product-title} and checking the data.

0 commit comments

Comments
 (0)