Skip to content

Commit 8374096

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #101688 from ShaunaDiaz/OSDOCS-15647
OSDOCS-15647: modularizes backup and restore MicroShift
2 parents 455328f + ce8a134 commit 8374096

9 files changed

+116
-67
lines changed

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

Lines changed: 7 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,19 @@
11
:_mod-docs-content-type: ASSEMBLY
22
[id="microshift-troubleshoot-backup-restore"]
33
= Troubleshooting data backup and restore
4+
45
include::_attributes/attributes-microshift.adoc[]
56
:context: microshift-troubleshoot-backup-and-restore
67

78
toc::[]
89

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_{context}"]
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 {microshift-short}. The system must complete health checks and any other background processes before a back up can succeed.
16-
* If {microshift-short} 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 {microshift-short} 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_{context}"]
23-
== Backup logs
24-
* Logs print to the terminal console during manual backups.
25-
* Logs are automatically generated for `rpm-ostree` system automated backups as part of the {microshift-short} 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_{context}"]
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 {microshift-short} restarts.
35-
36-
[id="troubleshoot-backup-restore-microshift-RPM-OSTree-data-restore-failed_{context}"]
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 {microshift-short}.
45-
46-
** Ensure that the data you are restoring follows same versioning pattern as the update path. For example, if the destination version of {microshift-short} is an older version than the version of the {microshift-short} data you are currently using, the restoration can fail.
47-
48-
[id="troubleshoot-backup-restore-microshift-rpm-manual-restore-data-failed_{context}"]
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 {microshift-short} 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.
10+
[role="_abstract"]
11+
To troubleshoot failed data backups and restorations, check the basics first. For example, user permissions, system health and configuration, and storage capacity.
5512

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.
13+
include::modules/microshift-backup-data-failed.adoc[leveloffset=+1]
5814

59-
* You are attempting to restore data from a newer version of {microshift-short}.
60-
** Ensure that the data you are restoring follows same versioning pattern as the update path. For example, if the destination version of {microshift-short} is an older version than the version of the {microshift-short} data you are attempting to use, the restoration can fail.
15+
include::modules/microshift-backup-logs.adoc[leveloffset=+1]
6116

62-
[id="troubleshoot-backup-restore-microshift-storage-migration-failed_{context}"]
63-
== Storage migration failed
64-
Storage migration failures are typically caused by substantial changes in custom resources (CRs) from one {microshift-short} to the next. If a storage migration fails, there is usually an unresolvable discrepancy between versions that requires manual review.
17+
include::modules/microshift-restore-data-failed.adoc[leveloffset=+1]
6518

19+
include::modules/microshift-storage-migration-failed.adoc[leveloffset=+1]

‎microshift_troubleshooting/microshift-version.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,11 @@ include::_attributes/attributes-microshift.adoc[]
66

77
toc::[]
88

9-
To begin troubleshooting, determine which version of {product-title} you have installed.
9+
[role="_abstract"]
10+
To begin troubleshooting, you must know which version of {product-title} you have installed.
1011

1112
include::modules/microshift-version-cli.adoc[leveloffset=+1]
1213

1314
include::modules/microshift-version-api.adoc[leveloffset=+1]
1415

15-
include::modules/microshift-etcd-version.adoc[leveloffset=+1]
16+
include::modules/microshift-etcd-version.adoc[leveloffset=+1]

‎modules/microshift-backup-data-failed.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// * microshift_troubleshooting/microshift-troubleshoot-backup-restore.adoc
5+
6+
:_mod-docs-content-type: CONCEPT
7+
[id="microshift-backup-data-failed_{context}"]
8+
= Data backup failure
9+
10+
[role="_abstract"]
11+
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:
12+
13+
* Not waiting several minutes after a system start to successfully stop {microshift-short}. The system must complete health checks and any other background processes before a back up can succeed.
14+
* If {microshift-short} stopped running because of an error, you cannot perform a backup of the data.
15+
** Make sure the system is healthy.
16+
** Stop it in a healthy state before attempting a backup.
17+
* If you do not have enough storage for the data, the backup fails. Ensure that you have enough storage for {microshift-short} data.
18+
* If you do not have the required user permissions, a backup can fail. Ensure that you have the correct user permissions to create a backup and perform the required configurations.

‎modules/microshift-backup-logs.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_troubleshooting/microshift-troubleshoot-backup-restore.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-checking-backup-logs_{context}"]
7+
= Checking backup logs
8+
9+
[role="_abstract"]
10+
Backup logs can help you identify where backups are and what processes occurred during manual and automatic backups.
11+
12+
* Logs print to the terminal console during manual backups.
13+
* Logs are automatically generated for `rpm-ostree` system automated backups as part of the {microshift-short} journal logs.
14+
15+
.Procedure
16+
17+
* Check the logs by running the following command:
18+
+
19+
[source,terminal]
20+
----
21+
$ sudo journalctl -u microshift
22+
----

‎modules/microshift-etcd-version.adoc‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
[id="microshift-version-etcd_{context}"]
88
= Checking the etcd version
99

10+
[role="_abstract"]
1011
You can get the version information for the etcd database included with your {microshift-short} by using one or both of the following methods, depending on the level of information that you need.
1112

1213
.Procedure
@@ -21,7 +22,7 @@ $ microshift-etcd version
2122
.Example output
2223
[source,terminal,subs="attributes+"]
2324
----
24-
microshift-etcd Version: 4.17.1
25+
microshift-etcd Version: 4.20.0
2526
Base etcd Version: 3.5.13
2627
----
2728
@@ -33,15 +34,15 @@ $ microshift-etcd version -o json
3334
----
3435
+
3536
.Example output
36-
[source,terminal,subs="attributes+"]
37+
[source,terminal]
3738
----
3839
{
3940
"major": "4",
40-
"minor": "16",
41-
"gitVersion": "4.17.1~rc.1",
41+
"minor": "20",
42+
"gitVersion": "4.20.0",
4243
"gitCommit": "140777711962eb4e0b765c39dfd325fb0abb3622",
4344
"gitTreeState": "clean",
44-
"buildDate": "2024-05-10T16:37:53Z",
45+
"buildDate": "2025-11-03T16:37:53Z",
4546
"goVersion": "go1.21.9"
4647
"compiler": "gc",
4748
"platform": "linux/amd64",

‎modules/microshift-restore-data-failed.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// * microshift_troubleshooting/microshift-troubleshoot-backup-restore.adoc
5+
6+
:_mod-docs-content-type: CONCEPT
7+
[id="microshift-restore-data-failed_{context}"]
8+
= Data restoration failure
9+
10+
[role="_abstract"]
11+
The restoration of data can fail for many reasons, including storage and permission issues. Mismatched data versions can cause failures when {microshift-short} restarts.
12+
13+
[id="microshift-image-based-systems-data-restore-failed_{context}"]
14+
== Image-based systems data restore failed
15+
16+
Data restorations are automatic on `rpm-ostree` systems, but can fail, for example:
17+
18+
* 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.
19+
20+
** Only the latest backups that have corresponding deployments are retained. Outdated backups that do not have a matching deployment are automatically removed.
21+
22+
** Data is usually not restored from a newer version of {microshift-short}.
23+
24+
** Ensure that the data you are restoring follows same versioning pattern as the update path. For example, if the destination version of {microshift-short} is an older version than the version of the {microshift-short} data you are currently using, the restoration can fail.
25+
26+
[id="microshift-rpm-manual-restore-data-failed_{context}"]
27+
== RPM-based manual data restore failed
28+
29+
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:
30+
31+
* If {microshift-short} stopped running because of an error, you cannot restore data.
32+
** Make sure the system is healthy.
33+
** Start it in a healthy state before attempting to restore data.
34+
35+
* If you do not have enough storage space allocated for the incoming data, the restoration fails.
36+
** Make sure that your current system storage is configured to accept the restored data.
37+
38+
* You are attempting to restore data from a newer version of {microshift-short}.
39+
** Ensure that the data you are restoring follows same versioning pattern as the update path. For example, if the destination version of {microshift-short} is an older version than the version of the {microshift-short} data you are attempting to use, the restoration can fail.

‎modules/microshift-storage-migration-failed.adoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// * microshift_troubleshooting/microshift-troubleshoot-backup-restore.adoc
5+
6+
:_mod-docs-content-type: CONCEPT
7+
[id="microshift-storage-migration-failed_{context}"]
8+
= Storage migration failure
9+
10+
[role="_abstract"]
11+
Storage migration failures are typically caused by significant changes in custom resources (CRs) from one {microshift-short} version to the next.
12+
13+
* If a storage migration fails, there is usually an unresolvable discrepancy between versions that requires manual review.

‎modules/microshift-version-api.adoc‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,12 @@
66
[id="microshift-version-api_{context}"]
77
= Checking the {microshift-short} version using the API
88

9+
[role="_abstract"]
910
To begin troubleshooting, you must know your {microshift-short} version. One way to get this information is by using the API.
1011

1112
.Procedure
1213

13-
* To get the version number using the OpenShift CLI (`oc`), view the `kube-public/microshift-version` config map by running the following command:
14+
* To get the version number using the {oc-first}, view the `kube-public/microshift-version` config map by running the following command:
1415
+
1516
[source,terminal]
1617
----
@@ -23,12 +24,11 @@ $ oc get configmap -n kube-public microshift-version -o yaml
2324
apiVersion: v1
2425
data:
2526
major: "4"
26-
minor: "13"
27-
version: 4.13.8-0.microshift-fa441af87431
27+
minor: "20"
28+
version: 4.20.0-0.microshift-fa441af87431
2829
kind: ConfigMap
2930
metadata:
30-
creationTimestamp: "2023-08-03T21:06:11Z"
31+
creationTimestamp: "2025-11-03T21:06:11Z"
3132
name: microshift-version
3233
namespace: kube-public
3334
----
34-
//update output to 4.14

‎modules/microshift-version-cli.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
[id="microshift-version-cli_{context}"]
77
= Checking the version using the command-line interface
88

9-
To begin troubleshooting, you must know your {microshift-short} version. One way to get this information is by using the CLI.
9+
[role="_abstract"]
10+
To begin troubleshooting, you must know your {microshift-short} version. One way to get this information is by using the command-line interface (CLI).
1011

1112
.Procedure
1213

@@ -20,6 +21,6 @@ $ microshift version
2021
.Example output
2122
[source,terminal,subs="attributes+"]
2223
----
23-
{product-title} Version: {product-version}-0.microshift-e6980e25
24+
{microshift-short} Version: {product-version}-0.microshift-e6980e25
2425
Base OCP Version: {product-version}
2526
----

0 commit comments

Comments
 (0)