Skip to content

Commit 88bb487

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-8216: embed microshift in rpm-ostree commit
1 parent 5337ff9 commit 88bb487

7 files changed

+203
-4
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,8 @@ Name: Running applications
422422
Dir: microshift_running_apps
423423
Distros: microshift
424424
Topics:
425+
- Name: Embedding MicroShift containers for offline deployments
426+
File: microshift-embed-microshift-offline-deploy
425427
- Name: Embedding applications on RHEL for Edge
426428
File: microshift-embedded-apps-on-rhel-edge
427429
- Name: Embedding applications for offline use

‎microshift_running_apps/microshift-embed-apps-offline-use.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
66

77
toc::[]
88

9-
You can embed microservices-based workloads and applications in a {op-system-ostree-first} image. This allows users to run a {microshift-short} cluster in air-gapped, disconnected, or offline environment.
9+
You can embed microservices-based workloads and applications in a {op-system-ostree-first} image. Embedding means you can run a {product-title} cluster in air-gapped, disconnected, or offline environments.
1010

1111
include::modules/microshift-embed-images-offline-use.adoc[leveloffset=+1]
1212

‎microshift_running_apps/microshift-embed-microshift-offline-deploy.adoc

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
:_content-type: ASSEMBLY
2+
[id="microshift-embed-microshift-offline-deployments"]
3+
= Running a cluster in an offline deployment
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-embed-apps-offline-use
6+
7+
toc::[]
8+
9+
Embedding {microshift-short} containers in an `rpm-ostree` commit means that you can run a cluster in air-gapped, disconnected, or offline environments. You can embed {product-title} containers in a {op-system-ostree-first} image so that container engines do not need to pull images over a network from a container registry. Workloads can start up immediately without network connectivity.
10+
11+
include::modules/microshift-embed-microshift-image-offline-deploy.adoc[leveloffset=+1]
12+
13+
include::modules/microshift-embed-microshift-update-osbuilder-worker.adoc[leveloffset=+1]
14+
15+
include::modules/microshift-embed-microshift-build-image.adoc[leveloffset=+1]
16+
17+
include::modules/microshift-adding-service-to-blueprint.adoc[leveloffset=+2]
18+
19+
include::modules/microshift-creating-ostree-iso.adoc[leveloffset=+2]
20+
21+
[id="additional-resources_microshift-embed-microshift-offline-deployments_{context}"]
22+
[role="_additional-resources"]
23+
== Additional resources
24+
25+
* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image_composing-a-customized-rhel-system-image#con_the-container-registry-credentials_assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image[Pushing a container to a registry and embedding it into an image]
26+
* link:https://www.osbuild.org/guides/image-builder-on-premises/container-auth.html[Container registry credentials]

‎modules/microshift-creating-ostree-iso.adoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55

66
:_content-type: PROCEDURE
77
[id="microshift-creating-ostree-iso_{context}"]
8-
= Creating the {op-system-ostree-first} image
8+
= Creating the {op-system-ostree} image
99

10-
Use the following procedure to create the ISO. The {op-system-ostree} Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded OSTree commit.
10+
Use the following procedure to create the ISO. The {op-system-ostree} Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded `rpm-ostree` commit.
1111

1212
.Prerequisites
1313
* Your build host meets the Image Builder system requirements.
1414
* You have installed and set up Image Builder and the `composer-cli` tool.
1515
* You have root-user access to your build host.
16-
* You have the `podman` tool.
16+
* You have installed the `podman` tool.
1717
1818
.Procedure
1919

‎modules/microshift-embed-microshift-build-image.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_running_applications/embed-microshift-offline-deploy.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-embed-microshift-build-image-offline-deployment_{context}"]
7+
= Build and use the rpm-ostree image for offline deployments
8+
9+
You can use Image Builder to create `rpm-ostree` system images with embedded {microshift-short} container images. To embed container images, you must add the image references to your Image Builder blueprint. You can create the commit and ISO as needed for your use case.
10+
11+
Add the prerequisites listed here to the ones that are included in the procedures that follow.
12+
13+
[id="microshift-embed-microshift-build-image-offline-deployment-prereqs_{context}"]
14+
== Additional prerequisites for offline deployments
15+
16+
* You have created and updated a {op-system-ostree} image blueprint for offline use. The following procedures use the example of a blueprint created with container images. You must use the updated blueprint you created in the "Embedding MicroShift containers for offline deployments" procedure.
17+
* You have updated the `/etc/osbuild-worker/osbuild-worker.toml` configuration file for offline use.
18+
19+
[IMPORTANT]
20+
====
21+
Replace `minimal-microshift.toml` in the following procedures with the name of the TOML you updated for offline use, <my_blueprint_name>.
22+
====

‎modules/microshift-embed-microshift-image-offline-deploy.adoc

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
// Module included in the following assemblies:
2+
//
3+
// microshift_running_applications/embed-microshift-offline-deploy.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-embed-microshift-image-offline-deployment_{context}"]
7+
= Embedding {microshift-short} containers for offline deployments
8+
9+
You can use Image Builder to create `rpm-ostree` system images with embedded {microshift-short} container images. To embed container images, you must add the image references to your Image Builder blueprint.
10+
11+
.Prerequisites
12+
13+
* You have root-user access to your build host.
14+
* Your build host meets the Image Builder system requirements.
15+
* You have installed and set up Image Builder and the `composer-cli` tool.
16+
* You have created a {op-system-ostree} image blueprint.
17+
* You have installed jq.
18+
19+
.Procedure
20+
21+
. Get the exact list of container image references used by the {microshift-short} version you are deploying. You can either install the `microshift-release-info` RPM package by following step 2 or download and unpack the RPM by following step 3.
22+
23+
. To install the `microshift-release-info` RPM package:
24+
25+
.. Install the `microshift-release-info` RPM package by running the following command:
26+
+
27+
[source,terminal]
28+
----
29+
$ sudo dnf install -y microshift-release-info-<release_version>
30+
----
31+
Replace `<release_version>` with the numerical value of the release you are deploying, using the entire version number, such as `4.14.0`.
32+
33+
.. List the contents of the `/usr/share/microshift/release` directory to verify the presence of the release information files by running the following command:
34+
+
35+
[source,terminal]
36+
----
37+
$ ls /usr/share/microshift/release
38+
----
39+
+
40+
.Example output
41+
[source,terminal]
42+
----
43+
release-x86_64.json
44+
release-aarch64.json
45+
----
46+
+
47+
If you installed the `microshift-release-info` RPM, you can proceed to step 4.
48+
49+
. If you did not complete step 2, download and unpack the `microshift-release-info` RPM without installing it:
50+
51+
.. Download the RPM package by running the following command:
52+
+
53+
[source,terminal]
54+
----
55+
$ sudo dnf download microshift-release-info-<release_version>
56+
----
57+
Replace `<release_version>` with the numerical value of the release you are deploying, using the entire version number, such as `4.14.0`.
58+
+
59+
.Example rpm
60+
[source,terminal]
61+
----
62+
microshift-release-info-4.14.0.*.el9.noarch.rpm <1>
63+
----
64+
<1> The `*` represents the date and commit ID. Your output should contain both, for example `-202311101230.p0.g7dc6a00.assembly.4.14.0`.
65+
66+
.. Unpack the RPM package without installing it by running the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ rpm2cpio <my_microshift_release_info> | cpio -idmv <1>
71+
./usr/share/microshift/release/release-aarch64.json
72+
./usr/share/microshift/release/release-x86_64.json
73+
----
74+
<1> Replace `<my_microshift_release_info>` with the name of the RPM package from the previous step.
75+
76+
. Define the location of your JSON file, which contains the container reference information, by running the following command:
77+
+
78+
[source,terminal]
79+
----
80+
$ RELEASE_FILE=</path/to/your/release-$(uname -m).json>
81+
----
82+
Replace `</path/to/your/release-$(uname -m).json>` with the full path to your JSON file. Be sure to use the file needed for your architecture.
83+
84+
. Define the location of your TOML file, which contains instructions for building the image, by running the following command:
85+
+
86+
[source,terminal]
87+
----
88+
$ BLUEPRINT_FILE=</path/to/your/blueprint.toml>
89+
----
90+
Replace `</path/to/your/blueprint.toml>` with the full path to your JSON file.
91+
92+
. Generate and then embed the container image references in your blueprint TOML file by running the following command:
93+
+
94+
[source,terminal]
95+
----
96+
$ jq -r '.images | .[] | ("[[containers]]\nsource = \"" + . + "\"\n")' "${RELEASE_FILE}" >> "${BLUEPRINT_FILE}"
97+
----
98+
+
99+
.Example resulting `<my_blueprint.toml>` fragment showing container references
100+
[source,terminal]
101+
----
102+
[[containers]]
103+
source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db"
104+
105+
[[containers]]
106+
source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db"
107+
----
108+
109+
. You can manually embed any container image by adding it to the Image Builder blueprint using the following example:
110+
+
111+
.Example section for manually embedding container image to Image Builder
112+
[source,terminal]
113+
----
114+
[[containers]]
115+
source = "<my_image_pullspec_with_tag_or_digest>"
116+
----
117+
Replace `<my_image_pullspec_with_tag_or_digest>` with the exact reference to a container image used by the {microshift-short} version you are deploying.

‎modules/microshift-embed-microshift-update-osbuilder-worker.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
//
3+
// microshift_running_applications/embed-microshift-offline-deploy.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-embed-microshift-update-osbuilder-worker_{context}"]
7+
= Updating osbuilder worker configuration to prepare for image building
8+
9+
After you have updated the blueprint, you must update the osbuilder worker configuration to prepare for building the image with embedded {microshift-short} containers.
10+
11+
.Prerequisites
12+
13+
* You have root-user access to your build host.
14+
* Your build host meets the Image Builder system requirements.
15+
* You have installed and set up Image Builder and the `composer-cli` tool.
16+
17+
[NOTE]
18+
====
19+
You can create an `/etc/osbuild-worker/osbuild-worker.toml` directory and configuration file if they do not exist.
20+
====
21+
22+
.Procedure
23+
24+
. Add a pull secret for authenticating to the registry by setting the `auth_file_path` in the `[containers]` section of the `/etc/osbuild-worker/osbuild-worker.toml` osbuilder worker configuration file:
25+
+
26+
[source,terminal]
27+
----
28+
[containers]
29+
auth_file_path = "/etc/osbuild-worker/pull-secret.json"
30+
----
31+
32+
. Restart the `osbuild-worker` to apply configuration changes by restarting the host. Restarting the host ensures that all `osbuild-worker` services currently running are restarted.

0 commit comments

Comments
 (0)