Skip to content

Latest commit

 

History

History
186 lines (132 loc) · 7.99 KB

README.md

File metadata and controls

186 lines (132 loc) · 7.99 KB
Raw




Proximal makes it easy to develop Proxy-WASM modules for Envoy right on your local machine (or anywhere you can run our Docker image).

TL;DR

Develop WebAssembly extensions for Envoy with ease. Try running docker run -p 8080:8080 -p 18000:18000 docker.io/apoxy/proximal:latest then visit http://localhost:8080

Demo:

proximal-demo.mp4

What is Proxy-WASM?

Proxy-WASM (WebAssembly) is a powerful technology that enables you to extend the functionality of modern proxies like Envoy with WebAssembly modules. By writing Proxy-WASM modules, you can write code in your L4/L7 proxy that inspects, mutates, and routes requests as they are passing through, all in a language-independent and sandboxed environment. It works with both HTTP and TCP-based connection and SDKs are available for Rust, Go, C++, and AssemblyScript (we're working on JavaScript and Python).

These standards based WebAssembly modules can be used with Istio, MOSN and APSIX as well.

Why Proximal?

Developing Proxy-WASM modules for Envoy traditionally involves cumbersome setups, complex toolchains, and time-consuming testing iterations, frequently on a remote environment. Proximal simplifies the development process and brings it to your local machine in a single process environment with a friendly UI and basic REST API.

We believe that developers have been held back from adopting this incredibly powerful technology because the developer experience for WASM and Proxy-WASM has been a little rough around the edges. Proximal is here to help.

Key Features:

  • Local Development: Forget about deploying to remote environments for every code change. Proximal allows you to develop and test your Proxy-WASM modules locally, saving you valuable time and effort. It features a workflow engine that compiles source code into WebAssembly binary (.wasm) and loads them into Envoy automatically.

  • Rapid Iterations: Change your code and see the results almost instantaneously. Proximal continuously watches a working directory (even Docker mounted volumes) and triggers a rebuild/reload of your module in Envoy automatically.

  • Simplified Setup + Examples: Setting up a development environment for Proxy-WASM can be daunting. Proximal streamlines the process and provides a few examples you can use to get started with minimal configuration.

  • Observability: Debugging is easier with integrated logs capture. See requests and responses in real-time.

Getting Started

Run via Docker container:

docker run -p 8080:8080 -p 9901:9901 -p 9088:9088 -p 18000:18000 -v `pwd`:/mnt docker.io/apoxy/proximal:latest

The above command mounts your current working directory at /mnt inside the container so you can ingest local Proxy-WASM code (e.g. /mnt/myprojects/myawesome-proxy-wasm-go/). Adjust as needed.

Bound ports:

  • 8080 - Web UI (see below) and REST API at :8080/v1/ (see definitions in the //api folder).
  • 18000 - Envoy listener - test your proxy configurations by sending requests to localhost:18000.
  • 9901 - Envoy admin UI.
  • 9088 - Temporal UI (for build workflow debugging).

Architecture

We rely on Envoy as the main data plane processing engine for request routing and its WebAssembly (WASI) extension engine that implements the Proxy-WASM ABI. The default runtime is Chromium V8 but other runtimes such as Wasmtime, Wamr, and WAVM can be configured.

The control plane server is a single Go binary that combines an Envoy control plane (using xDS protocol), a REST API server, a React app, and a Temporal server (which is linked directly via the awesome temporalite library) for managing build workflows. The same binary also acts as a Temporal worker and manages the Envoy process.

Internal state is supported by an embedded SQLite instance which produces an sqlite3.db file on local disk. The Temporal server has its own SQLite db file - temporalite.db. Both of these need to be exported via Docker volume mount if you want state persisted across Docker runs.

Compiled .wasm binaries are stored on local disk in the /tmp/proximal/ directory.

HTML/CSS/JavaScript assets currently live on local filesystem but will be embedded in the binary itself in the future.

High-level Design:

proximal-architecture

Known Limitations / Future Improvements

Known Limitations:

  • The entire setup is a single instance, single binary deal designed for local experimentation. While it's possible to run it on remote host since it's packaged in Docker, replication features are rather lacking.
  • TCP filters aren't yet supported.
  • Currently Proximal supports re-triggering builds from a git source manually. Automatic build triggers from GitHub commit webhooks or the like aren't suppported since they would require a hosted solution with a stable webhook endpoint.

Roadmap:

  • More SDKs + Examples - AssemblyScript, C++, JavaScript, and Python.
  • Istio examples - show how you take these modules into an existing Istio-enabled cluster.
  • K/V store integration.
  • Improved logging / tracing / accounting.
  • TCP and UDP filters.

If you're interested in any of above features (or maybe something else), feel free to drop a note to the Apoxy Team or open an issue on this repo!

Contributing

Patches Welcome! (no, really)

Proximal welcomes contributions from the community. If you find bugs, or wish to contribute code, please check out our contribution guidelines for detailed instructions.

Support and Feedback

If you encounter any issues, have questions, or want to provide feedback, we want to hear from you! Feel free to join our active community on Slack, raise an issue on GitHub, or shoot us an email:

License

Proximal is released under the Apache 2.0 License.

Credits

Proximal is developed and maintained by the Apoxy team. We want to thank the open-source community for their contributions and support in making this project possible. Special thanks go to: Envoy Proxy community, Proxy-WASM ABI and SDKs contributors, and fine folks at Temporal.



Apoxy Logo



Let's take Proxy-WASM development to new levels with Proximal! Happy Proxying! 🚀