The latest version of the WASM OCI Image Specification can be found at its new home here

• Introduction
• Terminology
• Description
  • Overview
  • Layers
  • Running OCI Images with Envoy
• Format
• Envoy WASM Filter Specification
  • Example

The WASM OCI Image Specification defines how to bundle WASM modules as OCI images. WASM OCI Images consist of a WASM binary file, configuration file, and metadata for the target WASM runtime.

The spec is intended to be generic, allowing for any type of WASM module whether it is used to extend any Envoy, OPA, or the browser.

The spec can be considered an extension of the OCI Image Spec designed specifically for use by applications which produce and consume WASM modules (as opposed to application containers). It is intended to provide a standard mechanism to manage the building and running of WASM modules.

This document considers primarily the use case of storing WASM Envoy Filters as OCI Images.

The WASM OCI Image Specification defines a method of storing WASM modules which makes them easy to build, pull, publish, and execute.

Because each execution environment (runtime) for a WASM module may have runtime-specific configuration parameters, a WASM image is composed of both a content layer, for the WASM module itself, as well as a config layer, with metadata describing the module which is relevant to the target runtime.

The content layer always consists of the WASM module binary.

The config layer consists of a JSON-formatted string, which contains metadata for the target runtime. The runtime and ABI versions of an image can be deduced by parsing the config layer.

The config layer may also contain additional data, depending on the target runtime. For example, the config for a WASM Envoy Filter contains root_ids available on the filter.

For the sake of simplicity, the specification only supports a single module per image.

Envoy supports loading and running WASM modules via a file on local disk or an “Http datasource”.

Envoy WASM Filters can be stored according to the spec and run with Istio and Gloo, with the help of a local cache which pulls images from remote registries.

Control planes then configure the Envoy instances to load the filter via the local cache, using the required root_id parameter supplied in the image config if it is available.

The WASM OCI Image Spec consists of two layers bundled together:

• A layer specifying configuration for the target runtime.
• A layer containing the compiled WASM module itself.

Each layer is associated with its own Media Type, which is stored in the OCI Descriptor for that layer:

application/vnd.module.wasm.config.v1+json Property Descriptions:

The runtime config for Envoy WASM Filter OCI Images has the following format: type is set to envoy_proxy abiVersion is set to a recognized version of the Envoy Proxy WASM Filter ABI config is a JSON Object containing a list of Filter root_ids that can be used with the provided filter.

The following descriptors provide an example of the OCI Image descriptors for an Envoy WASM Filter stored according to the specification:

[
  {
    "mediaType": "application/vnd.module.wasm.config.v1+json",
    "digest": "sha256:d0a165298ae270c5644be8e9938036a3a7a5191f6be03286c40874d761c18abf",
    "size": 125,
    "annotations": {
      "org.opencontainers.image.title": "runtime-config.json"
    }
  },
  {
    "mediaType": "application/vnd.module.wasm.content.layer.v1+wasm",
    "digest": "sha256:5e82b945b59d03620fb360193753cbd08955e30a658dc51735a0fcbc2163d41c",
    "size": 1043056,
    "annotations": {
      "org.opencontainers.image.title": "filter.wasm"
    }
  }
]

The following is the runtime config is stored as the application/vnd.module.wasm.config.v1+json layer:

  "type": "envoy_proxy",
  "abi_version": "v0-541b2c1155fffb15ccde92b8324f3e38f7339ba6",
  "config": {
    "root_ids": [
      "add_header_root_id"
    ]
  }
}