OCI Image Format

Introduction

AosCore packages all Deployable Items — services, firmware components, and layers — using the Open Container Initiative (OCI) Image Format Specification. This standardized format provides content-addressable storage, cryptographic integrity verification, and platform-aware image selection.

The ocispec module (aos_core_cpp/src/common/ocispec/) implements load and save operations for OCI image structures, while the interface layer (aos_core_lib_cpp/src/core/common/ocispec/itf/) defines the data contracts. Both the Communication Manager (CM) and Service Manager (SM) use this module — CM for processing incoming Deployment Bundles, and SM for managing service images on-Node.

OCI Specification Compliance

AosCore implements OCI Image Spec schema version 2 (as defined by cSchemaVersion = 2 in the codebase) and reports OCI runtime spec version 1.2.0. The implementation covers:

• Image Index — top-level manifest list for multi-platform images
• Image Manifest — references config and layer blobs for a single image
• Image Config — container configuration (platform, environment, entrypoint, rootfs)
• Runtime Config — OCI runtime specification for container execution (Linux containers and VMs)

In addition, AosCore extends the OCI format with an Item Config — an AosEdge-specific metadata structure that carries service quotas, resource requirements, permissions, and scheduling parameters.

Image Structure Overview

A Deployable Item stored by AosCore follows this hierarchy:

image-index.json          ← Image Index (entry point)
├── manifest-<digest>.json   ← Image Manifest (per-platform)
│   ├── config-<digest>.json    ← Image Config (container settings)
│   ├── item-config-<digest>.json  ← Item Config (AosEdge extension)
│   └── layer-<digest>.tar.gz     ← Layer blob(s)

All blobs are stored in a content-addressable layout where each file is identified by its SHA-256 digest. This enables deduplication — shared layers between services are stored only once.

Image Index

The Image Index is the entry point for any Deployable Item. It lists one or more platform-specific manifests, allowing AosCore to select the correct image variant for the target Node's architecture.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:129abeb509f55870ec19f24eba0caecccee3f0e055c467e1df8513bdcddc746f",
      "size": 1018,
      "platform": {
        "architecture": "amd64",
        "variant": "6",
        "os": "linux",
        "os.version": "6.0.8",
        "os.features": ["feature1", "feature2"]
      }
    }
  ]
}

Field	Description
schemaVersion	Always 2
mediaType	application/vnd.oci.image.index.v1+json
artifactType	Optional — identifies the artifact type when used with OCI artifacts
manifests	Array of content descriptors pointing to platform-specific manifests

Each manifest entry includes a platform object with architecture, os, and optional variant, os.version, and os.features fields. CM uses this information to route the correct manifest to each Node based on its hardware platform.

Image Manifest

The Image Manifest ties together the config, layers, and the AosEdge-specific item config for a single platform variant.

{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:a9fd89f4f021b5cd92fc993506886c243f024d4e4d863bc4939114c05c0b5f60",
    "size": 288
  },
  "aosItemConfig": {
    "mediaType": "application/vnd.aos.service.config.v1+json",
    "digest": "sha256:7bcbb9f29c1dd8e1d8a61eccdcf7eeeb3ec6072effdf6723707b5f4ead062e9c",
    "size": 322
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:129abeb509f55870ec19f24eba0caecccee3f0e055c467e1df8513bdcddc746f",
      "size": 1018
    }
  ]
}

Field	Description
config	Content descriptor pointing to the OCI image config blob
aosItemConfig	AosEdge extension — content descriptor pointing to the item config blob
layers	Ordered array of content descriptors for filesystem layers

The aosItemConfig field is the key AosEdge extension to the standard OCI manifest. It references a separate JSON blob containing service-specific metadata that AosCore needs for scheduling, resource management, and access control.

Content Descriptor

Every reference between OCI structures uses a content descriptor — a uniform pointer to a blob:

{
  "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
  "digest": "sha256:129abeb509f55870ec19f24eba0caecccee3f0e055c467e1df8513bdcddc746f",
  "size": 1018
}

Field	Description
mediaType	MIME type identifying the blob format
digest	Content-addressable hash (sha256:<hex>)
size	Blob size in bytes — used for space allocation and download progress

The digest serves as both an identifier and an integrity check. After downloading a blob, AosCore verifies that its computed digest matches the declared value.

Layer Media Types

AosCore supports several layer media types for different Deployable Item formats:

Media Type	Description
application/vnd.oci.image.layer.v1.tar	Uncompressed tar layer
application/vnd.oci.image.layer.v1.tar+gzip	Gzip-compressed tar layer (standard container layers)
application/vnd.oci.empty.v1+json	Empty blob placeholder
application/vnd.aos.image.component.full.v1+gzip	Full firmware component (gzip-compressed)
application/vnd.aos.image.component.full.v1+squashfs	Full firmware component (SquashFS)
application/vnd.aos.image.component.inc.v1+squashfs	Incremental firmware component (SquashFS delta)

The vnd.aos.* media types are AosEdge-specific extensions for firmware components. The incremental SquashFS type enables delta updates — only the changed blocks are transmitted, reducing bandwidth for firmware updates.

Image Config

The Image Config follows the standard OCI image configuration format, describing the container's platform and execution parameters:

{
  "architecture": "x86_64",
  "author": "gtest",
  "created": "2024-12-31T23:59:59Z",
  "os": "Linux",
  "config": {
    "exposedPorts": { "8080/tcp": {}, "53/udp": {} },
    "entrypoint": ["test-entrypoint", "arg1"],
    "cmd": ["-u", "main.py"],
    "env": ["PATH=/usr/local/bin:/usr/bin:/bin", "TERM=xterm"],
    "workingDir": "/app"
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:129abeb509f55870ec19f24eba0caecccee3f0e055c467e1df8513bdcddc746f"
    ]
  }
}

Section	Fields	Purpose
Platform	architecture, os, variant, os.version, os.features	Target platform identification
Config	entrypoint, cmd, env, exposedPorts, workingDir	Container execution parameters
Rootfs	type, diff_ids	Layer identity for filesystem assembly

The rootfs.diff_ids array contains the uncompressed digests of each layer in order. SM's Launcher uses these to assemble the container's root filesystem by stacking layers.

Item Config (AosEdge Extension)

The Item Config is AosCore's primary extension to the OCI specification. It carries all the metadata that AosCore needs to schedule, resource-limit, and permission-gate a Deployable Item. This config is referenced from the manifest's aosItemConfig field.

{
  "created": "2024-12-31T23:59:59Z",
  "author": "Aos cloud",
  "skipResourceLimits": false,
  "hostname": "my-service",
  "balancingPolicy": "disabled",
  "runtimes": [
    { "codename": "crun" },
    { "codename": "runc" }
  ],
  "runParameters": {
    "startInterval": "PT1M",
    "startBurst": 0,
    "restartInterval": "PT5M"
  },
  "offlineTTL": "P1DT3H",
  "quotas": {
    "cpuDMIPSLimit": 100,
    "ramLimit": 200,
    "storageLimit": 300,
    "stateLimit": 400,
    "tmpLimit": 500,
    "uploadSpeed": 600,
    "downloadSpeed": 700,
    "noFileLimit": 800,
    "pidsLimit": 900
  },
  "requestedResources": {
    "cpu": 50,
    "ram": 128,
    "storage": 256,
    "state": 64
  },
  "allowedConnections": {
    "9931560c-be75-4f60-9abf-08297d905332/8087-8088/tcp": {},
    "9931560c-be75-4f60-9abf-08297d905332/1515/udp": {}
  },
  "resources": [
    { "name": "gpu", "mode": "rw" },
    { "name": "serial-port", "mode": "ro" }
  ],
  "permissions": {
    "vis": {
      "Attribute.Body.Vehicle.VIN": "r",
      "Signal.Doors.*": "r"
    }
  },
  "alertRules": {
    "ram": { "minTimeout": "PT1M", "minThreshold": 10, "maxThreshold": 20 },
    "cpu": { "minTimeout": "PT2M", "minThreshold": 15, "maxThreshold": 25 }
  },
  "sysctl": {
    "net.ipv4.ip_forward": "1"
  }
}

Item Config Fields

Field	Type	Description
created	ISO 8601 timestamp	Creation time of the config
author	string	Creator identity
skipResourceLimits	boolean	If true, resource quotas are not enforced
hostname	string (optional)	Custom hostname for the container
balancingPolicy	"enabled" or "disabled"	Whether the service participates in load balancing across Nodes
runtimes	array of {codename}	Compatible container runtimes (e.g., crun, runc)
runParameters	object	Start/restart timing parameters
offlineTTL	ISO 8601 duration	How long the service may run without cloud connectivity
quotas	object	Resource limits (CPU, RAM, storage, network, PIDs, file descriptors)
requestedResources	object (optional)	Minimum resources needed for scheduling decisions
allowedConnections	object	Network connections the service is permitted to establish
resources	array	Host resources (devices, hardware) the service requires
permissions	object	Function-level access permissions for inter-service communication
alertRules	object (optional)	Thresholds for generating resource usage alerts
sysctl	object	Kernel parameters to set in the container's namespace

Service Quotas

The quotas object defines hard limits enforced by SM's Resource Manager:

Quota	Unit	Description
cpuDMIPSLimit	DMIPS	Maximum CPU capacity
ramLimit	bytes	Maximum RAM usage
pidsLimit	count	Maximum number of processes
noFileLimit	count	Maximum open file descriptors
tmpLimit	bytes	Maximum temporary storage
stateLimit	bytes	Maximum persistent state storage
storageLimit	bytes	Maximum image storage
uploadSpeed	bytes/sec	Network upload rate limit
downloadSpeed	bytes/sec	Network download rate limit
uploadLimit	bytes	Total upload data cap
downloadLimit	bytes	Total download data cap

Run Parameters

Parameter	Description
startInterval	Minimum time between consecutive start attempts (ISO 8601 duration)
startBurst	Number of rapid starts allowed before throttling
restartInterval	Delay before restarting a failed service (ISO 8601 duration)

Runtime Config

The Runtime Config follows the OCI Runtime Specification and defines how a container is executed. SM's Launcher generates this config when starting a service instance.

Key sections include:

Section	Purpose
process	User, args, env, capabilities, resource limits
root	Container rootfs path and read-only flag
mounts	Filesystem mount points (proc, dev, sys, tmpfs)
linux	Namespaces, cgroups, devices, sysctl, masked/readonly paths
vm	Hypervisor, kernel, and hardware config (for VM-based services)

AosCore supports both Linux container runtimes (using namespaces and cgroups) and VM-based execution (using a hypervisor with device tree passthrough, IOMEM mappings, and IRQ assignments). The runtime type is selected based on the runtimes field in the Item Config and the Node's available runners.

Image Processing Flow

1. CM receives a Deployment Bundle from the cloud containing an image index digest
2. CM loads the Image Index and iterates over manifests to identify the correct platform variant for each target Node
3. CM downloads blobs (manifests, configs, layers) into content-addressable storage, verifying each digest
4. SM receives the image and loads the Image Manifest to discover the config and layer references
5. SM's Launcher loads the Item Config to determine resource quotas, runtime selection, and permissions
6. SM's Launcher loads the Image Config to extract entrypoint, environment, and rootfs layer IDs
7. SM assembles the rootfs by stacking layers and generates the Runtime Config for the container runtime

Related Pages

• Common Infrastructure — overview of all shared modules
• Service Manager — SM component that manages service images
• Image Manager — SM's image storage and lifecycle management

• Image Deployment Pipeline — end-to-end image deployment flow

• Runtime Types — container and VM runtime execution models

• Architecture Overview — system-wide component architecture