From 33209acc6c7c597a15ec1c9846683e8cdd9c5b7a Mon Sep 17 00:00:00 2001 From: Alexis Couvreur Date: Wed, 12 Nov 2025 00:31:50 -0500 Subject: [PATCH] docs: reference plugin repositories --- docs/getting-started.md | 4 +- docs/guides/code-server-traefik-kubernetes.md | 4 +- docs/plugins/apacheapisix.md | 30 +--- docs/plugins/caddy.md | 83 +-------- docs/plugins/envoy.md | 45 +---- docs/plugins/istio.md | 42 +---- docs/plugins/nginx.md | 94 ---------- docs/plugins/nginx_proxywasm.md | 76 +-------- docs/plugins/overview.md | 19 +-- docs/plugins/traefik.md | 161 +----------------- 10 files changed, 25 insertions(+), 533 deletions(-) delete mode 100644 docs/plugins/nginx.md diff --git a/docs/getting-started.md b/docs/getting-started.md index d5e1bfb..1173fec 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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 ` -?> 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. diff --git a/docs/guides/code-server-traefik-kubernetes.md b/docs/guides/code-server-traefik-kubernetes.md index c6025e2..d16acff 100644 --- a/docs/guides/code-server-traefik-kubernetes.md +++ b/docs/guides/code-server-traefik-kubernetes.md @@ -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: diff --git a/docs/plugins/apacheapisix.md b/docs/plugins/apacheapisix.md index 72274cd..56252da 100644 --- a/docs/plugins/apacheapisix.md +++ b/docs/plugins/apacheapisix.md @@ -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" } }' -``` \ No newline at end of file +📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)** \ No newline at end of file diff --git a/docs/plugins/caddy.md b/docs/plugins/caddy.md index baf6193..4e669ca 100644 --- a/docs/plugins/caddy.md +++ b/docs/plugins/caddy.md @@ -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. - - - -#### **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 -``` - - - -## Configuration - -You can have the following configuration: - -```Caddyfile -:80 { - route /my/route { - sablier [=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)** diff --git a/docs/plugins/envoy.md b/docs/plugins/envoy.md index 8c09438..9d4bc99 100644 --- a/docs/plugins/envoy.md +++ b/docs/plugins/envoy.md @@ -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: { } -``` \ No newline at end of file +📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)** \ No newline at end of file diff --git a/docs/plugins/istio.md b/docs/plugins/istio.md index de5f72a..009e90f 100644 --- a/docs/plugins/istio.md +++ b/docs/plugins/istio.md @@ -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" - } - } -``` \ No newline at end of file +📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)** \ No newline at end of file diff --git a/docs/plugins/nginx.md b/docs/plugins/nginx.md deleted file mode 100644 index c2aae69..0000000 --- a/docs/plugins/nginx.md +++ /dev/null @@ -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` \ No newline at end of file diff --git a/docs/plugins/nginx_proxywasm.md b/docs/plugins/nginx_proxywasm.md index a507dad..d04eca9 100644 --- a/docs/plugins/nginx_proxywasm.md +++ b/docs/plugins/nginx_proxywasm.md @@ -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 - } - } -} -``` \ No newline at end of file +📚 **[Full Documentation](https://github.com/sablierapp/sablier-proxywasm-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-proxywasm-plugin)** \ No newline at end of file diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md index f891b6d..f3aee5d 100644 --- a/docs/plugins/overview.md +++ b/docs/plugins/overview.md @@ -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** > diff --git a/docs/plugins/traefik.md b/docs/plugins/traefik.md index 4a30f07..61d630f 100644 --- a/docs/plugins/traefik.md +++ b/docs/plugins/traefik.md @@ -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 - - - -#### **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). - - - -## Install the plugin to Traefik - - - -#### **File (YAML)** - - -```yaml -experimental: - plugins: - sablier: - moduleName: "github.com/sablierapp/sablier" - version: "v1.10.1" -``` - - -#### **CLI** - - -```bash ---experimental.plugins.sablier.modulename=github.com/sablierapp/sablier ---experimental.plugins.sablier.version=v1.10.1 -``` - - - - -## Configure the plugin using the Dynamic Configuration - - - -#### **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 -``` - - - -## Configuration reference - -TODO +📚 **[Full Documentation](https://github.com/sablierapp/sablier-traefik-plugin)** | 💻 **[Plugin Repository](https://github.com/sablierapp/sablier-traefik-plugin)** \ No newline at end of file