Storage and Quotas

Introduction

This page documents the storage and quota configuration options available in AosCore. Storage configuration controls where components store images, service state, and working data. Quota configuration determines how much disk space each service instance may consume and how the system reclaims space when capacity is constrained.

AosCore manages storage at two levels:

1. Component-level storage — local configuration in CM and SM config files that defines filesystem paths, partition limits, and item lifecycle policies
2. Service-level quotas — per-service limits defined in the service manifest (item configuration) and modulated by cloud-managed resource ratios in the Unit configuration

CM Storage Configuration

The Communication Manager configuration file (aos_communicationmanager.json) contains several storage-related fields.

Working and Data Directories

Field	Type	Default	Description
workingDir	string	— (required)	Base directory for all CM working data. Other paths derive from this if not explicitly set.
storageDir	string	{workingDir}/storages	Directory where service instance persistent storage is mounted. Each instance gets a subdirectory.
stateDir	string	{workingDir}/states	Directory where service instance state data is stored. Each instance gets a subdirectory.

The storageDir and stateDir paths define where the CM creates per-instance storage and state directories. These directories are provisioned when a service instance is launched and may be on the same or different filesystem partitions.

Image Manager Storage

The imageManager section within the CM configuration controls Deployment Bundle image storage:

{
  "imageManager": {
    "installPath": "/var/aos/cm/install",
    "downloadPath": "/var/aos/cm/download",
    "updateItemTtl": "30d",
    "removeOutdatedPeriod": "24h"
  }
}

Field	Type	Default	Description
installPath	string	{workingDir}/install	Directory for permanently installed Deployment Bundle images. Managed by the install Space Allocator.
downloadPath	string	{workingDir}/download	Directory for in-progress downloads. Managed by the download Space Allocator.
updateItemTtl	duration	"30d"	Time-to-live for installed items. After this period, items become eligible for eviction by the Space Allocator.
removeOutdatedPeriod	duration	"24h"	How often the CM checks for and removes outdated items that have exceeded their TTL.

Both installPath and downloadPath are managed by separate Space Allocator instances. If both paths resolve to the same filesystem partition, the allocators share a single partition view and coordinate their space usage to prevent over-allocation.

SM Storage Configuration

The Service Manager configuration file (aos_servicemanager.json) contains storage settings for service images.

Working Directory

Field	Type	Default	Description
workingDir	string	— (required)	Base directory for all SM working data. Other paths derive from this if not explicitly set.

Image Manager Storage

The imageManager section within the SM configuration controls service image storage:

{
  "imageManager": {
    "imagePath": "/var/aos/sm/images",
    "imagesPartLimit": 50,
    "updateItemTtl": "15d",
    "removeOutdatedPeriod": "12h"
  }
}

Field	Type	Default	Description
imagePath	string	{workingDir}/images	Directory where service image layers are stored. Managed by the images Space Allocator.
imagesPartLimit	integer	0 (unlimited)	Percentage of the partition's total capacity that the SM image allocator may consume (0–100). When set to 0, the allocator is constrained only by physical available space.
updateItemTtl	duration	"30d"	Time-to-live for stored service images. After this period, unused images become eligible for eviction.
removeOutdatedPeriod	duration	"24h"	How often the SM checks for and removes outdated images that have exceeded their TTL.

Partition Limit

The imagesPartLimit field is the only configurable percentage-based partition limit in the current implementation. It maps directly to the Space Allocator's percentage limit parameter:

• When imagesPartLimit is 0 — the SM image allocator has no per-allocator cap and uses all available partition space
• When imagesPartLimit is 50 — the SM image allocator may consume at most 50% of the partition's total capacity

This is useful when the SM image directory shares a partition with other data (e.g., CM images, system logs) and you want to guarantee that SM images cannot consume more than a defined fraction of the disk.

note

The CM's Space Allocators currently initialize with a limit of 0 (unlimited). The CM does not expose a configurable partition limit in its JSON configuration. If partition-level constraints are needed for CM storage, they must be enforced at the filesystem level (e.g., separate partitions or filesystem quotas).

Space Allocator Behavior

Both CM and SM use the Space Allocator module to manage disk space. The allocator provides:

• Partition-aware allocation — multiple allocators on the same filesystem partition share a single view of available space
• Automatic eviction — when space is insufficient, the oldest outdated items are removed to free capacity
• TTL-based lifecycle — items are registered as eviction candidates after their TTL expires

Eviction Flow

┌──────────────────────────────────────────────────────────────┐
│                    Allocation Request                         │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Check partition      │
                    │ limit (if > 0)       │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │                     │
                    ▼                     ▼
            Space available?       Evict outdated items
                    │              (oldest first)
                    │                     │
                    ▼                     ▼
            ┌─────────────┐     ┌─────────────────┐
            │  Allocate   │     │ Enough freed?    │
            └─────────────┘     └────────┬────────┘
                                         │
                                ┌────────┴────────┐
                                │                 │
                                ▼                 ▼
                          Allocate          Return error
                                         (insufficient space)

System Limits

The Space Allocator has compile-time limits that constrain the storage subsystem:

Limit	Value	Description
Maximum partitions	4	Maximum number of distinct filesystem partitions tracked simultaneously across all allocators
Maximum outdated items	64	Maximum number of items in the eviction queue per partition

These limits are defined at compile time and cannot be changed through configuration files.

Service-Level Quotas

Each service defines its resource quotas in its item configuration (service manifest). The storage-related quota fields are:

Quota Field	Type	Description
storageLimit	integer (bytes)	Maximum persistent storage a service instance may consume
stateLimit	integer (bytes)	Maximum state data a service instance may consume

These quotas are enforced when the CM sets up storage and state directories for a service instance. The actual allocated size for each instance is determined by the interaction between the service's quota limits and the Node's resource ratios.

Resource Ratio Interaction

The Unit configuration defines per-Node resourceRatios that modulate how much of a service's quota is actually allocated:

{
  "resourceRatios": {
    "storage": 52,
    "state": 53
  }
}

The allocation formula is:

allocatedSize = quota × (ratio / 100)

Where:

• quota is the service's storageLimit or stateLimit from its manifest
• ratio is the corresponding storage or state value from the Node's resourceRatios

If no resource ratio is configured for the Node, a default ratio of 50% is used. The ratio is clamped to a maximum of 100%.

Allocation Priority

When determining how much storage/state to allocate for a service instance, the system follows this precedence:

1. Explicit requested resources — if the service manifest specifies requestedResources.storage or requestedResources.state, that value is used (clamped to the quota limit)
2. Resource ratio calculation — if no explicit request exists, the allocation is computed from the quota and the Node's resource ratio
3. Skip resource limits — if the service's skipResourceLimits flag is set, storage and state allocation sizes are set to 0 (no limit enforcement)

Storage and State Directories

For each running service instance, the CM creates:

• A storage directory at {storageDir}/{instance-path}/ — for persistent data that survives restarts
• A state directory at {stateDir}/{instance-path}/ — for state data that may be synchronized with the cloud

The CM tracks whether storage and state directories reside on the same filesystem partition. This information is used to coordinate space allocation when both directories compete for the same physical disk.

Duration Format

All duration fields in storage configuration use a string format supporting days, hours, minutes, and seconds:

Format	Example	Meaning
Days	"30d"	30 days
Hours	"24h"	24 hours
Minutes	"10m"	10 minutes
Seconds	"5s"	5 seconds
Combined	"1h30m"	1 hour and 30 minutes

Configuration Examples

CM with Explicit Storage Paths

{
  "workingDir": "/var/aos/cm",
  "storageDir": "/mnt/data/storages",
  "stateDir": "/mnt/data/states",
  "imageManager": {
    "installPath": "/mnt/images/cm/install",
    "downloadPath": "/tmp/aos/download",
    "updateItemTtl": "14d",
    "removeOutdatedPeriod": "6h"
  }
}

In this example:

• Service storage and state are on a dedicated data partition (/mnt/data/)
• Installed images are on a separate images partition (/mnt/images/)
• Downloads use temporary storage (/tmp/) that may be cleared on reboot
• Items are evicted after 14 days, with checks every 6 hours

SM with Partition Limit

{
  "workingDir": "/var/aos/sm",
  "imageManager": {
    "imagePath": "/var/aos/sm/images",
    "imagesPartLimit": 60,
    "updateItemTtl": "7d",
    "removeOutdatedPeriod": "4h"
  }
}

In this example:

• SM images may consume at most 60% of the partition containing /var/aos/sm/images
• Images are evicted after 7 days of being unused
• The outdated check runs every 4 hours

Minimal Configuration (Defaults)

{
  "workingDir": "/var/aos/cm"
}

With only workingDir specified, all storage paths default to subdirectories:

• storageDir → /var/aos/cm/storages
• stateDir → /var/aos/cm/states
• installPath → /var/aos/cm/install
• downloadPath → /var/aos/cm/download
• updateItemTtl → 30 days
• removeOutdatedPeriod → 24 hours

Related Pages

• Configuration Reference — overview of the AosCore configuration system
• Unit Configuration — cloud-managed resource ratios that modulate per-service quotas
• Space Allocator — partition-aware disk space management module
• SM Image Manager — service image storage and lifecycle
• CM Update Manager — Deployment Bundle image management
• Service Instance States — how storage/state is provisioned during instance lifecycle