From cdcfe24a3d3a7ee5bb74213b863898616b614725 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=82=9F=E7=A9=BA?= Date: Tue, 14 Feb 2023 09:59:33 +0800 Subject: [PATCH] feat: add Makefile for building wasm-go easier (#184) --- plugins/wasm-go/DockerfileBuilder | 40 ++++++++++++++++++ plugins/wasm-go/Makefile | 20 +++++++++ plugins/wasm-go/README.md | 67 +++++++++++++++++++++++++------ plugins/wasm-go/go.mod | 2 +- 4 files changed, 116 insertions(+), 13 deletions(-) create mode 100644 plugins/wasm-go/DockerfileBuilder create mode 100644 plugins/wasm-go/Makefile diff --git a/plugins/wasm-go/DockerfileBuilder b/plugins/wasm-go/DockerfileBuilder new file mode 100644 index 000000000..78064ddeb --- /dev/null +++ b/plugins/wasm-go/DockerfileBuilder @@ -0,0 +1,40 @@ +FROM ubuntu as builder + +ARG THIS_ARCH +ARG PLUGIN_NAME +ARG GO_VERSION +ARG TINYGO_VERSION + +ARG this_arch=${THIS_ARCH:-amd64} +ARG plugin_name=${PLUGIN_NAME:-hello-world} +ARG go_version=${GO_VERSION:-1.19} +ARG tinygo_version=${TINYGO_VERSION:-0.26.0} + +ARG go_pkg_name=go$go_version.linux-$this_arch.tar.gz +ARG tinygo_pkg_name=tinygo_${tinygo_version}_$this_arch.deb + + +RUN apt-get update \ + && apt-get install -y wget build-essential \ + && rm -rf /var/lib/apt/lists/* + +RUN wget https://golang.google.cn/dl/$go_pkg_name +RUN rm -rf /usr/local/go && tar -C /usr/local -xzf $go_pkg_name +ENV PATH=$PATH:/usr/local/go/bin + +RUN wget https://github.com/tinygo-org/tinygo/releases/download/v$tinygo_version/$tinygo_pkg_name +RUN dpkg -i $tinygo_pkg_name +ENV export PATH=$PATH:/usr/local/bin + +WORKDIR /workspace + +COPY . . + +WORKDIR /workspace/extensions/$plugin_name + +RUN go mod tidy +RUN tinygo build -o /main.wasm -scheduler=none -target=wasi ./main.go + +FROM scratch + +COPY --from=builder /main.wasm plugin.wasm diff --git a/plugins/wasm-go/Makefile b/plugins/wasm-go/Makefile new file mode 100644 index 000000000..9904ac3cd --- /dev/null +++ b/plugins/wasm-go/Makefile @@ -0,0 +1,20 @@ +PLUGIN_NAME ?= hello-world +REGISTRY ?= +BUILD_TIME := $(shell date "+%Y%m%d-%H%M%S") +COMMIT_ID := $(shell git rev-parse --short HEAD 2>/dev/null) +IMG ?= ${REGISTRY}${PLUGIN_NAME}:${BUILD_TIME}-${COMMIT_ID} + +build: + DOCKER_BUILDKIT=1 docker build --build-arg PLUGIN_NAME=${PLUGIN_NAME} \ + --build-arg THIS_ARCH=${THIS_ARCH} \ + --build-arg GO_VERSION=${GO_VERSION} \ + --build-arg TINYGO_VERSION=${TINYGO_VERSION} \ + -t ${IMG} \ + -f DockerfileBuilder \ + --output extensions/${PLUGIN_NAME} . + @echo "" + @echo "image: ${IMG}" + @echo "output wasm file: extensions/${PLUGIN_NAME}/plugin.wasm" + +build-push: build + docker push ${IMG} \ No newline at end of file diff --git a/plugins/wasm-go/README.md b/plugins/wasm-go/README.md index 7046c9934..c9ba077ca 100644 --- a/plugins/wasm-go/README.md +++ b/plugins/wasm-go/README.md @@ -4,17 +4,57 @@ 此 SDK 用于开发 Higress 的 Wasm 插件 -## 编译环境要求 +## 使用 Docker 快速构建 -(需要支持 go 范型特性) +使用以下命令可以快速构建 wasm-go 插件: -Go 版本: >= 1.18 +```bash +$ PLUGIN_NAME=request-block make build +``` -TinyGo 版本: >= 0.25.0 +
+输出结果 +

+DOCKER_BUILDKIT=1 docker build --build-arg PLUGIN_NAME=request-block \
+                               --build-arg THIS_ARCH= \
+                               --build-arg GO_VERSION= \
+                               --build-arg TINYGO_VERSION= \
+                               -t request-block:20230213-170844-ca49714 \
+                               -f DockerfileBuilder \
+                               --output extensions/request-block .
+[+] Building 84.6s (16/16)                                                                                                                                                                                                                                                0.0s 
 
-## Quick Examples
+image:            request-block:20230211-184334-f402f86
+output wasm file: extensions/request-block/plugin.wasm
+
+
-使用 [request-block](extensions/request-block) 作为例子 +该命令最终构建出一个 wasm 文件和一个 Docker image。 +这个本地的 wasm 文件被输出到了指定的插件的目录下，可以直接用于调试。 +你也可以直接使用 `make build-push` 一并构建和推送 image. + +### 参数说明 + +| 参数名称 | 可选/必须 | 默认值 | 含义 | +|------------------|-------|------------------------------------------|----------------------------------------------------------------------| +| `THIS_ARCH` | 可选的 | amd64 | 构建插件的机器的指令集架构，在非 amd64 架构的机器上构建时要手动指定。 | +| `PLUGIN_NAME` | 可选的 | hello-world | 要构建的插件名称。 | +| `REGISTRY` | 可选的 | 空 | 生成的镜像的仓库地址，如 `example.registry.io/my-name/`. 注意 REGISTRY 值应当以 / 结尾。 | +| `IMG` | 可选的 | 如不设置则根据仓库地址、插件名称、构建时间以及 git commit id 生成 | 生成的镜像名称。 | +| `GO_VERSION` | 可选的 | 1.19 | Go 版本号。 | +| `TINYGO_VERSION` | 可选的 | 0.26.0 | TinyGo 版本号。 | + +## 本地构建 + +你也可以选择先在本地将 wasm 构建出来，再拷贝到 Docker 镜像中。这要求你要先在本地搭建构建环境。 + +编译环境要求如下： + +- Go 版本: >= 1.18 (需要支持范型特性) + +- TinyGo 版本: >= 0.25.0 + +下面是本地多步骤构建 [request-block](extensions/request-block) 的例子。 ### step1. 编译 wasm @@ -31,7 +71,9 @@ docker build -t /request-block:1.0.0 . docker push /request-block:1.0.0 ``` -### step3. 创建 WasmPlugin 资源 +## 创建 WasmPlugin 资源使插件生效 + +编写 WasmPlugin 资源如下： ```yaml apiVersion: extensions.higress.io/v1alpha1 @@ -46,10 +88,12 @@ spec: defaultConfig: block_urls: - "swagger.html" - url: oci:///request-block:1.0.0 + url: oci:///request-block:1.0.0 # 之前构建和推送的 image 地址 ``` -创建上述资源后，如果请求url携带 `swagger.html`, 则这个请求就会被拒绝，例如： +使用 `kubectl apply -f ` 使资源生效。 + +资源生效后，如果请求url携带 `swagger.html`, 则这个请求就会被拒绝，例如： ```bash curl /api/user/swagger.html @@ -66,7 +110,6 @@ content-length: 0 可以阅读此 [文档](https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/) 了解更多关于 wasmplugin 的配置 - ## 路由级或域名级生效 ```yaml @@ -78,7 +121,7 @@ metadata: spec: selector: matchLabels: - higress: higress-system-higress-gateway + higress: higress-system-higress-gateway defaultConfig: # 跟上面例子一样，这个配置会全局生效，但如果被下面规则匹配到，则会改为执行命中规则的配置 block_urls: @@ -108,5 +151,5 @@ spec: url: oci:///request-block:1.0.0 ``` -所有规则会按上面配置的顺序一次执行匹配，当有一个规则匹配时，就停止匹配，并选择匹配的配置执行插件逻辑 +所有规则会按上面配置的顺序一次执行匹配，当有一个规则匹配时，就停止匹配，并选择匹配的配置执行插件逻辑。 diff --git a/plugins/wasm-go/go.mod b/plugins/wasm-go/go.mod index 40820022c..9f2595053 100644 --- a/plugins/wasm-go/go.mod +++ b/plugins/wasm-go/go.mod @@ -1,6 +1,6 @@ module github.com/alibaba/higress/plugins/wasm-go -go 1.18 +go 1.19 require ( github.com/google/uuid v1.3.0