Skip to content

Commit

Permalink
Add a variant of Wasm image spec based on standard media types. (#265)
Browse files Browse the repository at this point in the history 
* Add OCI-compatible Wasm Spec.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Review: add annotation instruction

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Rename filter.wasm to plugin.wasm to line with API.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* review: Add docker variant.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* style

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* clear

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Update spec/README-compat.md

Co-authored-by: Shane O'Donnell <Sodman74@gmail.com>

* Update spec/README-compat.md

Co-authored-by: Shane O'Donnell <Sodman74@gmail.com>

* Restrcture spec/ dir, add general info.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* fix typo

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Not necessarily Istio.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Put common terminology in README

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Update spec/README.md

Co-authored-by: Shane O'Donnell <Sodman74@gmail.com>

* Fix typo, add more sentences.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

* Make annotations optional.

Signed-off-by: Takeshi Yoneda <takeshi@tetrate.io>

Co-authored-by: Shane O'Donnell <Sodman74@gmail.com>
  • Loading branch information
@mathetake @Sodman
mathetake and Sodman authored Jul 2, 2021
1 parent ea64e9f commit 7389be1
Show file tree
Hide file tree
Showing 3 changed files with 293 additions and 107 deletions.
144 changes: 37 additions & 107 deletions spec/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,133 +1,63 @@
# Wasm Image specifications

## WASM Artifact Image Specification v0.0.0
## Introduction

- [Introduction](#introduction)
- [Terminology](#terminology)
- [Description](#description)
- [Overview](#overview)
- [Layers](#layers)
- [Running OCI Images with Envoy](#running-oci-images-with-envoy)
- [Format](#format)
- [Envoy WASM Filter Specification](#envoy-wasm-filter-specification)
- [Example](#example)
The Wasm Image specification defines how to bundle Wasm modules as container images. A compatible Wasm image consists of a Wasm binary file, and runtime metadata for the target Wasm runtime. We primarily consider the use case of [Envoy] as Wasm runtime and its Wasm filter/plugins, although the spec is intended to be generic and to provide a standard mechanism to manage the building and running of Wasm modules on any Wasm runtime.


### Introduction:

The WASM Artifact Image Specification defines how to bundle WASM modules as OCI images. WASM Artifact 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 Artifact 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.

### Terminology:
## Terminology:

| Term | Definition |
|------------------------------------|--------------------------------------------------|
| WASM Module | The distributable, loadable, and executable unit of code in WebAssembly.
| WASM OCI Image Specification | The specification for storing WASM modules as OCI Images.
| WASM Runtime | The execution environment into which a WASM Module may be loaded. This refers to the application itself which loads and executes a wasm module. Examples include web browsers, the Open Policy Agent, the Envoy Proxy, or any other application which supports extension via WASM modules.
| Runtime Configuration | Configuration specific to the runtime which consumes a module. This configuration is stored as JSON and bundled with the module in the image in the specification.
| Envoy WASM Filter | Custom Filters for the Envoy Proxy built as a WASM module.
| Envoy WASM OCI Image | Envoy Filters stored as OCI images according to the specification.
| Envoy WASM OCI Artifact Specification | An extension of the WASM OCI Artifact Spec which describes how to bundle and ship Envoy WASM filters as OCI Images. |

### Description:

#### Overview:

The WASM OCI Artifact 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.

#### Layers:

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 (Application Binary Interface) 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.

#### Running OCI Images with Envoy:
| Wasm Module | The distributable, loadable, and executable unit of code in WebAssembly.
| Wasm Image Specification | The specification for storing Wasm modules as container images.
| Wasm Runtime | The execution environment into which a Wasm Module may be loaded. This refers to the application itself which loads and executes a wasm module. Examples include web browsers, the Open Policy Agent, the Envoy Proxy, or any other application which supports extension via Wasm modules.
| Runtime Configuation | Configuration or metadata specific to the runtime which consumes a module.

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

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.
Here we have several specifications for how to bundle Wasm modules as container images.

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.
There are two variants of the specification:
- [spec.md](spec.md)
- [spec-compat.md](spec-compat.md)

Developers and Wasm module consumers can leverage both of these specifications.

### Format:
For clarity, we call the variant in [spec.md](spec.md) *oci*, and the one in [spec-compat.md](spec-compat.md) *compat*.

The WASM OCI Artifact Spec consists of two layers bundled together:
- A layer specifying configuration for the target runtime
- A layer containing the compiled WASM module itself
## Difference between variants

Each layer is associated with its own Media Type, which is stored in the OCI Descriptor for that layer:
Our goal is to make the *oci* variant the default format for shipping Wasm modules in container images, we acknowledge however that there are toolchains and registries deployed and in use that do not support our custom media types yet. To accomodate those exisiting toolchains, there is the semantically equivalent *compat* variant, which provides the same feature set, but is compatible with existing tooling because it 'looks' very much like a normal container image. Implementations of this spec should support both variants.

| Media Type | Type | Description |
|------------|------|-------------|
| application/vnd.module.wasm.config.v1+json | JSON Object | Configuration for the Target WASM runtime.
| application/vnd.module.wasm.content.layer.v1+wasm | binary data (byte array) | The compiled module data |
With that said, the key difference between these two variants is that, the *oci* variant makes use of the custom media types on [OCI Artifact] for image layers while the *compat* variant leverages the standard media types.

`application/vnd.module.wasm.config.v1+json` Property Descriptions:
As a consequence, that introduces the difference in tools available for building and pushing images.
For example, the only way to build and push *oci* variant images is to use [`wasme`] cli while you can use [`buildah`] or [`docker`] for *compat* variant images.

| Property | Type | Description |
|------------|------|-------------|
| type | string | Name of the target runtime. Required. Specifies the intended runtime of the bundled module. The content of the Opaque JSON Config is specific to the type of WASM runtime.
| abiVersions | string array | List of ABI Versions for the target runtime with which the image is compatible. The format for the version is dependent upon the runtime itself.
| config | JSON Object | This field stores any configuration parameters required by the target runtime. Its structure depends on the specified runtime. |
Not only that, the usage of custom media types on top of [OCI Artifact] requires registries to support arbitrary custom media types. Therefore, you might not be able to push *oci* variants to your registry while [WebAssemblyHub] is designed for accepting them.

## Wasm image support in [Istio]

### Envoy WASM Filter Specification
Istio's Wasm Plugin API has support for **both of these variants** to deploy your Wasm plugins into Envoy sidecars.

The runtime config for Envoy WASM Filter OCI Images has the following format:
### Which variant should I use in [Istio]?

- *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
Given that Istio supports both of variants, you can choose whichever variant depending on your needs. For example, if you want to use [`docker`] cli, then choose *compat* variant and push them to your container registries. You might want to use [`wasme`] cli and [WebAssemblyHub] then choose the *oci* variant.

The `root_ids` key in the *config* JSON Object will have a list of strings as a value. Each string in the list corresponds to the name of a registered Root Context Helper defined in the module.
## How can I build images?

#### Example:
For *oci* variant, see the guideline by [`wasme`].

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"
}
}
]
```
For *compat* variant, follow the instructions in
- [build a compat image with buildah](spec-compat.md#appendix-1-build-a-compat-image-with-buildah) if you want to use [`buildah`].
- [build a compat image with docker](spec-compat.md#appendix-2-build-a-compat-image-with-docker-cli) if you want to use [`docker`].

The following is the runtime config 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"
]
}
}
```
[Envoy]: https://github.com/envoyproxy/envoy
[Istio]: https://github.com/istio/istio
[OCI Artifact]: https://github.com/opencontainers/artifacts
[WebAssemblyHub]: https://webassemblyhub.io/

You can use the `wasme` tool to take new or existing module code and package it according to the WASM OCI Spec.
[`docker`]: https://docs.docker.com/engine/reference/commandline/cli/
[`buildah`]: https://github.com/containers/buildah
[`wasme`]: https://docs.solo.io/web-assembly-hub/latest/installation/
142 changes: 142 additions & 0 deletions spec/spec-compat.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@

# Wasm Image Specification v0.0.0

## Introduction:

This document describes a variant of [Wasm Artifact Image Specification](spec.md), which leverages the compatible layer media types. Here, we omit definition and terminology explained in [Wasm Artifact Image Specification](spec.md).

We call this variant "compat", and the spec in [Wasm Artifact Image Specification](spec.md) "oci".

## Description

This *compat* variant makes use of compatible media type for layers, and is not based on custom OCI Artifact media types. This way users can operate with standard tools such as docker, podman, buildah, and standard container registries which don't yet support custom media types as used in [*oci* variant](spec.md).

## Specification

### Layer

The *compat* variant must consist of exactly one layer whose media type is one of the followings:
- `application/vnd.oci.image.layer.v1.tar+gzip`
- `application/vnd.docker.image.rootfs.diff.tar.gzip`

In addition, the layer must consist of the following two files:
- `plugin.wasm` - (**Required**) A Wasm binary to be loaded by the runtime.
- `runtime-config.json` - (**Optional**) A runtime configuration specified in [Wasm Artifact Image Specification](spec.md#Format). This is mainly used as metadata for the image, depending on the runtime.

### Annotation

If the media type equals `application/vnd.oci.image.layer.v1.tar+gzip`, then a *compat* variant image *should* add the annotation `module.wasm.image/variant=compat` in the manifest to make it easy to distinguish this *compat* variant from the *oci* variant. Note that this is **optional**.

### Example with `application/vnd.oci.image.layer.v1.tar+gzip` media type

The following is an example OCI manifest of images with `application/vnd.oci.image.layer.v1.tar+gzip` layer media type:

```
{
"schemaVersion": 2,
"config": {
"mediaType": "application/vnd.oci.image.config.v1+json",
"digest": "sha256:933594cea89247a78932eb9d74fae998e6fc3d1d114a7ff7705aaf702dbf7edb",
"size": 326
},
"layers": [
{
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"digest": "sha256:e05c6f7d59f4c5976d9c1be8e12c34f64c49e5541967581e7f052070705191ac",
"size": 151
}
],
"annotations": {
"module.wasm.image/variant": "compat"
}
}
```

### Example with `application/vnd.docker.image.rootfs.diff.tar.gzip` media type

The following is an example Docker manifest of images with `application/vnd.docker.image.rootfs.diff.tar.gzip` layer media type:

```
{
"schemaVersion": 2,
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"size": 1182,
"digest": "sha256:500c5c9b0755790c440f6d24a8926e399913bda2d599dcac24edb99a72b66de7"
},
"layers": [
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"size": 161,
"digest": "sha256:cf72304d01ead8fe014ed9f09e4132678ee4f29030ec46e6242c457071435ec3"
}
]
}
```

## Appendix 1: build a *compat* image with Buildah

We demonstrate how to build a *compat* image with Buildah, a standard cli for building OCI images. We use v1.21.0 of Buildah here. Produced images have `application/vnd.oci.image.layer.v1.tar+gzip` layer media type

We assume that you have a valid Wasm binary named `plugin.wasm` and `runtime-config.json` (optional) that you want to package as an image.

1. First, we create a working container from `scratch` base image with `buildah from` command.

```
$ buildah --name mywasm from scratch
mywasm
```

2. Next, add the annotation described above via `buildah config` command

```
$ buildah config --annotation "module.wasm.image/variant=compat" mywasm
```

**Note this step is optional. See [Annotation](#annotation) section.**


3. Then copy the files into that base image by `buildah copy` command to create the layer.

```
$ buildah copy mywasm plugin.wasm runtime-config.json ./
af82a227630327c24026d7c6d3057c3d5478b14426b74c547df011ca5f23d271
```

**Note: you must execute `buildah copy` exactly once in order to end up having only one layer in produced images**

4. Now, you can build a *compat* image and push it to your registry via `buildah commit` command

```
$ buildah commit mywasm docker://my-remote-registry/mywasm:0.1.0
```

## Appendix 2: build a *compat* image with Docker CLI

We demonstrate how to build a *compat* image with Docker CLI. Produced images have `application/vnd.docker.image.rootfs.diff.tar.gzip` layer media type.

We assume that you have a valid Wasm binary named `plugin.wasm` and `runtime-config.json` (optional) that you want to package as an image.

1. First, we prepare the following Dockerfile:

```
$ cat Dockerfile
FROM scratch
COPY runtime-config.json plugin.wasm ./
```

**Note: you must have exactly one `COPY` instruction in the Dockerfile in order to end up having only one layer in produced images**

2. Then, build your image via `docker build` command

```
$ docker build . -t my-registry/mywasm:0.1.0
```

3. Finally, push the image to your registry via `docker push` command

```
$ docker push my-registry/mywasm:0.1.0
```
Loading

0 comments on commit 7389be1

Please sign in to comment.