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.
  2. info:
  3. category: auth # Plugin category. Options: auth (authentication and authorization), security (security protection), protocol (protocol transformation), flow-control, flow-monitor,custom
  4. 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.
  5. title: Basic Auth # Display name. I18n supported.
  6. description: 本插件实现了基于 HTTP Basic Auth 标准进行认证鉴权的功能。 # Plugin description. I18n supported.
  7. 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.
  8. en-US: This plugin implements an authentication function based on HTTP Basic Auth standard.
  9. version: 1.0.0 # Plugin version
  10. contact: # Plugin contact
  11. name: Higress Team
  12. email: admin@higress.io
  13. spec:
  14. priority: 0 # Execution priority within the given phase. Please refer to https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin
  15. configSchema: # Schema of the plugin’s runtime configurations, which shall be defined with the Schema object in OpenAPI 3.0.0 standard.
  16. 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.
  17. type: object
  18. properties:
  19. consumers:
  20. type: array
  21. x-scope: GLOBAL # Field effective scope. Options: GLOBAL (global configuration), RULE (rule-level configuration, which can be set associated to routes, domains or services.), ANY (Effective scope unrestricted). Optional. Default value is ANY.
  22. title: 调用方列表
  23. x-title-i18n:
  24. en-US: Consumer List
  25. description: 服务调用方列表,用于对请求进行认证
  26. x-description-i18n:
  27. en-US: List of service consumers which will be used in request authentication
  28. items:
  29. type: object
  30. properties:
  31. name:
  32. type: string
  33. title: 名称
  34. x-title-i18n:
  35. en-US: Name
  36. description: 该调用方的名称
  37. x-description-i18n:
  38. en-US: The name of the consumer
  39. # Data validation shall be implemented according JSON Schema Validation Spec
  40. # Following values are supported:
  41. # - maximum
  42. # - minimum
  43. # - maxLength
  44. # - minLength
  45. # - pattern
  46. # - maxItems
  47. # - minItems
  48. # - required
  49. minLength: 6 # Minimum length for data validation
  50. maxLength: 256 # Maximum length for data validation
  51. pattern: “^$ # Regular experssion for data validation
  52. example:
  53. - consumer1
  54. credential:
  55. type: string
  56. title: 访问凭证
  57. x-title-i18n:
  58. en-US: Credential
  59. description: 该调用方的访问凭证
  60. x-description-i18n:
  61. en-US: The credential of the consumer
  62. example:
  63. - admin:123456
  64. required:
  65. - name
  66. - credential
  67. allow:
  68. type: array
  69. title: 授权访问的调用方列表
  70. x-title-i18n:
  71. en-US: Allowed Consumers
  72. description: 对于匹配上述条件的请求,允许访问的调用方列表
  73. x-description-i18n:
  74. en-US: Consumers to be allowed for matched requests
  75. items:
  76. type: string
  77. example:
  78. - consumer1
  79. required:
  80. - allow
  81. - consumers
  82. example:
  83. consumers:
  84. - name: consumer1
  85. credential: admin:123456
  86. - name: consumer2
  87. credential: guest:abc
  88. allow:
  89. - consumer2

4. How to Build an Image

  1. Start the builder container from the Higress root folder
  1. GO_VERSION=”1.19
  2. TINYGO_VERSION=”0.28.1
  3. ORAS_VERSION=”1.0.0
  4. PLUGIN_NAME=”hello-world
  5. BUILDER_IMAGE=”higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/wasm-go-builder:go${GO_VERSION}-tinygo${TINYGO_VERSION}-oras${ORAS_VERSION}”
  6. 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}
  2. go mod tidy
  3. tinygo build -o ./plugin.wasm -scheduler=none -target=wasi -gc=custom -tags=’custommalloc nottinygc_finalizer ./main.go
  1. Build and push an OCI image
  1. tar czvf plugin.tar.gz plugin.wasm
  2. IMAGE_REGISTRY_SERVICE=docker.io
  3. IMAGE_REPOSITORY=”${IMAGE_REGISTRY_SERVICE}/plugins/${PLUGIN_NAME}”
  4. IMAGE_TAG=”v0.0.1
  5. oras login ${IMAGE_REGISTRY_SERVICE}
  6. oras push ${IMAGE_REPOSITORY}:${IMAGE_TAG} \
  7. ./spec.yaml:application/vnd.module.wasm.spec.v1+yaml \
  8. ./README.md:application/vnd.module.wasm.doc.v1+markdown \
  9. ./README_EN.md:application/vnd.module.wasm.doc.v1.en+markdown \
  10. ./plugin.tar.gz:application/vnd.oci.image.layer.v1.tar+gzip

5. Appendix

5.1 Default Icon for Each Plugin Category