mirrors/sablier
1
0
Fork 0
mirror of https://github.com/sablierapp/sablier.git synced 2025-12-21 13:23:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: reference plugin repositories

Browse Source
This commit is contained in:
Alexis Couvreur
2025-11-12 00:31:50 -05:00
parent 22c370ea22
commit 33209acc6c
10 changed files with 25 additions and 533 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/getting-started.md
View File

@@ -93,7 +93,7 @@ Because Caddy does not provide any runtime evaluation for the plugins, we need t
I'll use the provided Dockerfile to build the custom Caddy image.
```bash
docker build https://github.com/sablierapp/sablier.git#v1.8.1:plugins/caddy
docker build https://github.com/sablierapp/sablier-caddy-plugin.git
--build-arg=CADDY_VERSION=2.8.4
-t caddy:2.8.4-with-sablier
```
@@ -175,4 +175,4 @@ Here we've configured the following things when we're accessing the service on `
<!-- tabs:end -->
?> We've assigned the group `demo` to the service, and we use this to identify the workload i
?> We've assigned the group `demo` to the service, and we use this to identify the workload.

4
docs/guides/code-server-traefik-kubernetes.md
View File

@@ -58,8 +58,8 @@
enabled: true
additionalArguments:
- "--experimental.plugins.sablier.moduleName=github.com/sablierapp/sablier"
- "--experimental.plugins.sablier.version=v1.10.1" # x-release-please-version
- "--experimental.plugins.sablier.moduleName=github.com/sablierapp/sablier-traefik-plugin"
- "--experimental.plugins.sablier.version=v1.0.0 # Check latest version
providers:
kubernetesIngress:

30
docs/plugins/apacheapisix.md
View File

@@ -2,32 +2,6 @@
The Apache APISIX Plugin is a WASM Plugin written with the Proxy Wasm SDK.
## Provider compatibility grid
The plugin has moved to its own repository.
| Provider | Dynamic | Blocking |
|----------------------------------------|:-------:|:--------:|
| [Docker](../providers/docker) | ✅ | ✅ |
| [Docker Swarm](../providers/docker_swarm) | ❓ | ❓ |
| [Kubernetes](../providers/kubernetes) | ❓ | ❓ |
## Install the plugin to Apache APISIX
```yaml
wasm:
plugins:
- name: proxywasm_sablier_plugin
priority: 7997
file: /wasm/sablierproxywasm.wasm # Downloaded WASM Filter path
```
## Configuration
You can have the following configuration:
```yaml
routes:
- uri: "/"
plugins:
proxywasm_sablier_plugin:
conf: '{ "sablier_url": "sablier:10000", "group": ["my-group"], "session_duration": "1m", "dynamic": { "display_name": "Dynamic Whoami" } }'
```
📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)**

83
docs/plugins/caddy.md
View File

@@ -2,85 +2,6 @@
Caddy Sablier Plugin.
## Provider compatibility grid
The plugin has moved to its own repository.
| Provider | Dynamic | Blocking |
| --------------------------------------- | :-----: | :------: |
| [Docker](../providers/docker) | ✅ | ✅ |
| [Docker Swarm](../providers/docker_swarm) | ✅ | ✅ |
| [Kubernetes](../providers/kubernetes) | ❌ | ❌ |
## Install the plugin to Caddy
Because Caddy does not do runtime evaluation, you need to build the base image with the plugin source code.
In order to use the custom plugin for Caddy, you need to bundle it with Caddy.
Here I'll show you two options with Docker.
<!-- tabs:start -->
#### **Using the provided Dockerfile**
```bash
docker build https://github.com/sablierapp/sablier.git#v1.8.1:plugins/caddy
--build-arg=CADDY_VERSION=2.8.4
-t caddy:2.8.4-with-sablier
```
#### **Updating your Caddy Dockerfile**
```docker
ARG CADDY_VERSION=2.8.4
FROM caddy:${CADDY_VERSION}-builder AS builder
RUN xcaddy build \
--with github.com/sablierapp/sablier/plugins/caddy
FROM caddy:${CADDY_VERSION}
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
```
<!-- tabs:end -->
## Configuration
You can have the following configuration:
```Caddyfile
:80 {
route /my/route {
sablier [<sablierURL>=http://sablier:10000] {
[names container1,container2,...]
[group mygroup]
[session_duration 30m]
dynamic {
[display_name This is my display name]
[show_details yes|true|on]
[theme hacker-terminal]
[refresh_frequency 2s]
}
blocking {
[timeout 1m]
}
}
reverse_proxy myservice:port
}
}
```
### Exemple with a minimal configuration
Almost all options are optional, and you can set up very simple rules to use the server default values.
```Caddyfile
:80 {
route /my/route {
sablier {
group mygroup
dynamic
}
reverse_proxy myservice:port
}
}
```
📚 **[Full Documentation](https://github.com/sablierapp/sablier-caddy-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-caddy-plugin)**

45
docs/plugins/envoy.md
View File

@@ -2,47 +2,6 @@
The Envoy Plugin is a WASM Plugin written with the Proxy Wasm SDK.
## Provider compatibility grid
The plugin has moved to its own repository.
| Provider | Dynamic | Blocking |
|-----------------------------------------|:-------:|:--------:|
| [Docker](../providers/docker) | ✅ | ✅ |
| [Docker Swarm](../providers/docker_swarm) | ❓ | ❓ |
| [Kubernetes](../providers/kubernetes) | ❓ | ❓ |
## Configuration
You can have the following configuration:
```yaml
http_filters:
- name: sablier-wasm-whoami-dynamic
disabled: true
typed_config:
"@type": type.googleapis.com/udpa.type.v1.TypedStruct
type_url: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
value:
config:
name: "sablier-wasm-whoami-dynamic"
root_id: "sablier-wasm-whoami-dynamic"
configuration:
"@type": "type.googleapis.com/google.protobuf.StringValue"
value: |
{
"sablier_url": "sablier:10000",
"cluster": "sablier",
"names": ["docker_classic_e2e-whoami-1"],
"session_duration": "1m",
"dynamic": {
"display_name": "Dynamic Whoami",
"theme": "hacker-terminal"
}
}
vm_config:
runtime: "envoy.wasm.runtime.v8"
vm_id: "vm.sablier.sablier-wasm-whoami-dynamic"
code:
local:
filename: "/etc/sablierproxywasm.wasm"
configuration: { }
```
📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)**

42
docs/plugins/istio.md
View File

@@ -2,44 +2,6 @@
The Istio Plugin is a WASM Plugin written with the Proxy Wasm SDK.
## Provider compatibility grid
The plugin has moved to its own repository.
| Provider | Dynamic | Blocking |
|-----------------------------------------|:-------:|:--------:|
| [Docker](../providers/docker) | ❌ | ❌ |
| [Docker Swarm](../providers/docker_swarm) | ❌ | ❌ |
| [Kubernetes](../providers/kubernetes) | ✅ | ✅ |
## Configuration
You can have the following configuration:
!> This only works for ingress gateways.
!> Attaching this filter to a side-car would not work because the side-car itself gets shutdown on scaling to zero.
```yaml
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
name: sablier-wasm-whoami-dynamic
namespace: istio-system
spec:
selector:
matchLabels:
istio: ingressgateway
url: file:///opt/filters/sablierproxywasm.wasm/..data/sablierproxywasm.wasm
# Use https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin-TrafficSelector
# To specify which service to apply this filter only
phase: UNSPECIFIED_PHASE
pluginConfig:
{
"sablier_url": "sablier.sablier-system.svc.cluster.local",
"cluster": "outbound|10000||sablier.sablier-system.svc.cluster.local",
"names": [ "deployment_default_whoami_1" ],
"session_duration": "1m",
"dynamic": {
"display_name": "Dynamic Whoami",
"theme": "hacker-terminal"
}
}
```
📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)**

94
docs/plugins/nginx.md
View File

@@ -1,94 +0,0 @@
# Nginx Sablier Plugin
The Nginx Sablier Plugin is a javascript file that runs through the NJS Module.
## Provider compatibility grid
| Provider | Dynamic | Blocking |
| --------------------------------------- | :-----: | :------: |
| [Docker](../providers/docker) | ✅ | ✅ |
| [Docker Swarm](../providers/docker_swarm) | ✅ | ✅ |
| [Kubernetes](../providers/kubernetes) | ❌ | ❌ |
## Install the plugin to NGINX
1. Load the `ngx_http_js_module.so` in the main nginx config file `/etc/nginx/nginx.conf`
```nginx
load_module modules/ngx_http_js_module.so;
```
2. Copy/volume the `sablier.js` file to `/etc/nginx/conf.d/sablier.js`
## Configure the plugin
Use this sample for your APIs
```nginx
js_import conf.d/sablier.js;
resolver 127.0.0.11 valid=10s ipv6=off;
server {
listen 80;
subrequest_output_buffer_size 32k;
# The internal location to reach sablier API
set $sablierUrl /sablier;
# Shared variable for default session duration
set $sablierSessionDuration 1m;
# internal location for sablier middleware
# here, the sablier API is a container named "sablier" inside the same network as nginx
location /sablier/ {
internal;
proxy_method GET;
proxy_pass http://sablier:10000/;
}
# A named location that can be used by the sablier middleware to redirect
location @whoami {
# Use variable in order to refresh DNS cache
set $whoami_server whoami;
proxy_pass http://$whoami_server:80;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# The actual location to match your API
# Will answer by a waiting page or redirect to your app if
# it is already up
location /dynamic/whoami {
set $sablierDynamicShowDetails true;
set $sablierDynamicRefreshFrequency 5s;
set $sablierNginxInternalRedirect @whoami;
set $sablierGroup my-group;
set $sablierDynamicName "Dynamic Whoami";
set $sablierDynamicTheme hacker-terminal;
js_content sablier.call;
}
}
```
### Available variables
You can configure the middleware behavior with the following variables:
**General Configuration**
- `set $sablierUrl` The internal routing to reach Sablier API
- `set $sablierGroup` Group name to use to filter by label, ignored if sablierNames is set
- `set $sablierSessionDuration` The session duration after which containers/services/deployments instances are shutdown
- `set $sablierNginxInternalRedirect` The internal location for the service to redirect e.g. @nginx
**Dynamic Configuration**
*if any of these variables is set, then all Blocking Configuration is ignored*
- `set $sablierDynamicName`
- `set $sablierDynamicShowDetails` Set to true or false to show details specifcally for this middleware, unset to use Sablier server defaults
- `set $sablierDynamicTheme` The theme to use
- `set $sablierDynamicRefreshFrequency` The loading page refresh frequency
**Blocking Configuration**
- `set $sablierBlockingTimeout` waits until services are up and running but will not wait more than `timeout`

76
docs/plugins/nginx_proxywasm.md
View File

@@ -2,78 +2,6 @@
The Nginx Plugin is a WASM Plugin written with the Proxy Wasm SDK.
## Provider compatibility grid
The plugin has moved to its own repository.
| Provider | Dynamic | Blocking |
|-----------------------------------------|:-------:|:--------:|
| [Docker](../providers/docker) | ✅ | ✅ |
| [Docker Swarm](../providers/docker_swarm) | ❓ | ❓ |
| [Kubernetes](../providers/kubernetes) | ❓ | ❓ |
# Install ngx_wasm_module
Install https://github.com/Kong/ngx_wasm_module with version 0.6.0 at least.
Example for a Dockerfile:
```dockerfile
FROM ubuntu:25.04
RUN apt update && apt install -y libatomic1
ADD https://github.com/Kong/ngx_wasm_module/releases/download/prerelease-0.6.0/wasmx-prerelease-0.6.0-v8-x86_64-ubuntu22.04.tar.gz wasmx.tar.gz
RUN mkdir /etc/nginx
RUN tar -xvf wasmx.tar.gz
RUN mv /wasmx-prerelease-0.6.0-v8-x86_64-ubuntu22.04/* /etc/nginx/
WORKDIR /etc/nginx
CMD [ "./nginx", "-g", "daemon off;" ]
```
## Configuration
```nginx
# nginx.conf
events {}
# nginx master process gets a default 'main' VM
# a new top-level configuration block receives all configuration for this main VM
wasm {
module proxywasm_sablier_plugin /wasm/sablierproxywasm.wasm;
}
http {
access_log /dev/stdout;
# internal docker resolver, see /etc/resolv.conf on proxy container
# needed for docker name resolution
resolver 127.0.0.11 valid=1s ipv6=off;
server {
listen 8080;
location /dynamic {
proxy_wasm proxywasm_sablier_plugin '{ "sablier_url": "sablier:10000", "names": ["docker_classic_e2e-whoami-1"], "session_duration": "1m", "dynamic": { "display_name": "Dynamic Whoami", "theme": "hacker-terminal" } }';
# force dns resolution by using a variable
# because container will be restarted and change ip a lot of times
set $proxy_pass_host whoami:80$request_uri;
proxy_pass http://$proxy_pass_host;
proxy_set_header Host localhost:8080; # e2e test compliance
}
location /blocking {
wasm_socket_read_timeout 60s; # Blocking hangs the request
proxy_wasm proxywasm_sablier_plugin '{ "sablier_url": "sablier:10000", "names": ["docker_classic_e2e-whoami-1"], "session_duration": "1m", "blocking": { "timeout": "30s" } }';
# force dns resolution by using a variable
# because container will be restarted and change ip a lot of times
set $proxy_pass_host whoami:80$request_uri;
proxy_pass http://$proxy_pass_host;
proxy_set_header Host localhost:8080; # e2e test compliance
}
}
}
```
📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)**

19
docs/plugins/overview.md
View File

@@ -12,16 +12,15 @@ It leverages the API calls to plugin integration to catch in-flight requests to
## Available Reverse Proxies
| Reverse Proxy | Docker | Docker Swarm mode | Kubernetes |
|-------------------------------------------------|:------:|:-----------------:|:----------:|
| [Apache APISIX](apacheapisix) | ✅ | ✅ | ✅ |
| [Caddy](caddy) | ✅ | ✅ | ❌ |
| [Envoy](envoy) | ✅ | ❓ | ❓ |
| [Istio](istio) | ❌ | ❌ | ⚠️ |
| [Nginx (NJS Module)](nginx_njs) | ✅ | ✅ | ✅ |
| [Nginx (WASM Module)](nginx_proxywasm) | ✅ | ❓ | ❓ |
| [Traefik](traefik) | ✅ | ✅ | ✅ |
| [ProxyWasm](proxywasm) | ✅ | ✅ | ✅ |
| Reverse Proxy | Docker | Docker Swarm mode | Kubernetes |
| ----------------------------- | :----: | :---------------: | :--------: |
| [Apache APISIX](apacheapisix) | ✅ | ✅ | ✅ |
| [Caddy](caddy) | ✅ | ✅ | ❌ |
| [Envoy](envoy) | ✅ | ❓ | ❓ |
| [Istio](istio) | ❌ | ❌ | ⚠️ |
| [Nginx](nginx_proxywasm) | ✅ | ❓ | ❓ |
| [Traefik](traefik) | ✅ | ✅ | ✅ |
| [ProxyWasm](proxywasm) | ✅ | ✅ | ✅ |
> ✅ **Fully compatible**
>

161
docs/plugins/traefik.md
View File

@@ -1,162 +1,5 @@
# Traefik Sablier Plugin
The [Traefik Sablier Plugin](https://plugins.traefik.io/plugins/633b4658a4caa9ddeffda119/sablier) in the plugin catalog.
The plugin has moved to its own repository.
## Provider compatibility grid
| Provider | Dynamic | Blocking |
| --------------------------------------- | :-----: | :-----------------------------------------------------: |
| [Docker](../providers/docker) | ✅ | ✅ |
| [Docker Swarm](../providers/docker_swarm) | ✅ | ✅ |
| [Kubernetes](../providers/kubernetes) | ✅ | ✅ |
## Prerequisites
<!-- tabs:start -->
#### **Docker**
**Traefik will evict containers from its pool if they are stopped.**
Meaning labels attached to containers to autodiscover them is not possible with this plugin.
You have to use the dynamic config file provider instead.
**❌ You cannot do the following:**
```yaml
whoami:
image: acouvreur/whoami:v1.10.2
labels:
- traefik.enable
- traefik.http.routers.whoami.rule=PathPrefix(`/whoami`)
- traefik.http.routers.whoami.middlewares=my-sablier@file
```
**✅ You should do the following instead:**
```yaml
http:
services:
whoami:
loadBalancer:
servers:
- url: "http://whoami:80"
routers:
whoami:
rule: PathPrefix(`/whoami`)
entryPoints:
- "http"
middlewares:
- my-sablier@file
service: "whoami"
```
*dynamic-config.yaml*
#### **Docker Swarm**
**Traefik will evict services from its pool if they have 0 replicas.**
In order to use service labels, you have to add the following option on top of each services that will use this plugin.
See also [`traefik.docker.lbswarm`](https://doc.traefik.io/traefik/routing/providers/swarm/#traefikdockerlbswarm) label
```yaml
services:
whoami:
image: acouvreur/whoami:v1.10.2
deploy:
replicas: 0
labels:
- traefik.docker.lbswarm=true
```
Traefik also have [allowEmptyServices](https://doc.traefik.io/traefik/providers/docker/#allowemptyservices) option which can be used instead.
#### **Kubernetes**
**Traefik will evict deployments from its pool if they have 0 endpoints available.**
You must use [`allowEmptyServices`](https://doc.traefik.io/traefik/providers/kubernetes-ingress/#allowemptyservices)
The blocking strategy is supported by issuing redirect which force client to retry request. It might fail if client do not support redirections (e.g. `curl` without `-L`). The limitation is caused by Traefik architecture. Everytime the underlying configuration changes, the whole router is regenrated, thus changing the router during a request will still map to the old router. For more details, see [#62](https://github.com/sablierapp/sablier/issues/62).
<!-- tabs:end -->
## Install the plugin to Traefik
<!-- tabs:start -->
#### **File (YAML)**
<!-- x-release-please-start-version -->
```yaml
experimental:
plugins:
sablier:
moduleName: "github.com/sablierapp/sablier"
version: "v1.10.1"
```
<!-- x-release-please-end -->
#### **CLI**
<!-- x-release-please-start-version -->
```bash
--experimental.plugins.sablier.modulename=github.com/sablierapp/sablier
--experimental.plugins.sablier.version=v1.10.1
```
<!-- x-release-please-end -->
<!-- tabs:end -->
## Configure the plugin using the Dynamic Configuration
<!-- tabs:start -->
#### **File (YAML)**
```yaml
http:
middlewares:
my-sablier:
plugin:
sablier:
group: default
dynamic:
displayName: My Title
refreshFrequency: 5s
showDetails: "true"
theme: hacker-terminal
sablierUrl: http://sablier:10000
sessionDuration: 1m
```
#### **Kubernetes CRD**
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: my-sablier
namespace: my-namespace
spec:
plugin:
sablier:
group: default
dynamic:
displayName: My Title
refreshFrequency: 5s
showDetails: "true"
theme: hacker-terminal
sablierUrl: http://sablier:10000
sessionDuration: 1m
```
<!-- tabs:end -->
## Configuration reference
TODO
📚 **[Full Documentation](https://github.com/sablierapp/sablier-traefik-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-traefik-plugin)**