diff --git a/modules/ch4-update/pages/index.adoc b/modules/ch4-update/pages/index.adoc index a8cc279..efa42a6 100644 --- a/modules/ch4-update/pages/index.adoc +++ b/modules/ch4-update/pages/index.adoc @@ -3,12 +3,10 @@ Goal:: Publish and Validate updates of RHEL for Edge images using OSTree deltas and local VMs. -WARNING: Work In Progress - == Introduction This chapter explains how to use RPM-OStree technology from RHEL to apply and test edge device updates, as part of a development or CI/CD workflow. -This chapter presents a series of hands-on activities which update the operating system in VMs using OSTree repositories, and optimize those system updates by building static deltas. +This chapter presents a series of hands-on activities that update the operating system in VMs using OSTree repositories, and optimize those system updates by building static deltas. This is the final chapter of this course. Stay tuned for future courses which teach other features included in Red Hat Device Edge, such as MicroShift and Green Boot. diff --git a/modules/ch4-update/pages/s1-deltas.adoc b/modules/ch4-update/pages/s1-deltas.adoc index 25f9df2..b1faac5 100644 --- a/modules/ch4-update/pages/s1-deltas.adoc +++ b/modules/ch4-update/pages/s1-deltas.adoc @@ -8,8 +8,6 @@ Objective:: Understand how edge devices consume operating system updates from OSTree repositories. -WARNING: Work In Progress - == Device Updates Edge devices running RHEL for Edge retrieve operating system updates as new system images. They do not download individual package updates from RPM repositories, like package-based RHEL deployments do. You cannot end up in a state where some updates were applied but others weren't. You either update the entire system image or do not update anything. @@ -18,13 +16,13 @@ image::s1-deltas-fig-1.svg[title="End of an edge device installation and update RPM-OSTree keeps two system images side-by-side in a system, and only switches from the current to the new system image with a reboot -- contrast that with RPM package updates, which alter files which may be in use by running processes and may produce unpredictable results. -You can rollback an RPM-OSTree system into a previous known good image -- contrast that with rolling back an update of multiple RPM packages. With package-based systems, you can select an older kernel at boot, but you cannot easily revert all system binaries and dependency libraries, some of which may depend on the kernel version. With an image-based system using RPM-OStree you revert to the the kernel, libraries, and binaries of a previous system image all at one. +You can rollback an RPM-OSTree system into a previously known good image -- contrast that with rolling back an update of multiple RPM packages. With package-based systems, you can select an older kernel at boot, but you cannot easily revert all system binaries and dependency libraries, some of which may depend on the kernel version. With an image-based system using RPM-OStree you revert to the the kernel, libraries, and binaries of a previous system image all at once. You must use the `rpm-ostree` command on an edge device to download (stage) a new system image, and then reboot the system to deploy the new image. The same command allows you to rollback to the previous system image. -In case you download further system updates, the one not currently active is discarded to give room to the new updates, so there's typically just two system images in edge devices and you don't need to prune old updates nor risk exhausting disk space on the devices. It is possible to have three images, for a short period of time, between staging an upgrade and applying that upgrade, during the next reboot, if was not the first upgrade applied to an edge device. +In case you download further system updates, the one not currently active is discarded to give room to the new updates, so there are typically just two system images in edge devices and you don't need to prune old updates nor risk exhausting disk space on the devices. It is possible to have three images, for a short period of time, between staging an upgrade and applying that upgrade, during the next reboot, if it was not the first upgrade applied to an edge device. -Both on disk and during download, RPM-OStree takes advantage of OSTree capabilities to not store nor download files which didn't change between the current and the new system image. But the process of checking file changes can still take multiple network transactions and be slow for systems with low-bandwidth or high-latency network connections. In that case, you're advised to crate a static delta on your OSTree repository for faster download of updates. +Both on disk and during download, RPM-OStree takes advantage of OSTree capabilities to not store nor download files that didn't change between the current and the new system image. However, the process of checking file changes can still take multiple network transactions and be slow for systems with low-bandwidth or high-latency network connections. In that case, you're advised to create a static delta on your OSTree repository for faster download of updates. == Device Updates and Configuration or Application Data @@ -32,19 +30,19 @@ Most of the file system is read-only under RPM-OStree so those contents can be s * Files in `/var` are only touched at first boot, when they're copied from the system image to the writable file system, but updates keep the contents in `/var` unchanged. -* Files in `/etc` are updated with a three-way merge process: the current `/etc` contents are compared with the current system image; differences are applied a copy of the contents of `/etc` from the new system image; and the result saved to the writable file system. +* Files in `/etc` are updated with a three-way merge process: the current `/etc` contents are compared with the current system image; differences are applied to a copy of the contents of `/etc` from the new system image; and the result is saved to the writable file system. -The goal is, on one side, to preserve application data in `/var` across system updates, while at the same time enabling applications to include initial data in a system image; and on the other side, enable new system images to bring new configuration files and change configuration defaults, while preserving local customizations applied to the running system. +The goal is, on one side, to preserve application data in `/var` across system updates, while at the same time enabling applications to include initial data in a system image; and on the other side, to enable new system images to bring new configuration files and change configuration defaults, while preserving local customizations applied to the running system. -If a system update requires changes to application data, for example migrating data to a new database schema, this is responsibility of the application. It could run a first boot job to perform the database migration or use any other strategy. Just do not rely on RPM-OSTree itself to make application data compatible with a new version of an application and its dependencies. +If a system update requires changes to application data, for example, migrating data to a new database schema, this is the responsibility of the application. It could run a first boot job to perform the database migration or use any other strategy. Just do not rely on RPM-OSTree itself to make application data compatible with a new version of an application and its dependencies. == Building Update Images with Image Builder An update image is just a regular edge commit image produced by Image Builder, but its single OSTree commit must reference a parent commit so it can be later pulled into a remote OSTree repository and preserve the history if its branch. -image::ch2-publish:s1-ostree-fig-2.svg[title="OSTree repostory, branches/references, commits, and remotes"] +image::ch2-publish:s1-ostree-fig-2.svg[title="OSTree repository, branches/references, commits, and remotes"] -If you build an update image without a reference to a parent commit, when you pull it into a remote OSTree repository it will clean all previous history of its branch. That may cause issues for edge devices that need to rollback to previous images and eliminates the possibility of creating static deltas for updating edge devices on slow networks. +If you build an update image without a reference to a parent commit, when you pull it into a remote OSTree repository it will clean all the previous history of its branch. That may cause issues for edge devices that need to rollback to previous images and eliminate the possibility of creating static deltas for updating edge devices on slow networks. You must start Image Builder composes for updates of edge images with a reference to a remote OSTree repository and a branch. That way, the new edge commit image records the current head of the branch as its parent. @@ -64,15 +62,15 @@ Assuming your RHEL for Edge system image passes integration tests, you might per image::s1-deltas-fig-5.svg[title="New edge image, passed all tests and published on production repositories"] -At each of these states, you may use different OSTree repositories, and copy edge images, that is their OSTree commits, from one repository to the next. Finally, you could maintain multiple repositories with the copies of the same production images, for fault-tolerance or to serve different geographical regions. This all works because OSTree commit IDs are unique and do not change as you copy them from one repository to another. +At each of these states, you may use different OSTree repositories, and copy edge images, that is their OSTree commits, from one repository to the next. Finally, you could maintain multiple repositories with copies of the same production images, for fault-tolerance or to serve different geographical regions. This all works because OSTree commit IDs are unique and do not change as you copy them from one repository to another. -What if an edge commit image does not pass tests and is never delivered to production? Just build the next iteration using the same parent OSTree commit as the failed image. That way it replaces the previous iterations on the intermediate OSTree repositories you use for testing, and if it passess all tests it can be added to production repositories. +What if an edge commit image does not pass tests and is never delivered to production? Just build the next iteration using the same parent OSTree commit as the failed image. That way it replaces the previous iterations on the intermediate OSTree repositories you use for testing, and if it passes all tests it can be added to production repositories. image::s1-deltas-fig-6.svg[title="New edge image, failed some tests so it's not promoted to production and discarded, and optionally purged from test repositories"] So, instead of using the latest test image (latest OSTree commit from test repositories) as the parent of the next image you build for testing, you keep using the latest production image (latest successfully delivered to production) as the parent of all test images, until one of them is promoted all the way to production and becomes the new latest. A way of enforcing that is using, during image build, a reference to a production OSTree repository, even if the image being built might never be pulled into the production repository. -You can specify, for an OSTree compose, the URL of an web server which is not the one you intent to use to distribute system images to edge devices in production. That is, your development or testing remote OSTree repository is different than the production repository. An OSTree commit contains no metadata about OSTree remotes. OSTree remotes for fetching upgrades are configured by device-specific customizations, such as Kickstart files, or at day-2. +You can specify, for an OSTree compose, the URL of a web server which is not the one you intend to use to distribute system images to edge devices in production. That is, your development or testing remote OSTree repository is different than the production repository. An OSTree commit contains no metadata about OSTree remotes. OSTree remotes for fetching upgrades are configured by device-specific customizations, such as Kickstart files, or on day-2. During testing you usually deploy a test VM (or physical device) as if it's being provisioned for the first time. But, if your testing requires performing an RPM-OSTree update process, to perform tasks such as data schema migration, you can override the OSTree remote on the test machine before applying an update. @@ -82,13 +80,13 @@ IMPORTANT: Edge devices provisioned using edge installer images are *not* config You do not need to prune the local OSTree repository of an edge device because RPM-OStree does that automatically, always keeping at most two deployed system images in the device, plus one optional staged image. Deduplication of OSTree content happens at the file level, not at the branch or commit level, so you can safely prune older commits without losing files that didn't change and are still in use by more recent commits. -Os production or test repositories it may be necessary to implement a process for pruning old commits, based on count, age, or whatever other criteria. Else those repositories may grow unbounded and some day be out of disk space. +Os production or test repositories it may be necessary to implement a process for pruning old commits, based on count, age, or whatever other criteria. Otherwise those repositories may grow unbounded and someday be out of disk space. OSTree commits are considered derived data: the source of truth of an edge commit image is not the image itself, but the source code used to build its applications, its blueprint, and package list from RPM repositories. It is assumed that you could rebuild an old edge image exactly as it were, by providing the same inputs. So, unlike a source code repository, there is no need to keep historical data on an OSTree repository. -You may need manually prune an OStree repository of its latest commit. Remember that happens automatically in a test repository, when you pull in a newer test image which uses the same parent as the previous test image. But what if an image was already promoted all the way into production, and only then you find an issue? Pruning the latest image in a branch of a production repository prevents more edge devices from pulling that image as a system update. For devices that already applied the update, you rollback them to the previous image. And, when you fix whatever issue required you to remove the latest commit, you provide a fix as a new system image, which is just another image update to all edge devices. +You may need to manually prune an OStree repository of its latest commit. Remember that happens automatically in a test repository, when you pull in a newer test image which uses the same parent as the previous test image. But what if an image was already promoted all the way into production, and only then do you find an issue? Pruning the latest image in a branch of a production repository prevents more edge devices from pulling that image as a system update. For devices that already applied the update, you rollback them to the previous image. And, when you fix whatever issue requires you to remove the latest commit, you provide a fix as a new system image, which is just another image update to all edge devices. -The activities in thos course do not demonstrate pruning OSTree repositories. If you need to perform that, check the `ostree prune` command, in special the options `--delete-commit` and `--keep-younger-than`. +The activities in those courses do not demonstrate pruning OSTree repositories. If you need to perform that, check the `ostree prune` command, in special the options `--delete-commit` and `--keep-younger-than`. == OSTree Static Deltas @@ -96,21 +94,21 @@ OSTree static delta helps edge devices with challenging network connectivity to The standard process for downloading OSTree updates is similar to what Rsync, Git, DNF, and similar systems perform, which is basically a file-by-file check. If a system already has the file, move to the next. If it doesn't, download it. This process allows a device to skip updates and move straight to the latest one, instead of having to pass through multiple intermediate updates. -Unfortunately, the standard process requires many network transactions, as a device checks individual files on a remote repository. It does not require lots of bandwidth, as each file check sends very little data over the network but, if anything delays some of requests or their responses, the overall update may take a long time. +Unfortunately, the standard process requires many network transactions, as a device checks individual files on a remote repository. It does not require lots of bandwidth, as each file check sends very little data over the network but, if anything delays some of the requests or their responses, the overall update may take a long time. OSTree offers the possibility of pre-computing and storing static deltas between any two commits as part of an OSTree repository. OSTree clients will discover and use these pre-computed deltas, called *static deltas*, transparently, saving network capacity and reducing the time to download updates. -image::s1-deltas-fig-7.svg[title="Edge devices downloading updates as either static deltas or file-by-file"] +image::s1-deltas-fig-7.svg[title="Edge devices download updates as either static deltas or file-by-file"] If it happens that an edge device skips an update, for example because it was offline for too long, It will just download changes the usual way, without using the deltas between the current and the previous commit. If you expect this to be a frequent event, you could build static deltas between the current latest and multiple previous commits: one delta for latest → latest-1, another delta for latest → latest-2, one more for latest → latest-3, and so on. Each static delta takes up disk space on OSTree repository servers, but we usually consider that disk space on servers is cheaper than at edge devices or than network bandwidth to edge devices. -Having static deltas reduces the memory and CPU requirements of servers when updating edge devices. If you consider that an OSTree server has a potentially large population of client edge devices, compared to the population of developers using a Git repository, the efficiency gains can be large, not to mention a lower cloud bill for running your OSTree servers. +Having static deltas reduces the memory and CPU requirements of servers when updating edge devices. If you consider that an OSTree server has a potentially large population of client-edge devices, compared to the population of developers using a Git repository, the efficiency gains can be large, not to mention a lower cloud bill for running your OSTree servers. -Pre-computed static deltas also saves CPU and memory from edge devices while downloading and deploying system updates. The gains are especially welcome by smaller edge devices, which have slower CPUs and less memory than office workstations, and are expected to continue performing their regular tasks while downloading and staging system updates. +Pre-computed static deltas also save CPU and memory from edge devices while downloading and deploying system updates. The gains are especially welcome by smaller edge devices, which have slower CPUs and less memory than office workstations, and are expected to continue performing their regular tasks while downloading and staging system updates. -In fact, static deltas may be so good for some devices and networks that some RPM-OStree users create empty deltas: they store the difference between a commit and nothing, which is is the entire commit. But that empty delta can be queried and downloaded as a single unit, instead of a file-by-file basis, which saves memory, CPU, and network capacity between an edge device and a remote OSTree repository. +In fact, static deltas may be so good for some devices and networks that some RPM-OStree users create empty deltas: they store the difference between a commit and nothing, which is the entire commit. But that empty delta can be queried and downloaded as a single unit, instead of a file-by-file basis, which saves memory, CPU, and network capacity between an edge device and a remote OSTree repository. == OSTree Summary Files @@ -124,10 +122,10 @@ It's common to use an OSTree branch to represent a major version of an operating A RHEL for Edge system can use the RPM-OStree rebase operation to switch between OSTree branches and thus update to a new operating system or application major release. -Another scenario for performing rebases could be repurposing an existing edge device to run a different application, by switching it to a different branch of the same OSTree repository. It may be worthwhile, compared to reprovisioning devices from scratch, if the branches share a same base operating system and similar dependency libraries. +Another scenario for performing rebases could be repurposing an existing edge device to run a different application, by switching it to a different branch of the same OSTree repository. It may be worthwhile, compared to reprovisioning devices from scratch, if the branches share the same base operating system and similar dependency libraries. We are not performing rebases in the hands-on activities, as this is a somewhat rare event -- a major new release frequently requires a hardware refresh. We also do not exercise other RPM-OSTree features, such as applying a mutable layer over `/usr` to install RPM packages outside its system images, but we encourage people to use the `--help` option to explore the verbs of the `rpm-ostree` command and explore its possibilities. == Next Steps -The final series of hands-on activities in this course builds, installs and rolls backs updates to edge system images using test VMs that were provisioned using different methods. +The final series of hands-on activities in this course builds, installs and rolls back updates to edge system images using test VMs that were provisioned using different methods. diff --git a/modules/ch4-update/pages/s2-update-lab.adoc b/modules/ch4-update/pages/s2-update-lab.adoc index f1004b3..f3b94a9 100644 --- a/modules/ch4-update/pages/s2-update-lab.adoc +++ b/modules/ch4-update/pages/s2-update-lab.adoc @@ -9,13 +9,11 @@ Objective:: Build RHEL for Edge image updates, publish them as OSTree deltas, and apply the updates to a test VM. -WARNING: Work in Progress - == Before you Begin -You need a _development machine_ with RHEL and configured with the Image Builder service, its CLI and web UI, and a user that is member of the `weldr` group. Make sure your development machine was configured and verified by following the instructions from the xref:ch1-build:s4-install-lab.adoc[first lab]. +You need a _development machine_ with RHEL and configured with the Image Builder service, its CLI and web UI, and a user that is a member of the `weldr` group. Make sure your development machine is configured and verified by following the instructions from the xref:ch1-build:s4-install-lab.adoc[first lab]. -You also need a _web server machine_ which serves an OSTree repository. Make sure that machine was configured and verified by following the instructions from xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. +You also need a _web server machine_ which serves an OSTree repository. Make sure that the machine was configured and verified by following the instructions from xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. Finally, you need the _test VM_ that you created and published in xref:ch3-test:s2-boot-lab.adoc[another lab]. @@ -44,7 +42,7 @@ API server status: ... -- -.. Check that a remote client can access the OSTree repository in the _web server machine_ and get the current commit ID the OSTree branch with the Apache Web Server system image that you created in xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. You will get a different ID: +.. Check that a remote client can access the OSTree repository in the _web server machine_ and get the current commit ID of the OSTree branch with the Apache Web Server system image that you created in xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. You will get a different ID: + [source,subs="verbatim,quotes,attributes"] -- @@ -54,7 +52,7 @@ $ *curl http://servera.lab.example.com/repo/refs/heads/rhel/9/x86_64/edge* + Pay attention to the final path element of the URL, which should be "edge". The commit ID you got will be the parent commit of the edge commit image you are building during this lab. -.. Check that you can manage local VMs, and there's a VM left from the xref:ch3-test:s2-boot-lab:[previous lab] named `edge-test-1`. +.. Check that you can manage local VMs, and that there's a VM left from the xref:ch3-test:s2-boot-lab:[previous lab] named `edge-test-1`. + [source,subs="verbatim,quotes"] -- @@ -65,13 +63,13 @@ $ *virsh list --all* 2 edge-db-1 shut-off -- + -It's fine if the existing VM displays an status of "running" instead of "shut off". +It's fine if the existing VM displays a status of "running" instead of "shut off". 2. On your _developer machine_, make changes to the edge image blueprint to add the Cockpit packages. .. Open the `rhel9-httpd.toml` file, which you created in a xref:ch1-build:s6-blueprint-lab.adoc[previous lab], with any text editor. + -Increment the minor version number, in the beginning of the TOML file, add a new `packages` section, and makes changes to its `services` and `firewall` customization sections. The file should look like the following, after all edits: +Increment the minor version number, at the beginning of the TOML file, add a new `packages` section, and make changes to its `services` and `firewall` customization sections. The file should look like the following, after all edits: + [source,subs="verbatim"] -- @@ -102,7 +100,7 @@ include::1@samples:blueprints:example$rhel9-httpd-v2.toml[lines=1..3] 3. Still on your _development machine_, build a new edge commit image from your changed blueprint. + -This is very similar to what you done in previous labs, but pay attention to the differences required for update images and a few hints about the usage of the `composer-cli` command. +This is very similar to what you did in the previous labs, but pay attention to the differences required for updating images and a few hints about the usage of the `composer-cli` command. .. Start a compose for an edge commit image and copy its UUID to a shell variable. + @@ -127,7 +125,7 @@ $ *composer-cli compose list running* ID Status Blueprint Version Type -- -.. Once the list of running composes is empty, it means your compose job either finished or failed. You could filter the list of composes on those statuses, but after some time both lists could become too large for visual inspection. Let's see how to filter the JSON output of `composer-cli` to get the status of just one compose by its UUID: +.. Once the list of running composes is empty, it means your compose job is either finished or failed. You could filter the list of composes on those statuses, but after some time both lists could become too large for visual inspection. Let's see how to filter the JSON output of `composer-cli` to get the status of just one compose by its UUID: + [source,subs="verbatim,quotes"] -- @@ -145,12 +143,12 @@ FAILED + Because our compose didn't fail, the previous query returns empty. + -NOTE: You can download, from the source samples repository in GitHub, a https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/sh/status-compose.sh[simple Bash script] that returns the status of a compose gives its UUID. The script contains the `jq` from previous commands and also a couple other queries. +NOTE: You can download, from the source samples repository in GitHub, a https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/sh/status-compose.sh[simple Bash script] that returns the status of a compose and gives its UUID. The script contains the `jq` from previous commands and also a couple of other queries. -.. Download the edge commit image and copy it to your _web sever machine_. +.. Download the edge commit image and copy it to your _web server machine_. + -Because you have to track two sets of hashes, one for compose UUIDs, another for OSTree commit IDs, use the `--filename` option to give a mnemonic name to the TAR file of your edge commit image. This way, you won't be lost trying to figure out which of your many TAR files corresponds to each edge image, specially after they are moved to a different machine than the one where you run the Image Builder service. +Because you have to track two sets of hashes, one for compose UUIDs, and another for OSTree commit IDs, use the `--filename` option to give a mnemonic name to the TAR file of your edge commit image. This way, you won't be lost trying to figure out which of your many TAR files corresponds to each edge image, especially after they are moved to a different machine than the one where you run the Image Builder service. + [source,subs="verbatim,quotes"] -- @@ -162,7 +160,7 @@ $ *scp rhel9-httpd-v2-commit.tar servera:~* 4. Open a terminal on your _web server machine_ and copy the new edge image to the OSTree repository. -.. Check that the new edge commit image exists on your home folder. +.. Check that the new edge commit image exists in your home folder. + [source,subs="verbatim,quotes"] -- @@ -205,10 +203,10 @@ Version: 9.2 -- <.> Commit ID of the new edge commit image -<.> Commit ID of parent of the new edge commit image +<.> Commit ID of the parent of the new edge commit image <.> Commit ID of the current head of the remote OSTree repository, which should match the previous commit ID. -.. Now that you verified that your new edge commit image can connect to the existing history of your OSTree repository, pull the new edge commit image into the OSTree repository on the web server. +.. Now that you have verified that your new edge commit image can connect to the existing history of your OSTree repository, pull the new edge commit image into the OSTree repository on the web server. + [source,subs="verbatim,quotes"] -- @@ -242,7 +240,7 @@ Version: 9.2 (no subject) -- <.> Commit ID of the new edge commit image -<.> Commit ID of parent of the new edge commit image +<.> Commit ID of the parent of the new edge commit image <.> Commit ID of the old edge commit image, which is the parent of the new edge commit image .. You can now delete the temporary directory. @@ -265,7 +263,7 @@ $ *virsh domstate edtge-test-1* running -- -.. Attach to the console of your _test VM_ and log in as the user `core` with password `redhat123`. It may be necessary to press kbd:[Enter] a few times to get a login prompt +.. Attach to the console of your _test VM_ and log in as the user `core` with password `redhat123`. It may be necessary to press kbd:[Enter] a few times to get a login prompt. + [source,subs="verbatim,quotes"] -- @@ -274,7 +272,7 @@ $ *virsh console edge-test-1* edge login: -- -.. Change the hostname of your _test VM_ and verify that change is stored in a file under the `/etc/` directory. +.. Change the hostname of your _test VM_ and verify that the change is stored in a file under the `/etc/` directory. + [source,subs="verbatim,quotes"] -- @@ -370,7 +368,7 @@ Run "systemctl reboot" to start a reboot + NOTE: You can safely ignore the SELinux errors during staging of a new system image. Those issues are fixed by reboot, when the kernel loads the SELinux policy included in the new system image. -.. You can verify that the new system image is not active (its the second deployment) but it is marked for the next reboot (notice the bullet). +.. You can verify that the new system image is not active (it's the second deployment) but it is marked for the next reboot (notice the bullet). + [source,subs="verbatim,quotes,attributes"] -- @@ -387,7 +385,7 @@ Deployments: Commit: {commit-httpd-v2} -- -7. Still on your _development machine_, apply the upgrade to your _test VM_ and verify it is running the new edge commit image you built during this lab. +7. Still, on your _development machine_, apply the upgrade to your _test VM_ and verify it is running the new edge commit image you built during this lab. .. Reboot your _test VM_, log in again, and verify that the new commit is now the first (active) deployment and also the one marked for the next boot (as indicated by the bullet). + diff --git a/modules/ch4-update/pages/s3-rollback-lab.adoc b/modules/ch4-update/pages/s3-rollback-lab.adoc index e5504e4..708afea 100644 --- a/modules/ch4-update/pages/s3-rollback-lab.adoc +++ b/modules/ch4-update/pages/s3-rollback-lab.adoc @@ -7,15 +7,13 @@ _Estimated reading time: *{time_estimate} minutes*._ Objective:: -Rollback a test VM to a previous known good RHEL for Edge system image. - -WARNING: Work in Progress +Rollback a test VM to a previously known good RHEL for Edge system image. == Before you Begin -You need a _development machine_ with RHEL and configured with the Image Builder service, its CLI and web UI, and a user that is member of the `weldr` group. Make sure your development machine was configured and verified by following the instructions from the xref:ch1-build:s4-install-lab.adoc[first lab]. +You need a _development machine_ with RHEL and configured with the Image Builder service, its CLI and web UI, and a user that is a member of the `weldr` group. Make sure your development machine is configured and verified by following the instructions from the xref:ch1-build:s4-install-lab.adoc[first lab]. -You also need a _web server machine_ which serves an OSTree repository. Make sure that machine was configured and verified by following the instructions from xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. +You also need a _web server machine_ which serves an OSTree repository. Make sure that the machine was configured and verified by following the instructions from xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. Finally, you need the _test VM_ that you updated in xref:s2-update-lab.adoc[the previous lab]. While you could perform the focus tasks in this lab on a _test VM_ that was never updated before, that is, you can rollback the first update of an edge device, the instructions and outputs here assume that there are previous updates already applied to the _test VM_, to demonstrate that RPM-OSTree automatically prunes older system updates. @@ -44,7 +42,7 @@ API server status: ... -- -.. Check that you can get the current commit ID the OSTree branch with the Apache Web Server system image update that you created in xref:s2-update-lab.adoc[the previous lab]. You will get a different ID: +.. Check that you can get the current commit ID of the OSTree branch with the Apache Web Server system image update that you created in xref:s2-update-lab.adoc[the previous lab]. You will get a different ID: + [source,subs="verbatim,quotes,attributes"] -- @@ -54,7 +52,7 @@ $ *curl http://servera.lab.example.com/repo/refs/heads/rhel/9/x86_64/edge* + Pay attention to the final path element of the URL, which should be "edge". The commit ID you get should be the active commit in your _test VM_ and it will be the parent commit of the new update image you are building during this lab. -.. Check that you can manage local VMs, and there's a VM left from the xref:s2-update-lab:[previous lab] named `edge-test-1`. +.. Check that you can manage local VMs, and that there's a VM left from the xref:s2-update-lab:[previous lab] named `edge-test-1`. + [source,subs="verbatim,quotes"] -- @@ -65,15 +63,15 @@ $ *virsh list --all* 2 edge-db-1 shut-off -- + -It's fine if the existing VM displays an status of "running" instead of "shut off". +It's fine if the existing VM displays a status of "running" instead of "shut off". 2. Make changes to the edge image blueprint to add the PHP packages. + -This similar to what you did in the previous lab. It's just another update image, which should pick whatever is the current HEAD of the remote OSTree repository as its parent. +This is similar to what you did in the previous lab. It's just another update image, which should pick whatever is the current HEAD of the remote OSTree repository as its parent. .. Open the `rhel9-httpd.toml` file which you edited in the xref:s2-update-lab.adoc[previous lab], with any text editor. -.. Increment the version number, in tbe beginning of the TOML file, and add two `packages` sections, one for the PHP interpreter and another for the PHP-FastCGI engine. There is no need to change any of the `customizations` section. After your edits, the TOML file should look like the following: +.. Increment the version number, at the beginning of the TOML file, and add two `packages` sections, one for the PHP interpreter and another for the PHP-FastCGI engine. There is no need to change any of the `customizations` section. After your edits, the TOML file should look like the following: + [source,subs="verbatim"] -- @@ -82,7 +80,7 @@ include::1@samples:blueprints:example$rhel9-httpd-v3.toml[lines=1..18] ... -- + -You can also download a https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/blueprints/rhel9-httpd-v3.toml[TOML file with all edits] from the course samples repository in GitHub. Beware that the file in the samples repository have different file names, but the same blueprint name, so they can be used as-is, without renaming. +You can also download a https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/blueprints/rhel9-httpd-v3.toml[TOML file with all edits] from the course samples repository in GitHub. Beware that the files in the samples repository have different file names, but the same blueprint name, so they can be used as-is, without renaming. .. Push the updated blueprint. @@ -105,7 +103,7 @@ include::1@samples:blueprints:example$rhel9-httpd-v3.toml[lines=1..3] ... -- -3. Still on your _development machine_, build another new edge commit image from your changed blueprint. +3. Still, on your _development machine_, build another new edge commit image from your changed blueprint. + This is similar to what you did in the previous lab. You just need something different from the previous images so you later can verify that your _test VM_ got the right updates. @@ -144,7 +142,7 @@ ID Status Blueprint Version Type NOTE: You can alternatively use a https://raw.githubusercontent.com/RedHatQuickCourses/rhde-build-samples/refs/heads/main/sh/status-compose.sh[simple Bash script] that returns the status of a compose given its UUID. -.. Download the edge commit image and copy it to your _web sever machine_. +.. Download the edge commit image and copy it to your _web server machine_. + Be careful to not overwrite the TAR files of previous edge commit images, because you might need them to reconstruct your remote OSTree repository in case you make mistakes. + @@ -236,7 +234,7 @@ Version: 9.2 <.> Parent commit of the previous commit, it was the initial commit <.> Initial commit -5. Still on your _development machine_, stage the new edge commit image on your _test VM_. +5. Still, on your _development machine_, stage the new edge commit image on your _test VM_. .. If your _test VM_ is shut down, start it. Then connect to its console and log in as the user `core` with password `redhat123`. + @@ -441,9 +439,9 @@ Timezone=Etc/UTC include::1@samples:html:example$info.php[] -- -As you see, rolling back an RPM-OSTree system just switches the active system image for the next boot. The newer but inactive system image remains available in edge devices, and could me marked active again, until a future upgrade removes it. +As you see, rolling back an RPM-OSTree system just switches the active system image for the next boot. The newer but inactive system image remains available in edge devices, and could be marked active again, until a future upgrade removes it. -Also notice that a system rollback does NOT rollbacks changes to configuration and application data. If your upgrade required special handling of application data, your rollback will also require it. +Also, notice that a system rollback does NOT rollbacks changes to configuration and application data. If your upgrade requires special handling of application data, your rollback will also require it. == Next Steps diff --git a/modules/ch4-update/pages/s4-deltas-lab.adoc b/modules/ch4-update/pages/s4-deltas-lab.adoc index dff996f..daa353e 100644 --- a/modules/ch4-update/pages/s4-deltas-lab.adoc +++ b/modules/ch4-update/pages/s4-deltas-lab.adoc @@ -9,13 +9,11 @@ Objective:: Update a test VM, that was provisioned using an edge installer image, using OSTree static deltas. -WARNING: Work in Progress - == Before you Begin -You need a _development machine_ with RHEL and configured with the Image Builder service, its CLI and web UI, and a user that is member of the `weldr` group. Make sure your development machine was configured and verified by following the instructions from the xref:ch1-build:s4-install-lab.adoc[first lab]. +You need a _development machine_ with RHEL and configured with the Image Builder service, its CLI and web UI, and a user that is a member of the `weldr` group. Make sure your development machine is configured and verified by following the instructions from the xref:ch1-build:s4-install-lab.adoc[first lab]. -You also need a _web server machine_ which serves an OSTree repository. Make sure that machine was configured and verified by following the instructions from xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. +You also need a _web server machine_ which serves an OSTree repository. Make sure that the machine was configured and verified by following the instructions from xref:ch2-publish:s2-ostree-lab.adoc[a previous lab]. Finally, you need the _database VM_ that you created in xref:ch3-test:s3-installer-lab.adoc[another lab]. @@ -54,7 +52,7 @@ API server status: ... -- -.. Check that you can get the current commit ID the OSTree branch with the database edge system image that you created in xref:ch2-publish:s3-pull-local-lab.adoc[a previous lab]. Your will get a different ID. +.. Check that you can get the current commit ID of the OSTree branch with the database edge system image that you created in xref:ch2-publish:s3-pull-local-lab.adoc[a previous lab]. You will get a different ID. + [source,subs="verbatim,quotes,attributes"] -- @@ -64,7 +62,7 @@ $ *curl http://servera.lab.example.com/repo/refs/heads/rhel/9/x86_64/db* + Pay attention to the final path element of the URL, which should be "db". -.. Check that you can manage local VMs, and there's a VM left from a xref:ch3-test:s3-installer-lab:[previous lab] named `edge-db-1`. +.. Check that you can manage local VMs, and that there's a VM left from a xref:ch3-test:s3-installer-lab:[previous lab] named `edge-db-1`. + [source,subs="verbatim,quotes"] -- @@ -75,13 +73,13 @@ $ *virsh list --all* 2 edge-db-1 shut-off -- + -It's fine the existing VM displays an status of "running" instead of "shut off". +It's fine the existing VM displays a status of "running" instead of "shut off". 2. On your _development machine_, make changes to the edge image blueprint to add the Nano text editor. .. Open the `rhel9-mysql.toml` file which you created in a xref:ch2-publish:s3-pull-local-lab.adoc[previous lab], with any text editor. -.. Increment the version number, in tbe beginning of the TOML file, and add a `packages` section which refer to packages from Nano. +.. Increment the version number, at the beginning of the TOML file, and add a `packages` section that refers to packages from Nano. + [source,subs="verbatim,quotes"] -- @@ -139,7 +137,7 @@ ID Status Blueprint Version Type ... -- -.. Download the edge commit image and copy it to your _web sever machine_. +.. Download the edge commit image and copy it to your _web server machine_. + [source,subs="verbatim,quotes"] -- @@ -216,7 +214,7 @@ Version: 9.2 -- -5. Still on your _web server machine_, create an static delta on the remote OSTree repository. +5. Still, on your _web server machine_, create a static delta on the remote OSTree repository. .. If you're using the HOL007 classroom, its `servera` VM has too little memory (less than 1GiB) and will fail to build static deltas. Work around that by creating and activating a swap file. + @@ -326,7 +324,7 @@ package nano is not installed db file:///run/install/repo/ostree/repo -- -.. Configure you _database VM_ with an OSTree remote that points to your _web server_ machine. +.. Configure your _database VM_ with an OSTree remote that points to your _web server_ machine. + [source,subs="verbatim,quotes"] -- @@ -378,7 +376,7 @@ nano-5.6.1-5.el9.x86_64 -- + -7. Still on your _development machine_, verify that your _database VM_ actually fetched upgrades using static deltas. +7. Still, on your _development machine_, verify that your _database VM_ actually fetched upgrades using static deltas. .. Search the system logs on the _database VM_. You should see two entries with a message `libostree pull`: one from checking for updates, which refers to no deltas and has a small transfer size, and another from the actual upgrade operation, which refers to a delta and with a larger transfer size. + @@ -400,7 +398,7 @@ Oct 22 15:40:45 db rpm-ostree[1246]: libostree pull from 'db' for rhel/9/x86_64/ + NOTE: If you do not see any evidence of using static deltas to perform the upgrade operation, it might be because you forgot to update the summary file of the remote OSTree repository after creating the static delta. In that case, the upgrade didn't use the available static delta. -.. If you search the system log of the _test VM_ from the previous labs, your would see entries similar to the following. +.. If you search the system log of the _test VM_ from the previous labs, you will see entries similar to the following. + [source,subs="verbatim,quotes"] -- @@ -471,4 +469,4 @@ As you see, the usage of static deltas is transparent to administrators of edge == Next Steps -This was the last activity in this course. Stay tuned for the remaining Red Hat Device Edge courses, which feature MicroShift, Ansible Automation, Green Boot and FDO. \ No newline at end of file +This was the last activity in this course. Stay tuned for the remaining Red Hat Device Edge courses, which feature MicroShift, Ansible Automation, Green Boot, and FDO. \ No newline at end of file diff --git a/modules/ch4-update/pages/s5-summary.adoc b/modules/ch4-update/pages/s5-summary.adoc index 11e90d5..fc0aee5 100644 --- a/modules/ch4-update/pages/s5-summary.adoc +++ b/modules/ch4-update/pages/s5-summary.adoc @@ -8,10 +8,10 @@ In this chapter, you learned: * Devices provisioned using edge installer images are *NOT* configured with an OSTree remote, you must configure it before applying updates. -* RPM-OSTree stages upgrades on the system disk, as a new OSTree commit, and applies then on the next boot. It also keeps the previous OSTree commit so you can rollback from the upgrade. +* RPM-OSTree stages an upgrade on the system disk, as a new OSTree commit, and applies it on the next boot. It also keeps the previous OSTree commit so you can rollback from the upgrade. * Changes to files in `/etc` and `/var` are retained during system updates and rollbacks. -* OSTree static deltas between two OSTree commits make system upgrades faster and more reliable for devices with high latency or low-bandwidth network connections, and most be created manually. +* OSTree static deltas between two OSTree commits make system upgrades faster and more reliable for devices with high latency or low-bandwidth network connections, and must be created manually. * Every time you add commits or static deltas to an OSTree repository, you must update its summary file.