From 52d6b05d1f689cb63968b59ee61522481691d0b7 Mon Sep 17 00:00:00 2001 From: Fernando Lozano Date: Wed, 23 Oct 2024 16:09:41 -0300 Subject: [PATCH] spellchecker fixes --- modules/ch4-update/pages/index.adoc | 4 +-- modules/ch4-update/pages/s1-deltas.adoc | 30 +++++++++---------- modules/ch4-update/pages/s2-update-lab.adoc | 10 +++---- modules/ch4-update/pages/s3-rollback-lab.adoc | 8 ++--- modules/ch4-update/pages/s4-deltas-lab.adoc | 10 +++---- modules/ch4-update/pages/s5-summary.adoc | 4 +-- 6 files changed, 33 insertions(+), 33 deletions(-) diff --git a/modules/ch4-update/pages/index.adoc b/modules/ch4-update/pages/index.adoc index 2973f70..a8cc279 100644 --- a/modules/ch4-update/pages/index.adoc +++ b/modules/ch4-update/pages/index.adoc @@ -7,8 +7,8 @@ WARNING: Work In Progress == Introduction -This chapter explains how to use RPM-OStree technoly from RHEL to apply and test edge device updates, as part of a development or CI/CD workflow. +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 is the final chapter of this course. Stay tuned for future courses which teach othr features included in Red Hat Device Edge, such as MicroShift and Green Boot. +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 4c9c0ea..35bd47a 100644 --- a/modules/ch4-update/pages/s1-deltas.adoc +++ b/modules/ch4-update/pages/s1-deltas.adoc @@ -18,11 +18,11 @@ 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-baed 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 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 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 at most two system images in edge devices and you don't need to prune old updates nor risk exhausting disk space on the devices. -Both on disk and during download, RPM-OStree takes advatage 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 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. == Device Updates and Configuration or Application Data @@ -34,7 +34,7 @@ Most of the file system is read-only under RPM-OStree so those contents can be s 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. -If a system update requires changes to application data, for example migrating data to a new database schema, this is responsability 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 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 @@ -46,7 +46,7 @@ If you build an update image without a reference to a parent commit, when you pu 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. -An edge commit image built with a reference to a parent commit is still a complete system image. It contains all files on the image, and the edge commit image contains an OSTree repo with a single commit, without previous history. But, when it's pulled into a remote OSTree repository, it can link to its parent there and the remove repository will deduplicate files between those commit and other commits on it. +An edge commit image built with a reference to a parent commit is still a complete system image. It contains all files on the image, and the edge commit image contains an OSTree repo with a single commit, without previous history. But, when it's pulled into a remote OSTree repository, it can link to its parent there and the remote repository will deduplicate files between those commit and other commits on it. == Distribution of Edge Image Updates @@ -68,9 +68,9 @@ What if an edge commit image does not pass tests and is never delivered to produ 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 successfuly delivered to production) as the patent 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 production OSTree repository, even if that image might never be pulled into the production repository. +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 patent 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 production OSTree repository, even if that image might never be pulled into the production repository. -It is perfectly fine if an edge commit image contains a remote which points to an OSTree repository which is not the one serving it. During testing you usually deploy a test VM (or phisical device) as that's being provisioned for the first time. But, if you testing requires the RPM-OSTree update process, to perform tasks such as data schema migration, you can override the remote reference on the test machine before applying an update. +It is perfectly fine if an edge commit image contains a remote which points to an OSTree repository which is not the one serving it. During testing you usually deploy a test VM (or physical device) as that's being provisioned for the first time. But, if you testing requires the RPM-OSTree update process, to perform tasks such as data schema migration, you can override the remote reference on the test machine before applying an update. IMPORTANT: Edge devices provisioned using edge installer images are *not* configured with a valid OSTree remote. You must configure it before being able to apply any system update. @@ -84,27 +84,27 @@ Os production or test repositories it may be necessary to implement a process fo 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 alrey 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 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. == OSTree Static Deltas OSTree static delta helps edge devices with bad network connectivity downloading system updates in a more efficient way. -The standard process for downloading OSTree updates is similar to what Rsync, Git, DNF, and similarsystems 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. +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. -OSTree offers the possibility of precomputing and storing static deltas between any two commits as part of an OSTree repository. OSTree clients will discover and use these precomputed deltas, called *static deltas*, transparently, saving network capacity and reducing the time to download updates. +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"] 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 bandwith to edge devices. +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. -Precomputed static deltas also saves CPU and memory from edge devices while downloading and deploying system updates. The gains are especially wellcome by smaller edge devices, which have slower CPUs and less memory than office workstations, and are expected to contine performing their regular tasks while downloading and staging system updates. +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. 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. @@ -112,18 +112,18 @@ In fact, static deltas may be so good for some devices and networks that some RP Every time you update an OSTree repository with multiple branches, updates, and static deltas, you must also update its summary file. Most OSTree clients, such as RPM-OSTree, will check only that summary for information on remote repositories. If that file is outdated, such clients will not be aware of updates or static deltas. -You do not need a sumary file for provisioning edge systems or building edge commit images because they either work with a predefined commit, which is the latest in a predefined branch. Those processes do not query a remote OSTree repository for the availability of other commits, deltas, or branches. +You do not need a summary file for provisioning edge systems or building edge commit images because they either work with a predefined commit or with the latest in a predefined branch. Those processes do not query a remote OSTree repository for the availability of other commits, deltas, or branches. == Rebasing an Edge Device -It's common to use an OSTree banch to represent a major version of an operating system + applications, and major updates of each become different OSTree branches. This is consistent with the fact that you don't usually phase out major application releases immediately, but keep supporting them with updates and bugfixes for a while. You cannot force all users to switch to a new major release all at once. +It's common to use an OSTree branch to represent a major version of an operating system + applications, and major updates of each become different OSTree branches. This is consistent with the fact that you don't usually phase out major application releases immediately, but keep supporting them with updates and bug fixes for a while. You cannot force all users to switch to a new major release all at once. 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 differnent 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 a 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 activties 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 backs 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 fa28a27..b326d1c 100644 --- a/modules/ch4-update/pages/s2-update-lab.adoc +++ b/modules/ch4-update/pages/s2-update-lab.adoc @@ -145,7 +145,7 @@ 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 scrit 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 gives its UUID. The script contains the `jq` from previous commands and also a couple other queries. .. Download the edge commit image and copy it to your _web sever machine_. @@ -206,7 +206,7 @@ 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 current head of the remote OSTree reposity, which should match the previous commit ID. +<.> 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. + @@ -252,7 +252,7 @@ Version: 9.2 $ *rm -rf delete-me* -- -5. Back to your _development machine_, make some changes to configuration and data on your _test VM_, which you created in a xref:ch3-test:s2-boot-lab.adoc[previous lab], so you can verify if those chantes are retained after an update. +5. Back to your _development machine_, make some changes to configuration and data on your _test VM_, which you created in a xref:ch3-test:s2-boot-lab.adoc[previous lab], so you can verify if those changes are retained after an update. .. If your _test VM_ is shut down, start it. + @@ -446,9 +446,9 @@ You already noticed the change of hostname in the login and shell prompts of the include::1@samples:html:example$index.html[] -- -.. If you wish, you can leave the console of your _test VM_ by typing kbd:[Ctrl+\]] and stop your _test VM_. Or you can leave it there to use the terminal for the next activiy and open another terminal on your _development VM_. +.. If you wish, you can leave the console of your _test VM_ by typing kbd:[Ctrl+\]] and stop your _test VM_. Or you can leave it there to use the terminal for the next activity and open another terminal on your _development VM_. -You sucessfully built an edge commit image and applied it as an update to a _test VM_, demonstrating that your new system image can upgrade edge devices. You also demonstrated that edge devices retain configuration and application data over system upgrades. +You successfully built an edge commit image and applied it as an update to a _test VM_, demonstrating that your new system image can upgrade edge devices. You also demonstrated that edge devices retain configuration and application data over system upgrades. == Next Steps diff --git a/modules/ch4-update/pages/s3-rollback-lab.adoc b/modules/ch4-update/pages/s3-rollback-lab.adoc index 76c7022..fa503cb 100644 --- a/modules/ch4-update/pages/s3-rollback-lab.adoc +++ b/modules/ch4-update/pages/s3-rollback-lab.adoc @@ -130,7 +130,7 @@ $ *composer-cli compose list running* ID Status Blueprint Version Type -- -.. Make sure your compose finished sucessfully. Pay attention to the compose UUID and version so you don't check the status of the wrong compose. +.. Make sure your compose finished successfully. Pay attention to the compose UUID and version so you don't check the status of the wrong compose. + [source,subs="verbatim,quotes,attributes"] -- @@ -233,7 +233,7 @@ Version: 9.2 <.> Commit ID of the new edge commit image <.> Parent commit of the new edge commit image <.> Previous commit, it was the HEAD at the beginning of this lab -<.> Parent commmit of the previous commit, it was the initial commit +<.> 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_. @@ -336,7 +336,7 @@ php-8.0.27-1.el9_1.x86_64 7. Still on your _development machine_, change configurations and application data on your _test VM_, so you can verify if those changes are retained by rolling back an update. -.. Change the timezone of your _test VM_. +.. Change the time zone of your _test VM_. + [source,subs="verbatim,quotes"] -- @@ -429,7 +429,7 @@ package php is not installed cockpit-286.1-1.el9.x86_64 -- -.. Check that your _test VM_ still contains the changes to timezone and the PHP script, which doesn't work anymore because there's no PHP engine on its Apache Web Server. +.. Check that your _test VM_ still contains the changes to the system time zone and the PHP script, which doesn't work anymore because there's no PHP engine on its Apache Web Server. + [source,subs="verbatim,quotes"] -- diff --git a/modules/ch4-update/pages/s4-deltas-lab.adoc b/modules/ch4-update/pages/s4-deltas-lab.adoc index c02579d..a1c35aa 100644 --- a/modules/ch4-update/pages/s4-deltas-lab.adoc +++ b/modules/ch4-update/pages/s4-deltas-lab.adoc @@ -1,4 +1,4 @@ -:time_estimate: 11 +:time_estimate: 14 :compose-uuid-mysql-v2-bbbbbbbbbbbb: e0722e00-9cd1-4d7f-96fc-83776eac85fc = Lab: Update Edge Devices Using Static Deltas @@ -31,7 +31,7 @@ You will perform some steps of this lab on your _development machine_ and some s it seems "user" doesn't work well with ostree (at least installer images) but a %post-install script does ] https://bugzilla.redhat.com/show_bug.cgi?id=1838859 -Got confirmation that the edge installer image ships with a different Anaconda setup which doesn't enable all options. While the RHEL installer is optimized for interactive instrallation, the edge installer is optmized for unattended installation. +Got confirmation that the edge installer image ships with a different Anaconda setup which doesn't enable all options. While the RHEL installer is optimized for interactive installation, the edge installer is optmised for unattended installation. https://redhat-internal.slack.com/archives/C022TDCV3FH/p1729527320272209?thread_ts=1729268869.980959&cid=C022TDCV3FH They claim users from blueprints should work and have root access (wheel group) but that failed in my tests @@ -380,7 +380,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. -.. Search the system logs on the _database VM_. You should see two entries with a message `libostree pull`: one from checking for updates, which referes 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. +.. 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. + [source,subs="verbatim,quotes"] -- @@ -400,7 +400,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 seach the system log of the _test VM_ from the previous labs, your would see entries similar to the folowing. +.. If you search the system log of the _test VM_ from the previous labs, your would see entries similar to the following. + [source,subs="verbatim,quotes"] -- @@ -471,4 +471,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 reminaing 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 434f65a..11e90d5 100644 --- a/modules/ch4-update/pages/s5-summary.adoc +++ b/modules/ch4-update/pages/s5-summary.adoc @@ -4,7 +4,7 @@ In this chapter, you learned: * No matter how you provision your edge devices, they need access to remote OSTree repositories to fetch system updates. -* Edge commit imagge used for system updates must be created with a reference to an existing OSTree repository and an OSTree branch with at least one commit. +* Edge commit images used for system updates must be created with a reference to an existing OSTree repository and an OSTree branch with at least one commit. * Devices provisioned using edge installer images are *NOT* configured with an OSTree remote, you must configure it before applying updates. @@ -14,4 +14,4 @@ In this chapter, you learned: * 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. -* Everyime you add commits or static deltas to an OSTree repository, you must update its summary file. +* Every time you add commits or static deltas to an OSTree repository, you must update its summary file.