docs: Performing-an-ABUpdate (#224)

bfjelds · Copilot · Britel · web-flow · commit 5c4dacb86249 · 2025-10-02T13:30:44.000-07:00
* update

* Update docs/Tutorials/Performing-an-ABUpdate.md

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* host-config-update.yaml

* fix up

* rename

* missed update paths

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Update step description from 'Get' to 'Build' Trident RPMs

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Brian Telfer &lt;britel@microsoft.com&gt;

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Brian Telfer &lt;britel@microsoft.com&gt;

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Brian Telfer &lt;britel@microsoft.com&gt;

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Brian Telfer &lt;britel@microsoft.com&gt;

* Update docs/Tutorials/Performing-an-AB-Update.md

Co-authored-by: Brian Telfer &lt;britel@microsoft.com&gt;

* align other docs

* align

* align

* Host Configuration

* Update docs/Tutorials/Building-AB-Update-Images-for-Install-and-Update.md

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* line length

* Revise headings for steps in AB update tutorial

Updated section headings to improve consistency and clarity.

* Update heading format in tutorial on COSI configuration

* Fix heading formatting for Update COSI Configuration

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: Brian Telfer &lt;britel@microsoft.com&gt;
diff --git a/docs/How-To-Guides/Configure-an-AB-Update-Ready-Host.md b/docs/How-To-Guides/Configure-an-AB-Update-Ready-Host.md
@@ -70,7 +70,7 @@ pair comprised of two RAID arrays, `root-a` and `root-b`, would have an ID
 
 ### Step 2: Add `abUpdate` configuration
 
-1. Add a `storage.abUpdate` configuration to the host configuration. The
+1. Add a `storage.abUpdate` configuration to the Host Configuration. The
    [`abUpdate`](../Reference/Host-Configuration/API-Reference/AbUpdate.md)
    configuration carries information about the [A/B volume
    pairs](../Reference/Glossary.md#ab-volume-pair) that are used to perform A/B
@@ -155,7 +155,7 @@ will:
 - Link each pair of device copies into a logical A/B volume pair.
 
 1. Run A/B updates with Trident by following [this
-   tutorial](../Tutorials/Performing-an-ABUpdate.md). On an A/B update, Trident
+   tutorial](../Tutorials/Performing-an-AB-Update.md). On an A/B update, Trident
    will:
 
    - Update the OS image on the inactive partitions, so that it becomes active
diff --git a/docs/How-To-Guides/Creating-Azure-Linux-Images-with-Image-Customizer.md b/docs/How-To-Guides/Creating-Azure-Linux-Images-with-Image-Customizer.md
@@ -29,7 +29,7 @@ oras pull mcr.microsoft.com/azurelinux/3.0/image/minimal-os:latest --platform li
 popd
 ```
 
-### Step 2: Get Trident RPMs
+### Step 2: Build Trident RPMs
 
 Build the Trident RPMs by running:
 
@@ -56,7 +56,7 @@ Copy RPMs to staging folder:
 cp -r bin/RPMS $HOME/staging
 ```
 
-### Step 3: Create Image Customizer Configuration
+### Step 3: Define COSI Configuration
 
 Follow the Image Customizer
 [documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html)
diff --git a/docs/How-To-Guides/Set-Up-Root-Verity.md b/docs/How-To-Guides/Set-Up-Root-Verity.md
@@ -40,7 +40,7 @@ oras pull mcr.microsoft.com/azurelinux/3.0/image/minimal-os:latest --platform li
 popd
 ```
 
-### Step 2: Get Trident RPMs
+### Step 2: Build Trident RPMs
 
 Build the Trident RPMs by running:
 
@@ -67,7 +67,7 @@ Copy RPMs to staging folder:
 cp -r bin/RPMS $HOME/staging
 ```
 
-### Step 3: Create Image Customizer Configuration
+### Step 3: Define COSI Configuration
 
 To create a root-verity volume, there are a few Image Customizer configuration
 sections that are important.
diff --git a/docs/How-To-Guides/Set-Up-Usr-Verity.md b/docs/How-To-Guides/Set-Up-Usr-Verity.md
@@ -32,7 +32,7 @@ oras pull mcr.microsoft.com/azurelinux/3.0/image/minimal-os:latest --platform li
 popd
 ```
 
-### Step 2: Get Trident RPMs
+### Step 2: Build Trident RPMs
 
 Build the Trident RPMs by running:
 
@@ -59,7 +59,7 @@ Copy RPMs to staging folder:
 cp -r bin/RPMS $HOME/staging
 ```
 
-### Step 3: Create Image Customizer Configuration
+### Step 3: Define COSI Configuration
 
 To create a usr-verity volume, there are a few Image Customizer configuration
 sections that are important.
diff --git a/docs/Reference/Host-Configuration/API-Reference/EncryptedVolume.md b/docs/Reference/Host-Configuration/API-Reference/EncryptedVolume.md
@@ -39,7 +39,7 @@ This parameter is required. It must be a valid file name and unique among all en
 
 The ID of the LUKS-encrypted volume to create.
 
-This parameter is required. It must be non-empty and unique among the IDs of all block devices in the host configuration. This includes the IDs of all disk partitions, encrypted volumes, software RAID arrays, and A/B volume pairs.
+This parameter is required. It must be non-empty and unique among the IDs of all block devices in the Host Configuration. This includes the IDs of all disk partitions, encrypted volumes, software RAID arrays, and A/B volume pairs.
 
 | Characteristic | Value             |
 | -------------- | ----------------- |
diff --git a/docs/Reference/Host-Configuration/API-Reference/SoftwareRaidArray.md b/docs/Reference/Host-Configuration/API-Reference/SoftwareRaidArray.md
@@ -4,9 +4,9 @@
 
 Software RAID configuration.
 
-The RAID array will be created using the `mdadm` package. During a clean install, all the existing RAID arrays that are on disks defined in the host configuration will be unmounted, and then stopped.
+The RAID array will be created using the `mdadm` package. During a clean install, all the existing RAID arrays that are on disks defined in the Host Configuration will be unmounted, and then stopped.
 
-The RAID arrays that are defined in the host configuration will be created, and mounted if requested in the `storage.filesystems` config.
+The RAID arrays that are defined in the Host Configuration will be created, and mounted if requested in the `storage.filesystems` config.
 
 To learn more about RAID, please refer to the [RAID wiki](https://wiki.archlinux.org/title/RAID).
 
@@ -39,7 +39,7 @@ See the reference links for picking the right number of devices. Devices are par
 
 A unique identifier for the RAID array.
 
-This is a user-defined string that links the RAID array to the `filesystems` config in the configuration. The identifier must be unique across devices of all types in the host configuration.
+This is a user-defined string that links the RAID array to the `filesystems` config in the configuration. The identifier must be unique across devices of all types in the Host Configuration.
 
 | Characteristic | Value             |
 | -------------- | ----------------- |
diff --git a/docs/Trident/How-Do-I-Interact-With-Trident.md b/docs/Trident/How-Do-I-Interact-With-Trident.md
@@ -21,7 +21,7 @@ installation and servicing operations. The CLI supports the following commands:
 - [`offline-initialize`](Tutorials/Onboard-a-VM-to-Trident.md): Prepares the
   Trident datastore for a VM image, enabling future in-place servicing. This is
   typically performed during VM image creation.
-- [`update`](Tutorials/Performing-an-ABUpdate.md): Executes an OS update in
+- [`update`](Tutorials/Performing-an-AB-Update.md): Executes an OS update in
   accordance with the supplied Host Configuration.
 - `commit`: Certifies the current OS deployment as successful.
 - [`rebuild-raid`](How-To-Guides/Rebuild-RAID-Array.md): Reconstructs a degraded
diff --git a/docs/Trident/Trident.md b/docs/Trident/Trident.md
@@ -88,7 +88,7 @@ Trident](Tutorials/Onboard-a-VM-to-Trident.md) tutorial.
 #### Do you want to update a bare-metal host or a virtual machine?
 
 You can start with the [Performing an A/B
-update](Tutorials/Performing-an-ABUpdate.md) tutorial.
+update](Tutorials/Performing-an-AB-Update.md) tutorial.
 
 <!-- #### Do you want to orchestrate Trident servicing operations across your fleet?
 
diff --git a/docs/Tutorials/Building-AB-Update-Images-for-Install-and-Update.md b/docs/Tutorials/Building-AB-Update-Images-for-Install-and-Update.md
@@ -15,7 +15,7 @@ both install and update.
 2. Ensure [Image Customizer
    container](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/quick-start/quick-start.html)
    is accessible.
-3. Ensure SSH Key Pair Exists (assumed in this tutorial to be
+3. Ensure SSH key pair exists (assumed in this tutorial to be
    `$HOME/.ssh/id_rsa.pub`)
 
 ## Instructions
@@ -32,7 +32,7 @@ oras pull mcr.microsoft.com/azurelinux/3.0/image/minimal-os:latest --platform li
 popd
 ```
 
-### Step 2: Get Trident RPMs
+### Step 2: Build Trident RPMs
 
 Build the Trident RPMs by running:
 
@@ -59,7 +59,7 @@ Copy RPMs to staging folder:
 cp -r bin/RPMS $HOME/staging
 ```
 
-### Step 3: Create Image Customizer Configuration for Install
+### Step 3: Define Install COSI Configuration
 
 Follow the Image Customizer
 [documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html)
@@ -117,11 +117,10 @@ be defined like this:
 ```
 
 In addition to partition and filesystem definition, Trident must be added to the
-image. As the final step in install, [trident
-commit](../Reference/Trident-CLI.md#commit) must be invoked to validate and
-ensure the machine's boot order is correct. To enable commit, Trident needs the
-`trident-service` package to be installed and the `trident` service to be
-enabled:
+image. The final step for install is [trident commit](../Reference/Trident-CLI.md#commit).
+This will validate and ensure the machine's boot order is correct. To enable
+`trident commit` in the install image, the `trident-service` package must be
+installed and the `trident` service needs to be enabled:
 
 ``` yaml
   packages:
@@ -206,7 +205,7 @@ os:
 EOF
 ```
 
-### Step 4: Invoke Image Customizer to Create an Install COSI File
+### Step 4: Create an Install COSI
 
 From previous steps, the Trident RPMs, a base image (`image.vhdx`) and Image
 Customizer configuration file (`ic-config-install.yaml`) are all found in
@@ -336,7 +335,7 @@ os:
 EOF
 ```
 
-### Step 6: Create Servicing ISO and Install the A OS
+### Step 6: Create Servicing ISO and Install OS on Target Machine
 
 To install the COSI we created in step 4, we need to create a servicing ISO.
 Follow the [Building a Servicing ISO tutorial](./Building-a-Servicing-ISO.md),
@@ -350,16 +349,21 @@ operating system.
 Alternatively, to simulate an installation, you can create a virtual machine
 with an empty disk and mount the ISO directly as a CD.
 
-### Step 7: Create Image Customizer Configuration for Update
+### Step 7: Define Update COSI Configuration
 
 The process for creating an update COSI file is similar to what we did for
 Install.
 
-For an update COSI, we only need to provide an esp and the updated partitions.
+For an update COSI, we need to provide only an esp and the updated partitions.
+The `trident` partition does not have an [A/B volume pair](../Reference/Glossary.md#ab-volume-pair)
+and does not need to be serviced, so it is not included. The same would go for
+any data or other non-serviced partition.
 
-> Note that `root` is specified for Image Customizer unlike the `root-a` or
-> `root-b` found in the Trident Host Configuration. Also that there is no
-> `trident` partition.
+Image Customizer reflects the update OS image, which will be laid out onto a
+single partition at a time: either A _or_ B. So, the
+[A/B volume pairs](../Reference/Glossary.md#ab-volume-pair) will not be reflected
+in the Image Customizer config.  This is why `root` is specified here unlike the
+`root-a` or `root-b` found in the Trident Host Configuration.
 
 ``` yaml
   disks:
@@ -387,11 +391,10 @@ filesystems:
       type: ext4
 ```
 
-As for the install COSI, Trident must be added. The final step for update is
-[trident commit](../Reference/Trident-CLI.md#commit), which must be invoked to
-validate and ensure the machine's boot order is correct. To enable commit,
-Trident needs the `trident-service` package to be installed and the `trident`
-service to be enabled:
+The final step for A/B Update is [trident commit](../Reference/Trident-CLI.md#commit).
+This will validate and ensure the machine's boot order is correct after an
+update. To enable `trident commit` in the update image, the `trident-service`
+package must be installed and the `trident` service needs to be enabled:
 
 ``` yaml
   packages:
@@ -465,7 +468,7 @@ os:
 EOF
 ```
 
-### Step 8: Invoke Image Customizer to Create an Update COSI File
+### Step 8: Create an Update COSI
 
 From previous steps, the Trident RPMs, a base image (`image.vhdx`) and Image
 Customizer configuration file (`ic-config-update.yaml`) are all found in
@@ -505,7 +508,7 @@ cp $HOME/staging/host-config.yaml $HOME/staging/host-config-update.yaml
 sed -i 's|url: /images/azure-linux.cosi|url: /tmp/osimage-update.cosi|' $HOME/staging/host-config-update.yaml
 ```
 
-### Step 10: Copy COSI and Host Configuration to OS
+### Step 10: Copy COSI and Host Configuration to the Servicing OS
 
 While Trident can download COSI files from an OCI or http server, in this
 tutorial, we will just copy the COSI to a known location. This is based on
@@ -520,7 +523,7 @@ scp -i $HOME/.ssh/id_rsa $HOME/staging/host-config-update.yaml tutorial-user@$TA
 scp -i $HOME/.ssh/id_rsa $HOME/staging/osimage-update.cosi tutorial-user@$TARGET_MACHINE_IP:/tmp/osimage-update.cosi
 ```
 
-### Step 11: Update Target Machine to B OS
+### Step 11: Update OS on the Target Machine to B
 
 To update the target machine, we will invoke [`trident
 update`](../Reference/Trident-CLI.md#update).
diff --git a/docs/Tutorials/Building-a-Servicing-ISO.md b/docs/Tutorials/Building-a-Servicing-ISO.md
@@ -35,7 +35,7 @@ oras pull mcr.microsoft.com/azurelinux/3.0/image/minimal-os:latest --platform li
 popd
 ```
 
-### Step 2: Get Trident RPMs
+### Step 2: Build Trident RPMs
 
 Build the Trident RPMs by running:
 
@@ -133,7 +133,7 @@ iso:
       destination: /images/azure-linux.cosi
 ```
 
-### Step 4: Invoke Image Customizer to Create Installation ISO
+### Step 4: Create Installation ISO
 
 Assuming locations for the base image file (`$HOME/staging/image.vhdx`) and the
 Image Customizer configuration file (`$HOME/staging/ic-config.yaml`), follow the
diff --git a/docs/Tutorials/Onboard-a-VM-to-Trident.md b/docs/Tutorials/Onboard-a-VM-to-Trident.md
@@ -31,7 +31,7 @@ oras pull mcr.microsoft.com/azurelinux/3.0/image/minimal-os:latest --platform li
 popd
 ```
 
-### Step 2: Get Trident RPMs
+### Step 2: Build Trident RPMs
 
 Build the Trident RPMs by running:
 
@@ -58,7 +58,7 @@ Copy RPMs to staging folder:
 cp -r bin/RPMS $HOME/staging
 ```
 
-### Step 3: Create Image Customizer configuration including offline-initialize
+### Step 3: Define COSI Configuration including offline-initialize
 
 Add the `trident-service` package to the Image Customizer configuration. This
 will add the Trident services needed for update and the `trident` package used
diff --git a/docs/Tutorials/Performing-an-AB-Update.md b/docs/Tutorials/Performing-an-AB-Update.md
diff --git a/docs/Tutorials/Performing-an-ABUpdate.md b/docs/Tutorials/Performing-an-ABUpdate.md
diff --git a/docs/Tutorials/Trident-Hello-World.md b/docs/Tutorials/Trident-Hello-World.md
diff --git a/docs/Tutorials/Writing-a-Simple-Host-Configuration.md b/docs/Tutorials/Writing-a-Simple-Host-Configuration.md
