Skip to content

Commit e79aa2d

Browse files
ShaunaDiazShaunaDiaz
committed
OCPBUGS-44579: prevent unintended unsupported sys congif
1 parent bb7a2ee commit e79aa2d

8 files changed

+235
-12
lines changed

‎microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ You can embed {microshift-short} into a {op-system-ostree-first} image. Use this
1010

1111
include::modules/microshift-preparing-for-image-building.adoc[leveloffset=+1]
1212

13+
include::modules/microshift-embed-ostree-enable-eus-repos.adoc[leveloffset=+1]
14+
1315
include::modules/microshift-adding-repos-to-image-builder.adoc[leveloffset=+1]
1416

1517
[role="_additional-resources"]

‎microshift_troubleshooting/microshift-things-to-know.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
[id="microshift-things-to-know"]
33
= Responsive restarts and security certificates
44
include::_attributes/attributes-microshift.adoc[]
5-
:context: microshift-configuring
5+
:context: microshift-things-to-know
66

77
toc::[]
88

‎microshift_updating/microshift-update-options.adoc

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ You can update {op-system-ostree-first} images or {op-system-base-full} with or
1414

1515
include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1]
1616

17+
include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1]
18+
1719
[id="microshift-update-options-standalone-updates_{context}"]
1820
== Standalone {microshift-short} updates
1921
Consider the following when planning to update {microshift-short}:
@@ -61,10 +63,7 @@ You can update {microshift-short} manually on a non-OSTree system such as {op-sy
6163

6264
* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[About updating MicroShift RPMs manually]
6365

64-
[WARNING]
65-
====
66-
Keeping versions in a supported configuration of {op-system-bundle} can require updating {microshift-short} and {op-system-base} at the same time. Ensure that your version of {op-system-base} is compatible with the version of {microshift-short} you are updating to, especially if you are updating {microshift-short} across two minor versions. Otherwise, you can create an unsupported configuration, break your cluster, or both.
67-
====
66+
include::modules/microshift-updates-rhde-config-rhel-repos.adoc[leveloffset=+3]
6867

6968
[id="microshift-update-options-standalone-rhel-updates_{context}"]
7069
== Standalone {op-system-ostree} updates
@@ -87,7 +86,7 @@ You can update {op-system-ostree} or {op-system-base} and update {microshift-sho
8786
//additional resources for updating RHEL and MicroShift
8887
[role="_additional-resources"]
8988
.Additional resources
90-
* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Managing RHEL for Edge images]
89+
* link:https://access.redhat.com/articles/rhel-eus#c5[How to Access EUS]
9190
* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/index[Composing a customized RHEL system image]
9291
* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system]
9392
* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[Applying updates manually with RPMs]

‎modules/microshift-embed-ostree-enable-eus-repos.adoc

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_install_rpm_ostree/microshift-embed-into-rpm-ostree.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-enable-eus-repos_{context}"]
7+
= Enabling extended support repositories for image building
8+
9+
If you have an extended support (EUS) release of {microshift-short}, you must enable the {op-system-base-full} EUS repositories for image builder to use. If you do not have an EUS version, you can skip these steps.
10+
11+
.Prerequisites
12+
13+
* You have an EUS version of {microshift-short} or are updating to one.
14+
* You have root-user access to your build host.
15+
* You reviewed the link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[{op-system-bundle} release compatibility matrix].
16+
17+
include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1]
18+
19+
.Procedure
20+
21+
. Update the `baseos` source by modifying the `/etc/osbuild-composer/repositories/rhel-9.4.json` file with the following values:
22+
+
23+
[source,terminal]
24+
----
25+
# ...
26+
"baseurl": "https://cdn.redhat.com/content/eus/rhel<9>/<9.4>//baseos/os", # <1>
27+
# ...
28+
----
29+
<1> Replace _<9>_ with the major {op-system-base} version you are using, and replace _<9.4>_ with the _<major.minor>_ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using.
30+
31+
. Optional. Apply the `baseos` update by running the following command:
32+
+
33+
[source,terminal]
34+
----
35+
$ sudo sed -i "s,dist/rhel<9>/<9.4>/$(uname -m)/baseos/,eus/rhel<9>/<9.4>/$(uname -m)/baseos/,g" \
36+
/etc/osbuild-composer/repositories/rhel-<9.4>.json # <1>
37+
----
38+
<1> Replace _<9>_ with the major {op-system-base} version you are using, and replace _<9.4>_ with the _<major.minor>_ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using.
39+
40+
. Update the `appstream` source by modifying the `/etc/osbuild-composer/repositories/rhel-<major.minor>.json` file with the following values:
41+
+
42+
[source,terminal]
43+
----
44+
# ...
45+
"baseurl": "https://cdn.redhat.com/content/eus/rhel<9>/<9.4>//appstream/os", # <1>
46+
# ...
47+
----
48+
<1> Replace _<9>_ with the major {op-system-base} version you are using, and replace _<9.4>_ with the _<major.minor>_ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using.
49+
50+
. Optional. Apply the `appstream` update by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ sudo sed -i "s,dist/rhel<9>/<9.4>/$(uname -m)/appstream/,eus/rhel<9>/<9.4>/$(uname -m)/appstream/,g" \
55+
/etc/osbuild-composer/repositories/rhel-<9.4>.json # <1>
56+
----
57+
<1> Replace _<9>_ with the major {op-system-base} version you are using, and replace _<9.4>_ with the _<major.minor>_ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using.
58+
59+
.Verification
60+
61+
You can verify the repositories by using the `composer-cli` tool to display information about the source.
62+
63+
. Verify the `baseos` source by running the following command:
64+
+
65+
[source,terminal]
66+
----
67+
$ sudo composer-cli sources info baseos | grep 'url ='
68+
----
69+
.Example output
70+
+
71+
[source,text]
72+
----
73+
url = "https://cdn.redhat.com/content/eus/rhel9/9.4/x86_64/baseos/os"
74+
----
75+
76+
. Verify the `appstream` source by running the following command:
77+
+
78+
[source,terminal]
79+
----
80+
$ sudo composer-cli sources info appstream | grep 'url ='
81+
----
82+
.Example output
83+
+
84+
[source,text]
85+
----
86+
url = "https://cdn.redhat.com/content/eus/rhel9/9.4/x86_64/appstream/os"
87+
----

‎modules/microshift-install-rpms.adoc

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,35 @@ Use the following procedure to install {microshift-short} from an RPM package.
1515
1616
.Procedure
1717

18-
. As a root user, enable the {microshift-short} repositories by running the following command:
18+
. For all lifecycles, enable the repository for your release by running the following command:
1919
+
2020
[source,terminal,subs="attributes+"]
2121
----
2222
$ sudo subscription-manager repos \
23-
--enable rhocp-{ocp-version}-for-{rhel-major}-$(uname -m)-rpms \
24-
--enable fast-datapath-for-{rhel-major}-$(uname -m)-rpms
23+
--enable rhocp-<4.18>-for-<9>-$(uname -m)-rpms \ # <1>
24+
--enable fast-datapath-for-<9>-$(uname -m)-rpms # <2>
2525
----
26+
<1> Replace _<4.18>_ and _<9>_ with the compatible versions of your {microshift-short} and {op-system-base-full}.
27+
<2> Replace _<9>_ with the compatible version of {op-system-base}.
28+
29+
. For extended support (EUS) releases, also enable the EUS repositories by running the following command:
30+
+
31+
[source,terminal]
32+
----
33+
`$ sudo subscription-manager repos \
34+
--enable rhel-<9>-for-x86_64-appstream-eus-rpms \ # <1>
35+
--enable rhel-<9>-for-x86_64-baseos-eus-rpms` # <2>
36+
----
37+
<1> Replace _<9>_ with the compatible major version number of {op-system-base}.
38+
<2> Replace _<9>_ with the compatible major version number of {op-system-base}.
39+
40+
. Avoid unintended future updates into an unsupported configuration by locking your operating system version with the following command:
41+
+
42+
[source,terminal]
43+
----
44+
$ sudo subscription-manager release --set=<9.4> command. # <1>
45+
----
46+
<1> Replace _<9.4>_ with the major and minor version of your compatible {op-system-base} system.
2647

2748
. Install {microshift-short} by running the following command:
2849
+

‎modules/microshift-updates-rhde-config-rhel-repos.adoc

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
// Module included in the following assemblies:
2+
//
3+
//microshift_updating/microshift-update-options.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-updates-rhde-config-rhel-repos_{context}"]
7+
= Keeping {microshift-short} and {op-system-base} in a supported configuration
8+
9+
When using RPM updates, avoid creating an unsupported configuration or breaking your cluster by carefully managing your {op-system-base} repositories.
10+
11+
.Prerequisites
12+
13+
* You understand the support status of the version of {microshift-short} you are using.
14+
* You have root-user access to your build host.
15+
* You reviewed the link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[{op-system-bundle} release compatibility matrix].
16+
17+
.Procedure
18+
19+
. Avoid unintended updates by locking your operating system version by running the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ sudo subscription-manager release --set=<x.y> # <1>
24+
----
25+
<1> Replace _<x.y>_ with the major and minor version of your compatible {op-system-base} system. For example, _9.4_.
26+
27+
. Update both {microshift-short} and {op-system-base} versions by running the following command:
28+
+
29+
[source,terminal]
30+
----
31+
$ sudo subscription-manager release --set=<9.4> command. # <1>
32+
----
33+
<1> Replace _<9.4>_ with the major and minor version of your compatible {op-system-base} system.
34+
35+
. If you are using an EUS {microshift-short} release, disable the {op-system-base} standard-support-scope repositories by running the following command:
36+
+
37+
[source,terminal]
38+
----
39+
$ sudo subscription-manager repos \
40+
--disable=rhel-<9>-for-x86_64-appstream-rpms \ # <1>
41+
--disable=rhel-<9>-for-x86_64-baseos-rpms
42+
----
43+
<1> Replace _<9>_ with the major version of your compatible {op-system-base} system.
44+
45+
. After you disable the standard-support repositories, enable the {op-system-base} EUS repos by running the following command:
46+
+
47+
[source,terminal]
48+
----
49+
$ sudo subscription-manager repos \
50+
--enable rhel-<9>-for-x86_64-appstream-eus-rpms \ # <1>
51+
--enable rhel-<9>-for-x86_64-baseos-eus-rpms`
52+
----
53+
<1> Replace _<9>_ with the major version of your compatible {op-system-base} system.
54+
55+
.Verification
56+
57+
* List the repositories you have enabled for {op-system-base} by running the following command:
58+
+
59+
[source,terminal]
60+
----
61+
$ sudo subscription-manager repos --list-enabled
62+
----
63+
+
64+
.Example output
65+
+
66+
[source,terminal]
67+
----
68+
+----------------------------------------------------------+
69+
Available Repositories in /etc/yum.repos.d/redhat.repo
70+
+----------------------------------------------------------+
71+
Repo ID: rhel-9-for-x86_64-baseos-eus-rpms
72+
Repo Name: Red Hat Enterprise Linux 9 for x86_64 - BaseOS - Extended Update Support (RPMs)
73+
Repo URL: https://cdn.redhat.com/content/eus/rhel9/$releasever/x86_64/baseos/os
74+
Enabled: 1
75+
Repo ID: rhel-9-for-x86_64-appstream-eus-rpms
76+
Repo Name: Red Hat Enterprise Linux 9 for x86_64 - AppStream - Extended Update Support (RPMs)
77+
Repo URL: https://cdn.redhat.com/content/eus/rhel9/$releasever/x86_64/appstream/os
78+
Enabled: 1
79+
----

‎modules/microshift-updating-rpms-y.adoc

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
Updating a {microshift-short} minor version on non `rpm-ostree` systems such as {op-system-base-full} requires downloading then updating the RPMs. For example, use the following procedure to update from 4.16 to 4.18.
1010

11+
include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1]
12+
1113
.Prerequisites
1214
* The system requirements for installing {microshift-short} have been met.
1315
* You have root user access to the host.
@@ -22,14 +24,35 @@ You cannot downgrade {microshift-short} with this process. Downgrades are not su
2224

2325
.Procedure
2426

25-
. Enable the {microshift-short} repositories by running the following command:
27+
. For all lifecycles, enable the repository for your release by running the following command:
2628
+
2729
[source,terminal,subs="attributes+"]
2830
----
2931
$ sudo subscription-manager repos \
30-
--enable rhocp-{ocp-version}-for-{rhel-major}-$(uname -m)-rpms \
31-
--enable fast-datapath-for-{rhel-major}-$(uname -m)-rpms
32+
--enable rhocp-<4.18>-for-<9>-$(uname -m)-rpms \ # <1>
33+
--enable fast-datapath-for-<9>-$(uname -m)-rpms # <2>
34+
----
35+
<1> Replace _<4.18>_ and _<9>_ with the compatible versions of your {microshift-short} and {op-system-base-full}.
36+
<2> Replace _<9>_ with the compatible version of {op-system-base}.
37+
38+
. For extended support (EUS) releases, also enable the EUS repositories by running the following command:
39+
+
40+
[source,terminal]
41+
----
42+
`$ sudo subscription-manager repos \
43+
--enable rhel-<9>-for-x86_64-appstream-eus-rpms \ # <1>
44+
--enable rhel-<9>-for-x86_64-baseos-eus-rpms` # <2>
45+
----
46+
<1> Replace _<9>_ with the compatible major version number of {op-system-base}.
47+
<2> Replace _<9>_ with the compatible major version number of {op-system-base}.
48+
49+
. Avoid unintended future updates into an unsupported configuration by locking your operating system version with the following command:
50+
+
51+
[source,terminal]
52+
----
53+
$ sudo subscription-manager release --set=<9.4> command. # <1>
3254
----
55+
<1> Replace _<9.4>_ with the major and minor version of your compatible {op-system-base} system.
3356

3457
. Update the {microshift-short} RPMs by running the following command:
3558
+

‎snippets/microshift-unsupported-config-warn.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// Text snippet included in the following modules:
2+
//
3+
// * modules/microshift-updating-rpms-y.adoc
4+
// * modules/microshift-embed-ostree-enable-eus-repos.adoc
5+
// * assemblies/microshift-update-options.adoc
6+
7+
:_mod-docs-content-type: SNIPPET
8+
9+
[WARNING]
10+
====
11+
Keeping component versions in a supported configuration of {op-system-bundle} can require updating {microshift-short} and {op-system-base} at the same time. Ensure that your version of {op-system-base} is compatible with the version of {microshift-short} you are updating to, especially if you are updating {microshift-short} across two minor versions. Otherwise, you can create an unsupported configuration, break your cluster, or both. For more information, see the link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[Red Hat Device Edge release compatibility matrix].
12+
====

0 commit comments

Comments
 (0)