microsoft · bfjelds · May 22, 2026 · May 22, 2026 · May 22, 2026 · May 22, 2026
@@ -18,9 +18,13 @@ Trident's dependencies.
 - Ubuntu/Debian:
 
   ```bash
-  sudo apt install build-essential pkg-config libssl-dev libclang-dev protobuf-compiler
+  sudo apt install build-essential pkg-config libssl-dev libclang-dev protobuf-compiler ca-certificates unzip
   ```
 
+  For RPM builds (run inside the Azure Linux build container, not on the
+  Ubuntu host), additional packages are needed: `rpmdevtools`, `sed`,
+  `perl`, and `selinux-policy-devel`.
+
 - Docker (follow the instructions at [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/))
 
 ## Test Dependencies

@@ -4,7 +4,7 @@ sidebar_position: 5
 
 # Functional Tests
 
-Functional testing is a `pytest` test suite (rooted in `functional_tests/`) for
+Functional testing is a `pytest` test suite (rooted in `tests/functional_tests/`) for
 tests that are meant to be run in an isolated environment. Functional testing is
 comprised of:
 
@@ -27,11 +27,10 @@ how they are implemented.
 ## Native Python Tests
 
 Native Python tests are pytest tests that are written in Python. They live in
-python files in the `functional_tests/custom` directory.
+python files in the `tests/functional_tests/custom` directory.
 
 Generally, these leverage the `vm` fixture, which is an Azure Linux VM that has been
-created using `virt-deploy` and `netlaunch`. The `vm` fixture is defined in
-`conftest.py`.
+created using `virt-deploy`. The `vm` fixture is defined in `conftest.py`.
 
 ## Rust-Based Tests
 
@@ -60,6 +59,8 @@ inventory::submit!{pytest::TestCaseMetadata {
     module: module_path!(),
     function: #function,
     negative: #negative,
+    xfail: #xfail,
+    skip: #skip,
     feature: #feature,
     type_: #test_type,
 }}
@@ -87,6 +88,8 @@ inventory::submit!{pytest::TestCaseMetadata {
     module: module_path!(), // This will be `crate::module1::moduleN::functional_test`
     function: "test_case",
     negative: false,
+    xfail: None,
+    skip: None,
     feature: "",
     type_: "",
 }}
@@ -125,7 +128,7 @@ exist within the test binaries.
 
 The `pytest` crate collects all the test cases, and builds a tree representing
 rust's modules, and all the test cases within them. This tree is then serialized
-into a JSON file called `ft.json`, and placed in the `functional_tests/`
+into a JSON file called `ft.json`, and placed in the `tests/functional_tests/`
 directory.
 
 The underlying structure of the JSON file is:

@@ -6,8 +6,9 @@ sidebar_position: 3
 
 ## Code Checks
 
-To ensure code quality and consistency, we use Rust's `clippy` linting tool. You
-can run it with the following command:
+To ensure code quality and consistency, run `make check`. This verifies
+formatting (`cargo fmt --check`), runs `cargo check` with all features, and
+then runs `clippy` with `-D warnings`:
 
 ```bash
 make check
@@ -44,8 +45,8 @@ The tests themselves are located in the Rust code under `cfg`
 attributes:
 
 ```rust
-#[cfg(feature = "functional-tests")]
-mod functional_tests {
+#[cfg(feature = "functional-test")]
+mod functional_test {
     // ...
 }
 ```

@@ -51,7 +51,7 @@ for more detailed guidelines on how to use the background log file.
 
 For each command that can be run with Trident, the customer can adjust the log
 level, i.e. the verbosity level, to one of the following six values: `OFF`,
-`ERROR`, the **default** `WARN`, `INFO`, `DEBUG`, and `TRACE`.
+`ERROR`, `WARN`, `INFO`, the **default** `DEBUG`, and `TRACE`.
 
 The last five correspond to the actual functions in the `log` crate that the
 developers can use to write logs in Trident:
@@ -197,15 +197,16 @@ and should probably address, we issue a non-fatal error with an `ERROR` log.
 
 *Example 1.*
 
-The code snippet below refers to a scenario where the customer is requesting to
-ignore the hash of an image in the Host Configuration. Before deploying the
-image onto the block device, Trident produces a `WARN` log because streaming an
-unverified payload onto a block device is a potential security concern.
+The illustrative code snippet below refers to a scenario where the customer is
+requesting to ignore the hash of an image in the Host Configuration. Before
+deploying the image onto the block device, Trident should produce a `WARN` log
+because streaming an unverified payload onto a block device is a potential
+security concern.
 
 ```rust
-match image.sha256 {
-    ImageSha256::Ignored => {
-        warn!("Ignoring SHA256 for image from '{}'", image_url);
+match image.sha384 {
+    ImageSha384::Ignored => {
+        warn!("Ignoring SHA384 for image from '{}'", image_url);
     }
     ...
 }
@@ -316,7 +317,7 @@ is optional since Trident logging the next step is a confrmation in itself.)
 
 *Example 1.*
 
-The snippet below comes from the logic in `osutils/src/grub_mkconfig.rs` where
+The snippet below comes from the logic in `crates/osutils/src/grub_mkconfig.rs` where
 a new grub-mkconfig script is being written on the host. Here, we're using a
 `DEBUG` log to report the path at which the script is being written, since it's
 too low-level to be relevant to the overwhelming majority of the customers. At

@@ -36,7 +36,6 @@ When making a PR you are attempting to merge, make sure that:
 - Unit tests pass. (`make test`) (See: [Testing](../Building/Testing.md))
 - Functional tests pass. (`make functional-test`)
 - Local make targets work.
-  - `make rpm`
   - `make docker-build`
 - Coverage is above the baseline. (See: [Coverage](../Building/Coverage.md))
 

@@ -40,6 +40,16 @@ potential errors that might occur on a host and/or in Trident:
     system misconfiguration. E.g. `DatastoreError` is within this category
     since loading or writing to a datastore might fail for a variety of reasons.
 
+6. `HealthChecks` identifies errors that occur during health check
+    evaluation after a servicing operation completes. E.g. when a configured
+    health check fails after an update, indicating the deployment may need
+    to be rolled back.
+
+7. `UnsupportedConfiguration` identifies errors that occur when the
+    requested configuration is valid but not yet supported by Trident. E.g.
+    when a Host Configuration requests a feature combination that has not
+    been implemented.
+
 ## Adding a new error type
 
 1. When adding a new error type, e.g. when implementing new functionality or

@@ -9,7 +9,7 @@ For Runtime updates, an update modifies OS components like sysexts and confexts
 ## API to Support Rollback
 
 * `trident rollback` is provided to rollback the last update (note that this could be either a Runtime update or an A/B update)
-* `trident rollback -ab` can be used to rollback the last A/B update and boot into the inactive OS
+* `trident rollback --ab` can be used to rollback the last A/B update and boot into the inactive OS
 * `trident rollback --runtime` can be used to only rollback the last update if it was a runtime update
 * `trident rollback --check` can be used to determine what rollback will be invoked (output will be one of: `ab`, `runtime`, or `none`)
 * `trident get rollback-chain` can be used to see a yaml list of Host Statuses that can be rolled back to

@@ -47,7 +47,8 @@ sysexts contain files in `/opt`).
 
 ### SELinux
 
-Servicing of sysexts is not currently compatible with SELinux in systemd 255, as
-mounting the sysext overlays will result in `/usr` and `/opt` being mislabeled.
-Therefore, [SELinux](../Reference/Host-Configuration/API-Reference/Selinux.md)
-should be configured to `disabled` in the Host Configuration.
+Servicing of sysexts and confexts is not currently compatible with SELinux in
+systemd 255, as mounting the extension overlays will result in `/usr` and `/opt`
+(for sysexts) or `/etc` (for confexts) being mislabeled. Therefore,
+[SELinux](../Reference/Host-Configuration/API-Reference/Selinux.md) should be
+configured to `disabled` in the Host Configuration when using extensions.
@@ -47,6 +47,8 @@ flowchart LR
     Client["gRPC Client"] -- Unix Socket --> Server["Trident Daemon\n(tridentd)"]
     Server --> Version["VersionService"]
     Server --> Streaming["StreamingService"]
+    Server --> Update["UpdateService"]
+    Server --> Commit["CommitService"]
 :::
 
 ### Unix Domain Socket
@@ -120,6 +122,31 @@ service StreamingService {
 }
 ```
 
+### UpdateService
+
+Performs an A/B update on a Trident-managed system. The service supports running
+the full update, or executing the stage and finalize phases independently for
+two-step servicing workflows.
+
+```protobuf
+service UpdateService {
+  rpc Update(UpdateRequest) returns (stream ServicingResponse);
+  rpc UpdateStage(StageUpdateRequest) returns (stream ServicingResponse);
+  rpc UpdateFinalize(FinalizeUpdateRequest) returns (stream ServicingResponse);
+}
+```
+
+### CommitService
+
+Certifies the current OS deployment as successful and updates the boot order
+accordingly. This is the gRPC equivalent of `trident commit`.
+
+```protobuf
+service CommitService {
+  rpc Commit(CommitRequest) returns (stream ServicingResponse);
+}
+```
+
 ## Streaming Responses
 
 All servicing operations return a stream of `ServicingResponse` messages. This

@@ -11,21 +11,22 @@ Legend:
 - 🔜: Planned feature. Not implemented yet.
 - ⚠️: Refer to relevant notes for details.
 - ❌: Not supported.
+- ➖: Not applicable.
 
 ## Servicing Features
 
 | Category        | Feature                                 | Install | VM-Init | Update | Stream Disk |
 | --------------- | --------------------------------------- | ------- | ------- | ------ | ----------- |
 | 🚀 Runtime       | Native binary                           | ✅       | ✅       | ✅      | ✅           |
 | 🚀 Runtime       | Containerized                           | ✅       | ❌       | ✅      | ✅           |
-| 🚀 Runtime       | gRPC API                                | 🔜       | ❌       | 🔜      | ✅           |
+| 🚀 Runtime       | gRPC API                                | 🔜       | ❌       | ✅      | ✅           |
 | ⚙️ Bootloader    | UEFI [1]                                | ✅       | ✅       | ✅      | ✅           |
 | ⚙️ Bootloader    | GPT partitioning                        | ✅       | ✅       | ✅      | ✅           |
 | ⚙️ Bootloader    | Grub2                                   | ✅       | ✅       | ✅      | ✅           |
 | ⚙️ Bootloader    | Systemd-boot                            | ☑️       | ☑️       | ☑️      | ✅           |
 | 🔄 Lifecycle     | Onboard system for updates              | ✅       | ✅       | ✅      | ❌           |
-| 🔄 Lifecycle     | Rollback (grub)                         | ✅       | ✅       | ✅      | ❌           |
-| 🔄 Lifecycle     | Rollback (systemd-boot/UKI)             | 🔜       | 🔜       | 🔜      | ❌           |
+| 🔄 Lifecycle     | Rollback (grub)                         | ➖       | ✅       | ✅      | ❌           |
+| 🔄 Lifecycle     | Rollback (systemd-boot/UKI)             | ➖       | ☑️       | ☑️      | ❌           |
 | 🔏 Integrity     | Secure Boot                             | ✅       | ✅       | ✅      | ✅           |
 | 🔏 Integrity     | UKI                                     | ☑️       | ☑️       | ☑️      | ✅           |
 | 🔏 Integrity     | Root-verity (grub)                      | ⚠️[2]    | ⚠️[2]    | ⚠️[2]   | ✅           |
@@ -34,6 +35,7 @@ Legend:
 | 💽 Storage       | Block device creation                   | ✅       | 🔜       | ❌      | ✅           |
 | 💽 Storage       | Image streaming (local)                 | ✅       | 🔜       | ✅      | ✅           |
 | 💽 Storage       | Image streaming (HTTPS)                 | ✅       | 🔜       | ✅      | ✅           |
+| 💽 Storage       | Image streaming (OCI registry)          | ✅       | 🔜       | ✅      | ✅           |
 | 💽 Storage       | Multiboot                               | ☑️       | ❌       | ✅[3]   | ❌           |
 | 💽 Storage       | Partition adoption                      | ☑️       | ❌       | ✅[3]   | ❌           |
 | 💽 Storage       | Software RAID                           | ✅       | ❌       | ✅[3]   | ❌           |
@@ -46,6 +48,7 @@ Legend:
 | 📝 OS Config     | SSH configuration                       | ✅[5]    | ❌       | ✅[5]   | ❌           |
 | 📝 OS Config     | Initrd regeneration (grub)              | ✅       | ❌       | ✅      | ❌           |
 | 📝 OS Config     | Initrd regeneration (UKI)               | ❌       | ❌       | ❌      | ❌           |
+| 📦 Extensions    | Sysexts and confexts                    | ✅       | ❌       | ✅      | ❌           |
 | 🛡️ Security      | SELinux Configuration                   | ✅       | ❌       | ✅      | ❌           |
 | 🪛 Customization | User provided-scripts                   | ✅       | ❌       | ✅      | 🔜           |
 | 🛠️ Development   | Offline validation                      | ✅       | 🔜       | 🔜      | ❌           |

@@ -7,12 +7,19 @@ sidebar_position: 6
 Trident is under active development, with several enhancements planned for
 future releases. Key areas of focus include:
 
-- Support for servicing systemd System Extensions (sysexts). See
-  [Sysexts](../Explanation/Sysexts.md). ✅
+- Support for servicing systemd System Extensions (sysexts) and Configuration
+  Extensions (confexts). See [Sysexts](../Explanation/Sysexts.md) and
+  [Confexts](../Explanation/Confexts.md). ✅
 - User-initiated rollback capabilities. See
   [Manual Rollback](../Explanation/Manual-Rollback.md). ✅
 - Introduction of a gRPC API for improved integration. See
   [gRPC Server](../Explanation/gRPC-Server.md). ✅
+- Runtime updates for sysexts, confexts, and network configuration without
+  reboot. See [Runtime Updates](../Explanation/Runtime-Updates.md). ✅
+- Disk streaming for fast provisioning directly from COSI images. See
+  [Disk Streaming](../Explanation/Disk-Streaming.md). ✅
+- Image streaming from OCI registries. See
+  [Image Streaming Pipeline](../Explanation/Image-Streaming-Pipeline.md). ✅
 - Enhanced SELinux policy management and updates.
 - Implementation of a Host Report API to provide detailed hardware and software
   inventory.

@@ -35,6 +35,8 @@ installation and servicing operations. The CLI supports the following commands:
 - [`diagnose`](How-To-Guides/Generate-Diagnostics-Bundle.md): Generates a
   diagnostics bundle containing system information, logs, and configuration data
   for troubleshooting and support purposes.
+- [`rollback`](../Explanation/Manual-Rollback.md): Triggers a manual rollback to
+  a previous OS state. Supports both A/B rollback and runtime rollback.
 
 Please consult [CLI reference](Reference/Trident-CLI.md) for detailed
 information on each command and its usage.

@@ -47,9 +47,12 @@ servicing.
   accounts](How-To-Guides/Configure-Users.md), SSH, and SELinux policies.
 - [Execution of user-provided scripts](Tutorials/Running-Custom-Scripts.md) for
   custom OS image modifications.
-- Reliable rollback to the previous OS version in case of servicing issues.
 - Unified Kernel Image (UKI) support (preview).
 
+**Servicing Features:**
+
+- Reliable rollback to the previous OS version in case of servicing issues.
+
 Trident supports servicing both bare-metal hosts and virtual machines.
 
 Trident runs on both `x86_64` and `aarch64` architectures.