Add docs for Wasm Sandbox

[phlax]

description

We have a sandbox to demonstrate creating a Wasm filter, but it doesnt currently have any documentation

[htuch]

@phlax should I assign this to you?

[phlax]

yep, im happy to do this

[phlax]

@htuch the immediate problem i hit with this is that the wasm build expects bazel and i guess a working build environment.

im thinking the sandbox should ideally not depend on this - and if it does it would want to do the build inside a container (like for building grpc protos eg)

im wondering if there is an easy way to compile the .cc file in the sandbox to wasm with minimal build deps

[phlax]

this seems an option https://docs.bazel.build/versions/master/bazel-container.html - but its not a small image

[phlax]

i tried compiling the wasm bin - first using the default bazel image - which didnt get very far

https://travis-ci.org/github/phlax/bazeldev/builds/736657571#L244

and then using ./ci/run_envoy_docker.sh ... which seems to get further, but fails for some other reason:

https://travis-ci.org/github/phlax/bazeldev/builds/736662127#L1007

[mattklein123]

@PiotrSikora can you potentially advise on ^? Perhaps we can come up with some type of self contained example that doesn't use Bazel and just a very basic make/cmake setup?

[PiotrSikora]

@phlax are you talking about building Wasm extensions?

For C++ examples using standard tools (i.e. not Bazel), you can take a look at:
https://github.com/dengyijia/WAF-wasm
Note that this was developed before it was merged into official repo, so the instructions are using Istio Proxy.

For C++ examples using Bazel, you can take a look at extensions in Istio Proxy:
https://github.com/istio/proxy/tree/master/extensions
I believe that @bianpengyuan is working on some documentation for that.

For Rust examples using standard tools, you can take a look at examples in Proxy-Wasm Rust SDK:
https://github.com/proxy-wasm/proxy-wasm-rust-sdk/tree/master/examples
and there are already some helpful articles from the community about building Proxy-Wasm extensions:
https://antweiss.com/blog/extending-envoy-with-wasm-and-rust/
https://blog.red-badger.com/extending-istio-with-rust-and-webassembly

[phlax]

@phlax are you talking about building Wasm extensions?

yep, compiling this file (https://github.com/envoyproxy/envoy/blob/master/examples/wasm/envoy_filter_http_wasm_example.cc) before running the sandbox with the compiled file

i guess we need to build it in a container as we want something that will take at most 1 or 2 commands to build, and doesnt expect much from users env

after thinking about it, i reckon using bazel is fine - probs better as that is how Envoy builds everything else

i didnt try too hard to get the container builds above working - but probs we need to use the (huge) envoy build image, or at least a bazel build container

[PiotrSikora]

For that example, you can simply build it with:

bazel build //examples/wasm:envoy_filter_http_wasm_example.wasm

but that's a specific example within Envoy repository, and it's not how people should be developing extensions, so that's not a great base for developer documentation, IMHO. For that, see my previous comment.

[phlax]

the thing is that it is just for a sandbox - ie a single page of docs with a really simple setup to get started

we definitely dont want to expect that users have bazel/llvm/etc available natively (if we did, we would need to document exactly how they can do that in a multi-platform way)

it's not how people should be developing extensions

yep - its a simple example to get people started running with a wasm extension - compiliing it is kinda more than we might hope to be strictly necessary

[phlax]

in terms of comparisons with existing sandboxes - i think compiling the grpc protocol stubs is the closest to what we need here:

https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/grpc_bridge#step-3-generate-the-protocol-stubs

[phlax]

providing a pre-compiled binary is also an option i guess

[PiotrSikora]

For that example, you can simply build it with:

bazel build //examples/wasm:envoy_filter_http_wasm_example.wasm

...once #13619 is merged.

[phlax]

brilliant, thankyou!

[PiotrSikora]

If it's not about building Wasm extensions, but only about running them, then I think that using the existing examples/wasm/envoy_filter_http_wasm_example.wasm module that's already checked in is perfectly fine.

[phlax]

using the existing examples/wasm/envoy_filter_http_wasm_example.wasm module that's already checked in is perfectly fine.

i couldnt find any compiled module (with find . -name "*.wasm")

[phlax]

if i can get the build to work - this should be good - ill PR som wip sandbox docs in the next day or two

[PiotrSikora]

Ah, right. I must have generated it previously and it just stuck around. Once #13619 is merged, it's one-line to build it, though.

[phlax]

i tested building with the bazel and envoy-build images

the envoy-build image works - so i can use that i reckon

i tried again with the bazel image and got the (same) following error:

ERROR: /.cache/bazel/_bazel_2000/a08c2e4811c846650b733c6fc815a920/external/proxy_wasm_cpp_sdk/BUILD:21:11: C++ compilation of rule '@proxy_wasm_cpp_sdk//:proxy_wasm_intrinsics' failed (Exit 1) emcc.sh failed: error executing command external/proxy_wasm_cpp_sdk/toolchain/emcc.sh -MD -MF bazel-out/wasm32-fastbuild-ST-4d26de33ce28/bin/external/proxy_wasm_cpp_sdk/_objs/proxy_wasm_intrinsics/proxy_wasm_intrinsics.d ... (remaining 17 argument(s) skipped)

test is here - https://travis-ci.org/github/phlax/bazeldev/builds/736783158#L246

it might well be to do with how i am trying to call it - the commands are:

git clone -b fix_wasm_example https://github.com/PiotrSikora/envoy
mkdir build_output
mkdir cache
docker run \
      -e USER="$(id -u)" \
      -u="$(id -u)" \
      -v $(pwd)/envoy:/src/workspace \
      -v $(pwd)/cache:/.cache \
      -v $(pwd)/build_output:/tmp/build_output \
      -w /src/workspace \
     l.gcr.io/google/bazel:3.4.1 \
     build //examples/wasm:envoy_filter_http_wasm_example.wasm

for the docs im thinking we can provide a download and some instructions to rebuild the module

i can create something now i have it working

[PiotrSikora]

I don't think you can build Envoy or Wasm extensions using Bazel's official container, since it's missing a bunch of build tools.

How about using what's already provided in Envoy?

./ci/run_envoy_docker.sh 'bazel build //examples/wasm:envoy_filter_http_wasm_example.wasm'

[phlax]

How about using what's already provided in Envoy?

yep that works, it just involves a ~4GB image, which i was trying to avoid

[phlax]

i think the other reason im averse to running the ./ci/run_envoy_docker.sh script locally is that it runs ~privileged with /var/run/docker.sock mounted and a lot of software inside - even when those things arent needed

i think its ok for CI - but better avoided for local use, unless you understand what it is doing

for the example i have created a docker-compose with the ubuntu-build-image and just the source dir mounted etc - should work