80 lines
4.4 KiB
Markdown
80 lines
4.4 KiB
Markdown
# 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](https://ostreedev.github.io/ostree/introduction/) describes versioned filesystem trees and shared content; its [atomic upgrades explanation](https://ostreedev.github.io/ostree/atomic-upgrades/) 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](ADR-004-full-system-image-updates.md) provide a complete release using an image artifact.
|
|
- [Package-based updates](ADR-005-package-based-updates.md) support independent components on a versioned platform.
|
|
- [Binary delta delivery](ADR-008-binary-delta-delivery.md) 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](ADR-010-hybrid-update-strategies.md).
|