Atym Container Format and Image Layout

Image Format

Ocre container images follow the Open Container Initiative (OCI) format where possible, with some modifications to support the needs of constrained, embedded devices. The manifest format is modeled after the OCI Image Manifest format and conforms to the Wasm OCI Artifact layout specifications.

Ocre containers can be stored either as a single zip file or as a set of files in a directory, providing flexibility in how they are distributed and managed. The container format uses the Wasm OCI Artifact layout as its config.mediaType, ensuring compatibility with standard OCI tooling while maintaining the specific requirements for WebAssembly modules in embedded environments.

---

Image Components

An Ocre container consists of the following three components:

Component	Description
oci-layout	OCI Layout file in JSON format. Specifies the version of the imageLayoutVersion in use. Ocre containers must set this value to 1.0.0.
index.json	Image index file in JSON format. Serves as the entry point for the container image. Ocre containers will have one manifest entry with the mediaType of application/vnd.oci.image.manifest.v1+json which points to the Ocre artifact.
blobs/	Directory containing content-addressable blobs. Blobs are stored as files with the naming convention of <alg>/<encoded> which must match the digest format <alg>:<encoded>. Ocre containers support the SHA-256 algorithm only.

oci-layout

The oci-layout file identifies this as an Open Container Image Layout. Written in UTF-8 encoded JSON, it contains a single field imageLayoutVersion which must be set to 1.0.0 for Ocre containers. This file follows the application/vnd.oci.layout.header.v1+json media type specification.

Example:

{
  "imageLayoutVersion": "1.0.0"
}

index.json

The index.json file serves as the entry point for the container image. Written in UTF-8 encoded JSON, it contains a single manifest entry pointing to the Ocre artifact, using the mediaType of application/vnd.oci.image.manifest.v1+json. This file follows the OCI Image Index Specification.

Example:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:b11ba766595f3bf6b1db36019cb09decc88aca35ff44dc5ae70bd88d4f188be4",
      "size": 445
    }
  ]
}

This illustrates an index that provides a single reference to the Ocre container image manifest.

blobs

The blobs directory contains all content-addressable components of the Ocre container. Files are stored using the format <alg>/<encoded>, matching their digest format <alg>:<encoded>. Currently, Ocre containers only support the SHA-256 algorithm for these digests.

---

Image Manifest

The Ocre Container Image Manifest (application/vnd.oci.image.manifest.v1+json) defines the structure and contents of an Ocre container. It provides a standardized way to organize, configure, and execute container elements within the Ocre runtime, providing configuration and layers for a single cohesive container image.

The manifest references all elements that comprise the container image, including:

• Configuration: Metadata defining container execution, including properties, variables, and permissions.
• WebAssembly Module: Standard WebAssembly executable code that runs in the container runtime.
• Blobs (Optional): Additional resources that can be referenced by the application, such as images, binary data, or AI/ML models.

Manifest Structure

The manifest format follows the OCI Image Manifest specification, and while this format typically supports multiple architectures and operating systems, Ocre containers are fixed to the WASI configuration. Additionally, every Ocre container must include a manifest file (application/vnd.oci.image.manifest.v1+json) with a matching mediaType.

Example:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.wasm.config.v0+json",
    "digest": "sha256:55a98fff5a9a7bef217678f2669ad89816875df55af51b6d1c23a5f9393234e3",
    "size": 196
  },
  "layers": [
    {
      "mediaType": "application/wasm",
      "digest": "sha256:71cb138990af165c4baf0c43361e5c055ed60a5d2632ee547597be56dcfa07e2",
      "size": 2397
    }
  ]
}

Manifest Elements

Element	Type	Required	Description
schemaVersion	int	Yes	Specifies the image manifest schema version; this MUST be 2.
mediaType	string	Yes	Specifies the type of this manifest file; for Ocre containers, this MUST be application/vnd.oci.image.manifest.v1+json.
config	descriptor object	Yes	References the configuration object for this container image; schema follows the OCI Content Descriptor schema; mediaType must be application/vnd.wasm.config.v0+json.
layers	array	Yes	Specifies the list of elements that comprise this container image; each layer is a descriptor; one and only one layer MUST be of type application/wasm.

---

Image Configuration

The container configuration (application/vnd.wasm.config.v0+json) defines how the container should be run. It is a collection of metadata that controls the container's runtime behavior, including environment variables, execution parameters, hardware permissions, and entry points.

For Ocre containers, this configuration is specifically tailored to WebAssembly modules running in embedded environments, ensuring proper initialization and execution within resource constraints.

Configuration Structure

The configuration file follows the OCI Image Manifest specification with modifications for WASM and embedded environments.

Example:

{
  "architecture": "wasm",
  "os": "wasip1",
  "layerDigests": [
    "sha256:71cb138990af165c4baf0c43361e5c055ed60a5d2632ee547597be56dcfa07e2"
  ],
  "module": {
    "entryPoint": "on_init"
  }
}

Configuration Elements

Element	Type	Required	Description
architecture	string	Yes	CPU architecture of the binaries in this image; this MUST be wasm.
os	string	Yes	Operating system which this image is built to run on; this MUST be wasip1 or wasip2 according to the WASM target type.
layerDigests	array	Yes	Digests of all of the layers this configuration targets; digests must be in the same order as in the image manifest file.
module	module object	Yes	Specifies the parameters used for execution; entryPoint defines the WASM function to call on container start.

Future Enhancements

Ocre will extend its configuration format to better align with OCI standards and support critical runtime elements through the config entry. This enhancement will enable control over environment variables, permissions, and additional runtime parameters that are essential for container operation.

Example (future format):

{
  "config": {
    "Env": [
      "name1=val1",
      "name2=val2"
    ],
    "Permissions": [
      "perm1",
      "perm2"
    ]
  }
}