Wasm Plugin Image Specification

1. Overview

This document defines the structure and building method of Higress Wasm Plugin images. When preparing, we referred to Wasm Image Specification.

2. Image Structure

Each image needs to be build in OCI Image Specification based on scratch, and shall only contain following files:

  • spec.yaml: Required. Metadata file of the plugin. Please refer to section 3 below for its format.
  • README.md: Required. Readme file describing the usage of the plugin. Markdown format. Written in English or Chinese.
  • README_{lang}.md: Optional. Readme file describing the usage of the plugin. Markdown format. lang can be ZH or EN.
  • icon.png: Optional. Icon file of the plugin. A URL of the plugin icon can also be specified in spec.yaml. If both the file and the URL are configured, the file will be used for display.
  • plugin.wasm: Required. The binary file of the plugin.

Each layer of the image can only contain a single file.

Except the layer containing plugin.wasm, the media type of other layers shall be set according to the file inside:

  • spec.yaml: application/vnd.module.wasm.spec.v1+yaml
  • README.md: application/vnd.module.wasm.doc.v1+markdown
  • README_{lang}.md: application/vnd.module.wasm.doc.v1.{lang}+markdown
  • icon.png: application/vnd.module.wasm.icon.v1+png

plugin.wasm must be placed in the last layer of the image, with the media type of application/vnd.oci.image.layer.v1.tar+gzip.

3. Metadata File Format

The format of metadata file, spec.yaml, is as following, using the metadata of basic-auth plugin as an example:

  1. apiVersion: 1.0.0 # The schema version of the content below. Always use to 1.0.0 for now.
    info:
    category: auth # Plugin category. Options: auth (authentication and authorization), security (security protection), protocol (protocol transformation), flow-control, flow-monitor,custom
    name: basic-auth/v1 # Plugin name, which is the unique identifier of the plugin. It is recommended to add a version suffix, such as “/v1”, just in case an incompatible upgrade in the future.
    title: Basic Auth # Display name. I18n supported.
    description: 本插件实现了基于 HTTP Basic Auth 标准进行认证鉴权的功能。 # Plugin description. I18n supported.
    x-description-i18n: # I18n content of the description field above. Translated contents can be added using “x-{name}-i18n” fields for all i18n-supported fields.
    en-US: This plugin implements an authentication function based on HTTP Basic Auth standard.
    version: 1.0.0 # Plugin version
    contact: # Plugin contact
    name: Higress Team
    email: admin@higress.io
    spec:
    priority: 0 # Execution priority within the given phase. Please refer to https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin
    configSchema: # Schema of the plugin’s runtime configurations, which shall be defined with the Schema object in OpenAPI 3.0.0 standard.
    openAPIV3Schema: # Please refer to https://openapi.apifox.cn/#schema-%E5%AF%B9%E8%B1%A1 for the data structure. Some fields which can be used for display support i18n.
    type: object
    properties:
    consumers:
    type: array
    scope: GLOBAL # Field effective scope. Options: GLOBAL (global configuration), INSTANCE (instance-level configuration, which can be set associated to routes or domains.), ALL (Available as both global and instance-level configurations). Optional. Default value is INSTANCE.
    title: 调用方列表
    x-title-i18n:
    en-US: Consumer List
    description: 服务调用方列表,用于对请求进行认证
    x-description-i18n:
    en-US: List of service consumers which will be used in request authentication
    items:
    type: object
    properties:
    name:
    type: string
    title: 名称
    x-title-i18n:
    en-US: Name
    description: 该调用方的名称
    x-description-i18n:
    en-US: The name of the consumer
    # Data validation shall be implemented according JSON Schema Validation Spec
    # Following values are supported:
    # - maximum
    # - minimum
    # - maxLength
    # - minLength
    # - pattern
    # - maxItems
    # - minItems
    # - required
    minLength: 6 # Minimum length for data validation
    maxLength: 256 # Maximum length for data validation
    pattern: “^$” # Regular experssion for data validation
    example:
    - consumer1
    credential:
    type: string
    title: 访问凭证
    x-title-i18n:
    en-US: Credential
    description: 该调用方的访问凭证
    x-description-i18n:
    en-US: The credential of the consumer
    example:
    - admin:123456
    required:
    - name
    - credential
    allow:
    type: array
    title: 授权访问的调用方列表
    x-title-i18n:
    en-US: Allowed Consumers
    description: 对于匹配上述条件的请求,允许访问的调用方列表
    x-description-i18n:
    en-US: Consumers to be allowed for matched requests
    items:
    type: string
    example:
    - consumer1
    required:
    - allow
    - consumers
    example:
    consumers:
    - name: consumer1
    credential: admin:123456
    - name: consumer2
    credential: guest:abc
    allow:
    - consumer2

4. How to Build an Image

  1. Start the builder container from the Higress root folder
  1. GO_VERSION=”1.19
    TINYGO_VERSION=”0.25.0
    ORAS_VERSION=”1.0.0
    PLUGIN_NAME=”hello-world
    BUILDER_IMAGE=”higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/wasm-go-builder:go${GO_VERSION}-tinygo${TINYGO_VERSION}-oras${ORAS_VERSION}”
    docker run -v ${PWD}:/workspace -e PLUGIN_NAME=${PLUGIN_NAME} -it —rm /bin/bash
  1. Build Wasm file inside the container
  1. cd /workspace/plugins/wasm-go/extensions/${PLUGIN_NAME}
    go mod tidy
    tinygo build -o ./plugin.wasm -scheduler=none -target=wasi ./main.go
  1. Build and push an OCI image
  1. tar czvf plugin.tar.gz plugin.wasm
    IMAGE_REGISTRY_SERVICE=docker.io
    IMAGE_REPOSITORY=”${IMAGE_REGISTRY_SERVICE}/plugins/${PLUGIN_NAME}”
    IMAGE_TAG=”v0.0.1
    oras login ${IMAGE_REGISTRY_SERVICE}
    oras push ${IMAGE_REPOSITORY}:${IMAGE_TAG} \
    ./spec.yaml:application/vnd.module.wasm.spec.v1+yaml \
    ./README.md:application/vnd.module.wasm.doc.v1+markdown \
    ./README_EN.md:application/vnd.module.wasm.doc.v1.en+markdown \
    ./plugin.tar.gz:application/vnd.oci.image.layer.v1.tar+gzip

5. Appendix

5.1 Default Icon for Each Plugin Category