ota-reference-design/adr/ADR-006-container-based-updates.md

# ADR-006: Container-Based Updates

## Status

Accepted

## Context

An OTA architecture must define the unit of update.

One possible approach is to distribute software as a container that includes an application together with the user-space environment required to run it.

Unlike a package-based update, a container is treated as a self-contained delivery unit that may include the application, libraries, runtime components, configuration, and other dependencies.

In embedded Linux, container-based delivery is usually less common than in server environments and should be introduced only when it solves a clear architectural or organizational problem.

## Decision

Use container-based updates only when an application or subsystem must be delivered and maintained as an independent software product with minimal dependence on the target platform's user-space environment.

Do not use containerization as a substitute for a well-designed system architecture.

## Decision Drivers

Container-based updates are preferred when:

- the software subsystem is owned and maintained by a different organization;
- the supplier must support multiple compatible target platforms;
- the application must be delivered with its own user-space environment;
- changes to the host platform should have minimal impact on the delivered subsystem;
- the application or subsystem is maintained as an independent software product;
- the additional storage and runtime overhead are acceptable.

## Consequences

### Positive

- The application is delivered together with its required user-space environment.
- Dependence on the host system's user-space libraries is reduced.
- A supplier can maintain a single delivery for multiple compatible platforms.
- Independent subsystems can follow their own release lifecycle.
- Conflicts between library versions used by separate subsystems are less likely.
- The ownership boundary between the subsystem supplier and the device integrator becomes explicit.

### Negative

- The delivered artifact is larger.
- Libraries and supporting components may be duplicated across containers.
- A container update typically replaces the container as a whole.
- Diagnosing and maintaining third-party containers is more difficult.
- The device integrator loses visibility and control over part of the delivered software.
- The container may become a black box whose internal composition is controlled by the supplier.
- The integrator may not know which library versions, build options, patches, tools, or auxiliary processes are present.
- Internal defects often cannot be corrected without supplier involvement.
- The container runtime becomes an additional part of the maintained platform.

## Special Considerations

### Independent Supplier

Container-based delivery is most useful when a subsystem is supplied by a third party.

It allows the supplier to distribute an almost complete software environment without adapting it to every customer's user-space platform.

For the system integrator, this may simplify initial integration. It also reduces control over the subsystem's internal design and maintenance.

Delivery convenience does not remove operational responsibility. The integrator must still supervise startup, resource usage, logging, health, updates, and interaction with the rest of the device.

### Containers as Black Boxes

Bundling a complete user-space environment transfers part of the control from the integrator to the supplier.

Even when familiar libraries are included, the integrator may not be able to determine:

- how they were built;
- which patches were applied;
- which optional features were enabled;
- which additional dependencies were included;
- which background processes are started;
- what changed between container releases.

This complicates auditing, debugging, security review, and impact analysis.

The less transparent the container contents are, the more the integrator depends on the supplier's release process, documentation, and long-term support.

### Containerization Does Not Replace Architecture

If the entire software stack is developed and maintained by one organization, the benefits of containerization are often limited.

A well-designed package-based architecture can frequently provide similar lifecycle independence without introducing a separate user-space environment for each component.

Containerization does not correct:

- tightly coupled components;
- unstable interfaces;
- incorrect state management;
- poor service lifecycle design;
- inadequate observability;
- weak diagnostics.

Wrapping a poorly designed component in a container does not make it independent.

### Fault Isolation

Containers are often presented as a fault-tolerance mechanism.

In most embedded Linux systems, user-space processes are already isolated by the operating system. A correctly designed service can fail without terminating unrelated services and can be restarted by a supervisor, watchdog, or service manager.

Restarting a container therefore does not necessarily provide stronger fault isolation than restarting a process, and may consume more time and resources.

Containerization also does not protect against a shared kernel failure. A kernel panic remains fatal to both containerized and non-containerized user-space architectures.

Systems that isolate complete operating systems under a hypervisor or a safety-certified RTOS use a different architectural model and are outside the scope of this ADR.

### Different Library Versions

Containers can be useful when independent subsystems require incompatible versions of the same libraries.

However, this does not always require full containerization.

In many embedded Linux systems, a component can ship with private libraries in its own directory and load them independently from the platform-wide versions.

Different library requirements alone are therefore not sufficient justification for introducing containers.

## Limitations

Containerization does not eliminate software maintenance.

It transfers part of the responsibility for the user-space environment from the device developer to the container supplier.

If the supplier does not provide timely bug fixes, security updates, or new compatible releases, the integrator may have little practical ability to maintain the container internals independently.

Container updates and rollbacks may also replace the entire bundled user space even when only one internal component changed.

This approach therefore requires:

- a high level of trust in the supplier;
- a transparent release process;
- documented container contents;
- long-term maintenance commitments;
- clear diagnostic and update procedures.

## Applicability

This approach is well suited when:

- the subsystem is supplied and maintained by an independent organization;
- the supplier must minimize dependence on the customer's user-space platform;
- the application or subsystem is an independently maintained product;
- a clear responsibility boundary between supplier and integrator is required;
- additional storage, memory, and runtime overhead are acceptable;
- independent delivery is more valuable than full control over the implementation.

Another approach should be considered when:

- the complete software stack is developed by one organization;
- components can be delivered as independent packages;
- storage, memory, or OTA download size are critical;
- full control over all device software is required;
- simple component-level rollback is important;
- containers are used only as packaging for ordinary services;
- expected fault tolerance is already provided by Linux process isolation and supervisor mechanisms.

## Alternatives Considered

The following alternatives are described in separate ADRs:

- full-system image updates;
- package-based updates;
- versioned filesystem trees;
- hybrid update strategies.

## Summary

Containerization primarily solves organizational problems related to the delivery and maintenance of independently owned software subsystems.

When all software components are controlled by one engineering organization, a well-designed package-based architecture often provides the same practical benefits with significantly less system complexity.