diff --git a/docs/en/docs/WasmEngine/figures/WasmEngine-arch.png b/docs/en/docs/WasmEngine/figures/WasmEngine-arch.png new file mode 100644 index 0000000000000000000000000000000000000000..e29f5a6efe84c2254f3679c300e07ad3cfdda0db Binary files /dev/null and b/docs/en/docs/WasmEngine/figures/WasmEngine-arch.png differ diff --git a/docs/en/docs/WasmEngine/figures/icon-note.gif b/docs/en/docs/WasmEngine/figures/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/docs/en/docs/WasmEngine/figures/icon-note.gif differ diff --git a/docs/en/docs/WasmEngine/installation-and-deployment.md b/docs/en/docs/WasmEngine/installation-and-deployment.md new file mode 100644 index 0000000000000000000000000000000000000000..d2627e8f006590168c6696b8c60761fd605081ea --- /dev/null +++ b/docs/en/docs/WasmEngine/installation-and-deployment.md @@ -0,0 +1,324 @@ +# WasmEngine + +## Overview + +WasmEngine is a lightweight WebAssembly function engine. Based on the WebAssembly sandbox-level security isolation model, it provides high-concurrency function execution and millisecond-level function extremely fast cold start capabilities. + +**WasmEngine Architecture Diagram** + +![wasm-engine-arch](./figures/WasmEngine-arch.png) + + +## Interface Description + +The popular FaaS framework in the industry generally uses the Restful API interface of the HTTP protocol to connect to the function execution engine on the backend. The function calls the functional interface. + +The detailed interface definition is as follows: + +**deploy function deployment interface** + +- HTTP request type: POST +- URL link: /function/deploy +- Input parameters: JSON format, {function_name: String, function_image: String, wasi_cap: bool} +- Return value: HTTP status code and message content or operation error failure information + +**delete delete function interface** + +- HTTP request type: POST +- URL link: /function/delete +- Input parameters: JSON format, {function_name: String} +- Return value: HTTP status code and message content or operation error failure information + +**list query all function interfaces** + +- HTTP request type: GET +- URL link: /function/list +- Input parameters: not involved +- Return value: HTTP status code and message content, where the message content includes a list of all deployed functions on the node or error information about query failure + + **query function query interface** + +- HTTP request type: POST +- URL link: /function/query +- Input parameters: JSON format, {function_name: String} +- Return value: HTTP status code and message content, where the message content includes the details of the query function or failure error information + +**query function query interface** + +- HTTP request type: POST +- URL link: /function/invoke +- Input parameters: JSON format, {function_name: String, args: HashMap}, in which args stores the function parameter kv format is almost correct, for the function parameter type without key type, the default value is taken from the value value as parameter +- Return value: HTTP status code and message content, where the message content includes the details of the query function or failure error information + + +## Install + +### Environment preparation + +To ensure the successful installation of WasmEngine, the following software and hardware requirements must be met. + +- Supported machine architectures: x86_64 and aarch64 +- Supported OS: openEuler +- The user has root privileges. + +### Install WasmEngine + +**Method 1: Install using yum (recommended)** + +1. Configure the openEuler yum source. + +2. Log in to the target server and install WasmEngine. + + ```` + sudo yum install -y WasmEngine + ```` + +**Method 2: Install using rpm package** + +1. Obtain the installation package WasmEngine-*.rpm corresponding to WasmEngine from the openEuler yum source. + +2. Upload the obtained rpm package to any directory of the target server, such as /home/. + +3. Log in to the target server with root privileges, and install WasmEngine by referring to the following commands. + + ```` + sudo rpm -ivh /home/WasmEngine-*.rpm + ```` + +**Method 3: source code compilation and installation** + +WasmEngine is developed in Rust language, so it relies on the compilation tool chain of Rust language for compilation and construction. + +**Rust locale installation** +* Rust openEuler22.03-LTS installation: `yum install -y cargo rust` +* Or you can refer to the official documentation to install: [Official documentation description](https://www.rust-lang.org/tools/install) + +**WasmEngine Compilation** + +```bash +$ cd WasmEngine + +$ cargo build --release + Compiling libc v0.2.126 + Compiling proc-macro2 v1.0.36 + Compiling unicode-xid v0.2.2 + Compiling syn v1.0.84 + Compiling cfg-if v1.0.0 + ... + Finished release [optimized] target(s) in 3m 41s + +# The path where the compiled binary files are stored is as follows +$ ls target/release/ +build deps examples incremental libwasm_engine.d libwasm_engine.rlib wasm_engine wasm_engine.d +```` + +## Instructions + +1. Launch the WasmEngine application in a terminal + +```bash +# The wasm_engine application requires root privileges to execute +$ su root + +# Set crate and log level for RUST_LOG output +$ export RUST_LOG=wasm_engine=debug + +# wasm_engine listens on port 10000 of the host by default +$ ./wasm_engine +2022-07-28T12:32:10.007200Z INFO wasm_engine::function_store::local_store: no persist json file exist, restore end +2022-07-28T12:32:10.007255Z INFO wasm_engine: WasmEngine listening on http://0.0.0.0:10000, waiting for request... +```` + +2. The next step is to package the compiled Wasm function binary file into a container image format, upload it to the function image repository, and wait for the WasmEngine to be pulled when it is deployed. + +For the production method of the Wasm function mirror, please refer to the introduction in the **Wasm function mirror production** section below. + +3. WasmEngine provides Restful API interface description + +The following uses the `authentication` and `hello` functions as examples to introduce the deployment, query, deletion, and invocation of functions using the curl command. + +**Deploy the authentication function** +```bash +$ curl --location --request POST 'localhost:10000/function/deploy' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "authentication", + "function_image": "127.0.0.1:5000/authentication-wasm:latest", + "wasi_cap": false +}' + +status code: 200, message: deploy function authentication successfully! +```` + +**Deploy the hello function** +```bash +$ curl --location --request POST 'localhost:10000/function/deploy' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "hello", + "function_image": "127.0.0.1:5000/hello-wasm:latest", + "wasi_cap": true +}' + +status code: 200, message: deploy function hello successfully! +```` + +**Query all deployed functions** +```bash +$ curl --location --request GET 'localhost:10000/function/list' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' + +status code: 200, message: all deployed function info: [{func_name: authentication, func_image_name: 127.0.0.1:5000/authentication-wasm:latest, wasi_cap: false}, {func_name: hello, func_image_name: 127.0.0.1:5000/ hello-wasm:latest, wasi_cap: true}] +```` + +**Query authentication function information** +```bash +$ curl --location --request POST 'localhost:10000/function/query' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "authentication" +}' +status code: 200, message: queried function info: FunctionEntry { func_name: "authentication", func_image_name: "127.0.0.1:5000/authentication-wasm:latest", func_local_path: "/var/lib/wasmengine/functions/authentication/authentication .wasm", wasi_cap: false } +```` + +**Call the authentication function** +```bash +$ curl --location --request POST 'localhost:10000/function/invoke' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "authentication", + "args": {"arg_uri": "https://abcd.com/uzid", "arg_body": "sun", "arg_secret": "755d0845dbc22b3ac376ae73c82996b7"} +}' + +status code: 200, message: {"status":"403","body":"

Auth Pass!

hash 755d0845dbc22b3ac376ae73c82996b7

"} +```` + +**Remove the deployed hello function** +```bash +$ curl --location --request POST 'localhost:10000/function/delete' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "hello" +}' + +status code: 200, message: delete function hello successfull! +```` + +## Wasm function image + +The Wasm function loaded and run by WasmEngine also needs the management and distribution capabilities similar to container images. Therefore, WasmEngine reuses the unified management and distribution capabilities of the container image repository. The developer makes the Wasm function into a container image, and WasmEngine pulls it from the remote image repository. . + +Developers can build container images through isula build or docker build container image building tools on openEuler. + +### Wasm application compilation + +**Rust Wasm compilation toolchain installation** + +The Rust compilation toolchain supports compilation into wasm-related target target formats: + +```bash +rustup target list | grep wasm +wasm32-unknown-emscripten +wasm32-unknown-unknown +wasm32-wasi +```` + +The difference between these three different target target formats: +- wasm32-unknown-emscripten: In Emscripten mode, the code is compiled into a wasm application through the Emscripten compilation tool chain emcc, and the wasm application will also rely on the abi interface provided by Emscripten through import, which is usually used in browser scenarios +- wasm32-unknown-unknown: Wasm standard mode, wasm standard format with no external dependencies at all, does not depend on external interface capabilities through import, usually only has numerical computing capabilities +- wasm32-wasi: WASI mode, wasm applications import externally dependent wasi interface capabilities through import, and through wasm interfaces, wasm applications have file directory operations, network connections and other expansion capabilities + +In server scenarios, only two target formats, `wasm32-unknown-unknown` and `wasm32-wasi`, are currently supported. + +The specific installation method is as follows: +```bash +$ rustup target add wasm32-unknown-unknown wasm32-wasi + +# After the installation is complete, there will be an (installed) mark after the corresponding target +$ rustup target list | grep wasm +wasm32-unknown-emscripten +wasm32-unknown-unknown (installed) +wasm32-wasi (installed) +```` + +**Compile the function samples given in the experiments directory** + +```bash +# Compile the sample function given in the experiments directory +$ make apps + +Building: fibonacci + Finished release [optimized] target(s) in 0.00s +Building: hello + Finished release [optimized] target(s) in 0.00s +Building: authentication + Finished release [optimized] target(s) in 0.28s +Building: authentication-wasi + Finished release [optimized] target(s) in 0.00s +```` + +After the compilation is complete, you can find the generated wasm function in the target directory under the source code directory of each function in experiments/application. + +For example, the wasm file path generated by `authentication` function compilation is `experiments/application/authentication/target/wasm32-unknown-unknown/release/authentication.wasm` + +**Manually compile the function** + +Enter the experiments/application directory, or the function directory you implemented yourself, and execute the following command to compile the function: +```bash +# for wasi +cargo build --release --target=wasm32-wasi +# for wasm +cargo rustc --release --target=wasm32-unknown-unknown -- -C target-feature=+multivalue +```` + +### Package function image + +1. Create an empty directory and copy the wasm format application file generated in the previous step to the empty directory +```bash +$ mkdir build && cd build +$ cp target/wasm32-unknown-unknown/release/authentication.wasm . +```` +2. Write the Dockerfile required for container image construction, as follows +```bash +$ cat Dockerfile +FROM scratch +ADD authentication.wasm/ +```` +3. Compile and build the Wasm container image +```bash +$ sudo docker build --tag 127.0.0.1:5000/authentication-wasm:latest . +Sending build context to Docker daemon 1.787MB +Step 1/2 : FROM scratch + ---> +Step 2/2 : ADD authentication.wasm / + ---> 897a9e7a1ce6 +Successfully built 897a9e7a1ce6 +Successfully tagged 127.0.0.1:5000/authentication-wasm:latest +```` +4. Push the container image to the container image repository + +If used for local development verification, developers can start a container registry service locally through the `registry` image. +```bash +$ sudo docker run -itd -p 5000:5000 --restart=always --name registry registry:latest +```` + +Push the container image to the container image repository: +```bash +$ sudo docker push 127.0.0.1:5000/authentication-wasm:latest +The push refers to repository [127.0.0.1:5000/authentication-wasm] +720b9e537c85: Pushed +v2: digest: sha256:a7b8e58e4b9c2abba6a39636dbc904e01c4cfa7e1d4cc6a97f8e955e148af41e size: 527 +```` + +## Precautions +- The Wasm target format needs to meet the official WebAssembly Spec 1.0 standard +- If the application requires WASI interface capability support, only the Wasm files compiled and generated by wasm32-unknown-wasi compilation tool chain of wasm32-unknown-wasi in Rust language are supported +- Does not support setting resource quotas per function call +- Only supports single function running model, does not support calling model between functions +- Only one wasm format module file is allowed in a Wasm function image \ No newline at end of file diff --git a/docs/en/docs/WasmEngine/overview.md b/docs/en/docs/WasmEngine/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..04ade34c14ae7ed011dae9140058bf4fa17102c7 --- /dev/null +++ b/docs/en/docs/WasmEngine/overview.md @@ -0,0 +1,3 @@ +# WasmEngine User Guide + +This document introduces how to use the WasmEngine lightweight WebAssembly function engine, and introduces the generation method of the Wasm function image. \ No newline at end of file diff --git a/docs/en/menu/index.md b/docs/en/menu/index.md index 43140e2faa2bc270b5cfea52c98eb41f51274078..ae0a25e5909c316c45ef3e72e584c37137dc80d2 100644 --- a/docs/en/menu/index.md +++ b/docs/en/menu/index.md @@ -222,4 +222,6 @@ headless: true - [NestOS User Guide]({{< relref "./docs/NestOS/overview.md" >}}) - [Installation and Deployment]({{< relref "./docs/NestOS/installation-and-deployment.md" >}}) - [Setting Up Kubernetes and iSulad]({{< relref "./docs/NestOS/usage.md" >}}) - - [Feature Description]({{< relref "./docs/NestOS/feature-description.md" >}}) \ No newline at end of file + - [Feature Description]({{< relref "./docs/NestOS/feature-description.md" >}}) +- [WasmEngine User Guide]({{< relref "./docs/WasmEngine/overview.md" >}}) + - [Installation and Deployment]({{< relref "./docs/WasmEngine/installation-and-deployment.md" >}}) \ No newline at end of file diff --git a/docs/zh/docs/WasmEngine/figures/WasmEngine-arch.png b/docs/zh/docs/WasmEngine/figures/WasmEngine-arch.png new file mode 100644 index 0000000000000000000000000000000000000000..e29f5a6efe84c2254f3679c300e07ad3cfdda0db Binary files /dev/null and b/docs/zh/docs/WasmEngine/figures/WasmEngine-arch.png differ diff --git a/docs/zh/docs/WasmEngine/figures/icon-note.gif b/docs/zh/docs/WasmEngine/figures/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/docs/zh/docs/WasmEngine/figures/icon-note.gif differ diff --git a/docs/zh/docs/WasmEngine/overview.md b/docs/zh/docs/WasmEngine/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..6a573de2894e6138c77b211caf54779f3e5cfc01 --- /dev/null +++ b/docs/zh/docs/WasmEngine/overview.md @@ -0,0 +1,3 @@ +# WasmEngine 使用指南 + +本文档介绍如何使用 WasmEngine 轻量级WebAssembly函数引擎,并介绍Wasm函数镜像的生成方法。 \ No newline at end of file diff --git "a/docs/zh/docs/WasmEngine/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" "b/docs/zh/docs/WasmEngine/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" new file mode 100644 index 0000000000000000000000000000000000000000..03e6492bb0dc0c4adea154fdd3d75d6268e64f13 --- /dev/null +++ "b/docs/zh/docs/WasmEngine/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" @@ -0,0 +1,330 @@ +# WasmEngine + +## 概述 + +WasmEngine是一个轻量级的WebAssembly函数引擎,基于WebAssembly沙箱级安全隔离模型,提供高并发函数执行、毫秒级函数极速冷启动能力。 + +**WasmEngine架构图** + +![wasm-engine-arch](./figures/WasmEngine-arch.png) + + +## 接口说明 + +业界流行的FaaS框架一般采用HTTP协议的Restful的API接口,对接后端的函数执行引擎,WasmEngine引擎也采用类似方案,提供了一组Restful风格的faas-provider API接口,提供函数的增删改查功能以及函数调用功能接口。 + +详细的接口定义如下: + +**deploy函数部署接口** + +- HTTP 请求类型:POST +- URL链接:/function/deploy +- 输入参数:JSON格式,{function_name: String, function_image: String, wasi_cap: bool} +- 返回值:HTTP的状态码和消息内容或操作错误失败信息 + +**delete删除函数接口** + +- HTTP请求类型:POST +- URL链接:/function/delete +- 输入参数:JSON格式,{function_name: String} +- 返回值:HTTP的状态码和消息内容或操作错误失败信息 + +**list查询所有函数接口** + +- HTTP请求类型:GET +- URL链接:/function/list +- 输入参数:不涉及 +- 返回值:HTTP的状态码和消息内容,其中消息内容包括所有已部署到节点上的函数列表或查询失败的错误信息 + + **query函数查询接口** + +- HTTP请求类型:POST +- URL链接:/function/query +- 输入参数:JSON格式,{function_name: String} +- 返回值:HTTP的状态码和消息内容,其中消息内容包括查询函数的详细信息或失败错误信息 + +**query函数查询接口** + +- HTTP请求类型:POST +- URL链接:/function/invoke +- 输入参数:JSON格式,{function_name: String, args: HashMap},其中args中存放的是函数参数kv形式的简直对,对于无key类型的函数参数类型,默认从value中取值作为参数 +- 返回值:HTTP的状态码和消息内容,其中消息内容包括查询函数的详细信息或失败错误信息 + + +## 安装 + +### 环境准备 + +为了确保WasmEngine成功安装,需满足以下软件硬件要求。 + +- 支持的机器架构:x86_64 和 aarch64 +- 支持的操作系统:openEuler +- 用户具有root权限。 + +### 安装WasmEngine + +**方法一:使用yum安装(推荐)** + +1. 配置openEuler yum源。 + +2. 登录目标服务器,安装WasmEngine。 + + ``` + sudo yum install -y WasmEngine + ``` + +**方法二:使用rpm包安装** + +1. 从openEuler yum源中获取WasmEngine对应安装包WasmEngine-*.rpm。 + +2. 将获取的rpm软件包上传至目标服务器的任一目录,例如 /home/。 + +3. 使用root权限,登录目标服务器,参考如下命令安装WasmEngine。 + + ``` + sudo rpm -ivh /home/WasmEngine-*.rpm + ``` + +**方法三:源码编译安装** + +WasmEngine采用Rust语言开发,因此依赖于Rust语言的编译工具链进行编译构建。 + +**Rust语言环境安装** +* Rust openEuler22.03-LTS安装: `yum install -y cargo rust` +* 或可参考官方文档安装:[官方文档说明](https://www.rust-lang.org/tools/install) + +**WasmEngine编译** + +```bash +$ cd WasmEngine + +$ cargo build --release + Compiling libc v0.2.126 + Compiling proc-macro2 v1.0.36 + Compiling unicode-xid v0.2.2 + Compiling syn v1.0.84 + Compiling cfg-if v1.0.0 + ... + Finished release [optimized] target(s) in 3m 41s + +# 编译生成的二进制文件存放的路径如下 +$ ls target/release/ +build deps examples incremental libwasm_engine.d libwasm_engine.rlib wasm_engine wasm_engine.d +``` + + + + +## 使用说明 + +1. 在一个终端中启动WasmEngine应用 + +```bash +# wasm_engine应用需要root权限才能执行 +$ su root + +# 设置RUST_LOG输出的crate和日志级别 +$ export RUST_LOG=wasm_engine=debug + +# wasm_engine默认监听在主机的10000端口上 +$ ./wasm_engine +2022-07-28T12:32:10.007200Z INFO wasm_engine::function_store::local_store: no persist json file exist, restore end +2022-07-28T12:32:10.007255Z INFO wasm_engine: WasmEngine listening on http://0.0.0.0:10000, waiting for request... +``` + + + +2. 接下来就是将编译生成的Wasm函数二进制文件打包成容器镜像格式,并上传到函数镜像仓库中,等待WasmEngine部署时进行拉取。 + + Wasm函数镜像的制作方法,可以参考下面**Wasm 函数镜像制作**小节的介绍说明。 + +3. WasmEngine 提供Restful API接口说明 + +下面以`authentication`和`hello`函数为例,使用curl命令进行函数部署、查询、删除、调用的介绍。 + +**部署authentication函数** +```bash +$ curl --location --request POST 'localhost:10000/function/deploy' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "authentication", + "function_image": "127.0.0.1:5000/authentication-wasm:latest", + "wasi_cap": false +}' + +status code: 200, message: deploy function authentication successfully! +``` + +**部署hello函数** +```bash +$ curl --location --request POST 'localhost:10000/function/deploy' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "hello", + "function_image": "127.0.0.1:5000/hello-wasm:latest", + "wasi_cap": true +}' + +status code: 200, message: deploy function hello successfully! +``` + +**查询全部已部署函数** +```bash +$ curl --location --request GET 'localhost:10000/function/list' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' + +status code: 200, message: all deployed function info: [{func_name: authentication, func_image_name: 127.0.0.1:5000/authentication-wasm:latest, wasi_cap: false}, {func_name: hello, func_image_name: 127.0.0.1:5000/hello-wasm:latest, wasi_cap: true}] +``` + +**查询authentication函数信息** +```bash +$ curl --location --request POST 'localhost:10000/function/query' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "authentication" +}' +status code: 200, message: queried function info: FunctionEntry { func_name: "authentication", func_image_name: "127.0.0.1:5000/authentication-wasm:latest", func_local_path: "/var/lib/wasmengine/functions/authentication/authentication.wasm", wasi_cap: false } +``` + +**调用authentication函数** +```bash +$ curl --location --request POST 'localhost:10000/function/invoke' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "authentication", + "args": {"arg_uri": "https://abcd.com/uzid", "arg_body": "sun", "arg_secret": "755d0845dbc22b3ac376ae73c82996b7"} +}' + +status code: 200, message: {"status":"403","body":"

Auth Pass!

hash 755d0845dbc22b3ac376ae73c82996b7

"} +``` + +**删除已部署的hello函数** +```bash +$ curl --location --request POST 'localhost:10000/function/delete' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "function_name": "hello" +}' + +status code: 200, message: delete function hello successfull! +``` + + +## Wasm 函数镜像制作 + +WasmEngine加载运行的Wasm函数同样需要类似容器镜像的管理和分发能力,因此WasmEngine复用了容器镜像仓库统一管理和分发的能力,开发者将Wasm函数制作成容器镜像,WasmEngine从远端镜像仓库拉取。 + +开发者可以通过openEuler上的isula build或者docker build容器镜像构建工具来进行容器镜像构建。 + +### Wasm应用编译 + +**Rust Wasm编译工具链安装** + +Rust编译工具链支持编译成wasm相关的target目标格式有: + +```bash +rustup target list | grep wasm +wasm32-unknown-emscripten +wasm32-unknown-unknown +wasm32-wasi +``` + +这三种不同target目标格式的区别: +- wasm32-unknown-emscripten:Emscripten模式,通过Emscripten编译工具链emcc将代码编译成wasm应用,其中wasm应用中也会通过import的方式依赖于Emscripten提供的abi接口,通常用于浏览器场景 +- wasm32-unknown-unknown:Wasm标准模式,完全没有外部依赖的wasm标准格式,不会通过import依赖外部接口能力,通常只具有数值计算能力 +- wasm32-wasi:WASI模式,wasm应用通过import导入外部依赖的wasi接口能力,通过wasi接口,wasm应用具有文件目录操作、网络连接等这些扩展能力 + +在服务器场景下,当前只支持`wasm32-unknown-unknown`和`wasm32-wasi`这两种目标格式。 + +具体的安装方法如下: +```bash +$ rustup target add wasm32-unknown-unknown wasm32-wasi + +# 安装完成之后,对应target之后会有(installed)标识 +$ rustup target list | grep wasm +wasm32-unknown-emscripten +wasm32-unknown-unknown (installed) +wasm32-wasi (installed) +``` + +**编译experiments目录中给定的函数样例** + +```bash +# 编译experiments目录中给定的函数样例 +$ make apps + +Building: fibonacci + Finished release [optimized] target(s) in 0.00s +Building: hello + Finished release [optimized] target(s) in 0.00s +Building: authentication + Finished release [optimized] target(s) in 0.28s +Building: authentication-wasi + Finished release [optimized] target(s) in 0.00s +``` + +编译完成之后,就可以在experiments/application的各个函数源码目录下面的target目录下找到生成的wasm函数。 + +例如,`authentication`函数编译生成的wasm文件路径为`experiments/application/authentication/target/wasm32-unknown-unknown/release/authentication.wasm` + +**手动编译函数** + +进入experiments/application目录,或自己实现的函数目录下,执行如下命令编译函数: +```bash +# for wasi +cargo build --release --target=wasm32-wasi +# for wasm +cargo rustc --release --target=wasm32-unknown-unknown -- -C target-feature=+multivalue +``` + +### 打包函数镜像 + +1. 创建一个空的目录,将上一步生成的wasm格式应用文件拷贝到该空目录中 +```bash +$ mkdir build && cd build +$ cp target/wasm32-unknown-unknown/release/authentication.wasm . +``` +2. 编写容器镜像构建所需的Dockerfile,内容如下 +```bash +$ cat Dockerfile +FROM scratch +ADD authentication.wasm / +``` +3. 执行Wasm容器镜像编译构建 +```bash +$ sudo docker build --tag 127.0.0.1:5000/authentication-wasm:latest . +Sending build context to Docker daemon 1.787MB +Step 1/2 : FROM scratch + ---> +Step 2/2 : ADD authentication.wasm / + ---> 897a9e7a1ce6 +Successfully built 897a9e7a1ce6 +Successfully tagged 127.0.0.1:5000/authentication-wasm:latest +``` +4. 将容器镜像push到容器镜像仓库 + +如果用于本地开发验证,开发者可以通过`registry`镜像在本地启动一个容器镜像仓库服务。 +```bash +$ sudo docker run -itd -p 5000:5000 --restart=always --name registry registry:latest +``` + +push容器镜像到容器镜像仓库: +```bash +$ sudo docker push 127.0.0.1:5000/authentication-wasm:latest +The push refers to repository [127.0.0.1:5000/authentication-wasm] +720b9e537c85: Pushed +v2: digest: sha256:a7b8e58e4b9c2abba6a39636dbc904e01c4cfa7e1d4cc6a97f8e955e148af41e size: 527 +``` + +## 注意事项 +- Wasm目标格式需要满足WebAssembly Spec 1.0正式标准 +- 如果应用程序需要WASI接口能力支持,只支持通过wasi-sdk或Rust语言的wasm32-unknown-wasi编译工具链编译生成的Wasm文件 +- 不支持设置每个函数调用的资源限额 +- 只支持单函数运行模型,不支持函数间调用模型 +- 一个Wasm函数镜像中只允许有一个wasm格式模块文件 diff --git a/docs/zh/menu/index.md b/docs/zh/menu/index.md index ba9380147fba7b77e4cd01dee734b628e6891dc8..dac22055dbf72fe016e571cc8ff725af3e2dd7bb 100644 --- a/docs/zh/menu/index.md +++ b/docs/zh/menu/index.md @@ -222,3 +222,5 @@ headless: true - [安装与部署]({{< relref "./docs/NestOS/安装与部署.md" >}}) - [使用方法]({{< relref "./docs/NestOS/使用方法.md" >}}) - [功能特性描述]({{< relref "./docs/NestOS/功能特性描述.md" >}}) +- [WasmEngine用户指南]({{< relref "./docs/WasmEngine/overview.md" >}}) + - [安装与部署]({{< relref "./docs/WasmEngine/安装与部署.md" >}})