ADR-009: Versioned Filesystem Trees

Context

A software platform can be released as a complete set of files and directories without representing every release as a separate block image.

This educational example considers a system that prepares versioned software trees, selects a prepared tree for activation, and reuses unchanged content between versions. The managed software is kept separate from mutable application data.

The purpose is to retain a known software release while avoiding unnecessary duplication of identical content.

Decision

Use versioned filesystem trees when complete software deployments and content reuse are valuable enough to justify a dedicated storage and deployment model.

Prepare the new deployment separately, retain a previous usable deployment, and activate the prepared version as a unit. Define which files belong to that version and which data is maintained outside it.

Decision Drivers

The managed software should correspond to a complete validated release.
Releases share substantial unchanged content.
The platform can support preparing and selecting separate deployments.
The team can maintain the required build, storage, and boot integration.
Mutable data can be separated from the versioned software.

Consequences

Positive

A deployment identifies a complete managed software version.
The running software need not be changed file by file during preparation.
Unchanged content can be reused between releases.
A retained deployment provides a software version to return to.

Negative

Storage management is more involved than writing a standalone image.
Build and deployment tooling must understand the tree model.
Old deployments and unused content require cleanup.
Boot integration and application-data compatibility still need attention.

Special Considerations

A Tree Is a Complete Software State

The build process determines the files in a release. Reusing a file from an older release does not make the new deployment an arbitrary mixture: it still has a defined target state.

An implementation may identify stored objects by hashes of their contents. Identical objects can then be shared instead of stored as separate copies for every release.

Atomic Activation Has a Boundary

Here, atomic activation means selecting a prepared software deployment as a unit. It does not mean every file and external component on the device changes in one transaction.

For example, selecting an older tree does not automatically restore a database maintained outside that tree. A complete update process still needs to determine whether the new software works and whether returning to the retained version is appropriate.

Retention and Cleanup

Content reuse does not eliminate storage requirements. Space is still needed for new content and the versions retained for recovery.

Cleanup must preserve both the deployments that remain in use and the content needed by the retained recovery version.

An Implementation to Explore

OSTree is an example of this model. Its overview describes versioned filesystem trees and shared content; its atomic upgrades explanation describes preparing and switching deployments.

These are useful next readings, rather than a requirement to choose OSTree. Snapshot-based systems may offer related behavior through different storage mechanisms and should be evaluated on their own terms.

Applicability

This approach fits a platform intentionally organized around versioned software deployments, where content reuse provides useful savings and the team can maintain the supporting tooling.

Prefer a simpler image model when its storage and delivery costs are acceptable. Prefer independently released components when the main requirement is separate application lifecycles rather than a complete platform deployment.

Alternatives Considered

Full-system image updates provide a complete release using an image artifact.
Package-based updates support independent components on a versioned platform.
Binary delta delivery can reduce image transfer size without adopting a tree-based deployment model.

A filesystem tree can also serve as the platform layer in a hybrid strategy.

4.4 KiB Raw Blame History