RAUC Adaptive Updates: Qualify Block Reuse Without Assuming Every Bundle Is a Delta
RAUC adaptive updates can reuse matching local blocks while retaining the complete image in the bundle. Qualify this as an optional transfer optimization, including the cost of building missing indexes and the possibility of a full-copy fallback. It is not a delta that can only reconstruct one specific predecessor image.
This guide is pinned to RAUC 1.13 documentation and v1.13 source, using block-device image slots with HTTP streaming. It does not qualify tar-archive installation, casync chunk stores or a server’s range behavior. No RAUC installation or performance measurement was executed.
1. Confirm the mechanism is eligible
The 1.13 adaptive-update guide describes block-hash-index, enabled per image together with a configured shared data directory. The bundle contains the full image and its index. The documented mode requires random access to block devices and does not support tar archives.
Record the exact bundle format, manifest settings, slot classes, target storage type and data-directory configuration. Keep ordinary bundle trust, compatibility and boot recovery as prerequisites. An optimization setting must not weaken those gates.
Use the actual production image layout for qualification. A small synthetic image can prove a lookup decision, but it cannot establish how a compressed bundle, large filesystem or slow storage behaves in the product.
2. Understand what a local match proves
The documented algorithm considers existing active and target-slot data. Missing slot indexes are generated on demand. A candidate local match is checked against bytes read from the slot; unavailable matching data is obtained from the bundle image. See the block-based method description.
The pinned hash-index implementation distinguishes a hash listed in an index from a verified data read. For ordinary indexed slot data, a changed block fails the read-time hash comparison. A stale index therefore must not be treated as proof that the current local bytes are reusable.
Do not require local blocks to be at the same offset as the desired output block. The purpose of the index is to locate content by hash. Also distinguish reuse from skipping a target write: fewer network bytes do not automatically mean proportionally fewer storage writes.
3. Include index preparation in the budget
The pinned implementation uses a 32-byte SHA-256 entry for each 4,096-byte block. An illustrative, aligned 8 MiB image therefore has 2,048 block hashes, totaling 65,536 bytes before considering other files or runtime structures. This arithmetic is an index-payload estimate, not a measured RAM requirement.
A first adaptive installation may need to read and hash local slots to prepare their indexes. A later run with usable indexes can have different startup cost. Record these populations separately rather than averaging them into one installation time.
| Index condition | Qualification focus | Interpretation |
|---|---|---|
| Usable indexes already retained. | Lookup, verified reads and storage overhead. | Steady-state optimization case. |
| No local index. | Initial scan time, read volume and CPU load. | Index creation is part of this installation’s cost. |
| Index describes changed local bytes. | Read-time mismatch and alternative source selection. | A listed hash is only a candidate match. |
| Index access or adaptive setup fails. | Actual fallback path and resource budget. | Final success need not mean adaptive reuse succeeded. |
Include free space and persistence policy for the shared data directory. A configuration that loses indexes during every normal reboot can repeatedly pay preparation cost even if each individual installation succeeds.
4. Test full-copy fallback deliberately
In v1.13 write_image_to_dev(), missing data-directory configuration bypasses adaptive copying. A failed adaptive attempt is logged and the path proceeds to a full raw-image copy. That subsequent copy can itself fail.
Consequently, an overall successful install does not prove the requested adaptive method was used. Capture the selected method, preparation results, fallback warning and final outcome. Do not suppress a fallback warning merely because the device eventually boots.
Reserve enough approved network, time and power budget for the path the implementation can actually take. If the product cannot tolerate a full transfer, solve that admission-policy requirement explicitly; do not assume a manifest’s adaptive setting guarantees reduced traffic.
A full-copy fallback is also different from a new campaign retry. It occurs within this installation path. Preserve the actual sequence when interpreting transfer totals and repeated destination work.
5. Use block-content fixtures with known alternatives
Create disposable test images containing distinguishable blocks and a known expected final image. Keep the bundle identical while changing only the availability of local data and indexes. Never alter the active production filesystem to manufacture a mismatch.
| Controlled case | Expected evidence |
|---|---|
| Required block exists in a local slot. | Verified local source can supply those exact bytes. |
| Required block moved to another local offset. | Content lookup, rather than offset equality, is exercised. |
| Index claims a match but that block was changed. | The changed bytes are not accepted as the required block. |
| Block is absent from local sources. | Bundle supplies it while the final image remains correct. |
| Indexes are absent. | Preparation activity is visible and included in total cost. |
| Adaptive setup fails in a controlled fixture. | Fallback is reported and budgeted; no false adaptive-success claim. |
After each case, verify the installed image through the product’s approved validation path. Keep zero-filled blocks and data reused from already-written target regions identifiable when analyzing source statistics; they can complicate a simplistic “local versus network” count.
6. Measure the right outcomes
Compare actual transferred bytes, installation duration, CPU utilization, local reads, destination work, peak memory and product responsiveness. State whether the network count includes metadata, retries and protocol overhead. Preserve the first-install and retained-index results separately.
Do not equate the fraction of changed image blocks with the fraction of compressed bundle bytes transferred. Compression layout, request granularity, caches and repeated reads can change that relationship. Measure the deployed distribution path instead of promising a fixed reduction.
For a hypothetical release that changes one package, the team might expect substantial reuse. Its first-run result can still be dominated by index preparation or a fallback caused by missing configuration. The useful diagnosis is the method trace and resource accounting, not an optimistic claim that every small software change yields a small download.
Release adaptive mode only when both the reuse cases and the full-copy path fit the product’s acceptance envelope. Preserve exact source versions, image fixtures, index state and final validation evidence so a later performance regression can be attributed to the right stage.
