diff --git a/docs/root/configuration/http/cluster_specifier/lua.rst b/docs/root/configuration/http/cluster_specifier/lua.rst
index 0cab42c25cd0..da53f3d502d0 100644
--- a/docs/root/configuration/http/cluster_specifier/lua.rst
+++ b/docs/root/configuration/http/cluster_specifier/lua.rst
@@ -6,10 +6,15 @@ Lua cluster specifier
Overview
--------
-The HTTP Lua cluster specifier allows `Lua `_ scripts to select router cluster
-during the request flows. `LuaJIT `_ is used as the runtime. Because of this, the
-supported Lua version is mostly 5.1 with some 5.2 features. See the `LuaJIT documentation
-`_ for more details.
+The HTTP Lua cluster specifier allows `Lua `_ scripts to select a router cluster
+during the request flow.
+
+.. note::
+ `LuaJIT `_ is used as the runtime.
+
+ This means that the currently supported Lua version is mostly 5.1 with some 5.2 features.
+
+ See the `LuaJIT documentation `_ for more details.
Configuration
-------------
@@ -17,61 +22,52 @@ Configuration
* This filter should be configured with the type URL ``type.googleapis.com/envoy.extensions.router.cluster_specifiers.lua.v3.LuaConfig``.
* :ref:`v3 API reference `
-A simple example of configuring Lua cluster specifier is as follow:
-
-.. code-block:: yaml
-
- routes:
- - match:
- prefix: "/"
- route:
- inline_cluster_specifier_plugin:
- extension:
- name: envoy.router.cluster_specifier_plugin.lua
- typed_config:
- "@type": type.googleapis.com/envoy.extensions.router.cluster_specifiers.lua.v3.LuaConfig
- source_code:
- inline_string: |
- function envoy_on_route(route_handle)
- local header_value = route_handle:headers():get("header_key")
- if header_value == "fake" then
- return "fake_service"
- end
- return "web_service"
- end
- default_cluster: web_service
-
-Lua script defined in ``source_code`` will be executed to select router cluster, and just as cluster specifier
-plugin in C++, Lua script can also select router cluster based on request headers. If Lua script execute failure,
-``default_cluster`` will be used.
+A simple example configuration of a Lua cluster:
+
+.. literalinclude:: /start/sandboxes/_include/lua-cluster-specifier/envoy.yaml
+ :language: yaml
+ :lines: 22-40
+ :emphasize-lines: 3-17
+ :linenos:
+ :caption: :download:`lua-cluster-specifier.yaml `
+
+The Lua script defined in
+:ref:`source_code `
+will be executed to select the routed cluster.
+
+It can also select a cluster based on matched request headers.
+
+If execution of the Lua script results in failure, the
+:ref:`default_cluster `
+will be used.
Complete example
----------------
-A complete example using Docker is available in :repo:`/examples/lua-cluster-specifier`.
+A complete example using Docker is available in the :ref:`Lua cluster specifier sandbox `.
Route handle API
----------------
-When Envoy loads the script in the configuration, it looks for a global function that the script defines:
+When Envoy loads the script in the configuration, it looks for a global function defined by the script:
.. code-block:: lua
function envoy_on_route(route_handle)
end
-During the route path, Envoy will run *envoy_on_route* as a coroutine, passing a handle to the route API.
+Following the route path, Envoy will run ``envoy_on_route`` as a coroutine, passing a handle to the route API.
-The following methods on the stream handle are supported:
+The following method on the stream handle is supported:
-headers()
-^^^^^^^^^
+``headers()``
++++++++++++++
.. code-block:: lua
- local headers = handle:headers()
+ local headers = route_handle:headers()
-Returns the stream's headers. The headers can be used to match to select a specific cluster.
+Returns the stream's headers. The headers can be used to select a specific cluster.
Returns a :ref:`header object `.
@@ -80,13 +76,17 @@ Returns a :ref:`header object `.
Header object API
-----------------
-get()
-^^^^^
+``get()``
++++++++++
.. code-block:: lua
headers:get(key)
-Gets a header. *key* is a string that supplies the header key. Returns a string that is the header
-value or nil if there is no such header. If there are multiple headers in the same case-insensitive
-key, their values will be combined with a *,* separator and returned as a string.
+This method gets a header.
+
+``key`` is a string that specifies the header key.
+
+Returns either a string containing the header value, or ``nil`` if the header does not exist.
+
+If there are multiple headers in the same case-insensitive key, their values will be concatenated to a string separated by ``,``.
diff --git a/docs/root/start/sandboxes/lua-cluster-specifier.rst b/docs/root/start/sandboxes/lua-cluster-specifier.rst
index a7e4c852c849..f927333ad755 100644
--- a/docs/root/start/sandboxes/lua-cluster-specifier.rst
+++ b/docs/root/start/sandboxes/lua-cluster-specifier.rst
@@ -1,6 +1,6 @@
.. _install_sandboxes_lua_cluster_specifier:
-Lua Cluster Specifier
+Lua cluster specifier
=====================
.. sidebar:: Requirements
@@ -17,13 +17,15 @@ The example Envoy proxy configuration includes a Lua cluster specifier plugin th
- ``envoy_on_route(route_handle)``
-:ref:`See here ` for an overview of Envoy's Lua cluster specifier
-and documentation regarding the function.
+.. tip::
+
+ See the :ref:`Lua cluster configuration documentation ` for an overview and
+ documentation regarding the function.
Step 1: Build the sandbox
*************************
-Change to the ``examples/lua-cluster-specifier`` directory.
+Change to the ``examples/lua-cluster-specifier`` directory, and bring up the composition.
.. code-block:: console
@@ -35,27 +37,23 @@ Change to the ``examples/lua-cluster-specifier`` directory.
Name Command State Ports
--------------------------------------------------------------------------------------------
- lua-cluster-specifier-proxy-1 /docker-entrypoint.sh /usr ... Up 10000/tcp, 0.0.0.0:8000->8000/tcp
- lua-cluster-specifier-web_service-1 /bin/echo-server Up 0.0.0.0:8080->8080/tcp
+ lua-cluster-specifier-proxy-1 /docker-entrypoint.sh /usr ... Up 10000/tcp, 0.0.0.0:10000->10000/tcp
Step 2: Send a request to the normal service
********************************************
The output from the ``curl`` command below should return 200, since the lua code select the normal service.
-Terminal 1
-
.. code-block:: console
- $ curl -i localhost:8000/anything 2>&1 |grep 200
+ $ curl -i localhost:10000/anything 2>&1 |grep 200
HTTP/1.1 200 OK
Step 3: Send a request to the fake service
******************************************
-The output from the ``curl`` command below should return 503, since the lua code select the fake service.
-
-Terminal 1
+If you specify the request header ``header_key:fake``, curl will return a ``503`` response, as
+the Lua code will select the fake service.
.. code-block:: console
diff --git a/examples/lua-cluster-specifier/docker-compose.yaml b/examples/lua-cluster-specifier/docker-compose.yaml
index 904b030f8417..8faf8df65a2c 100644
--- a/examples/lua-cluster-specifier/docker-compose.yaml
+++ b/examples/lua-cluster-specifier/docker-compose.yaml
@@ -5,10 +5,4 @@ services:
context: .
dockerfile: ../shared/envoy/Dockerfile
ports:
- - "${PORT_PROXY:-8000}:8000"
-
- web_service:
- build:
- context: ../shared/echo
- ports:
- - "${PORT_WEB:-8080}:8080"
+ - "${PORT_PROXY:-10000}:10000"
diff --git a/examples/lua-cluster-specifier/envoy.yaml b/examples/lua-cluster-specifier/envoy.yaml
index 058e28179395..178ced586715 100644
--- a/examples/lua-cluster-specifier/envoy.yaml
+++ b/examples/lua-cluster-specifier/envoy.yaml
@@ -1,10 +1,9 @@
static_resources:
listeners:
- - name: main
- address:
+ - address:
socket_address:
address: 0.0.0.0
- port_value: 8000
+ port_value: 10000
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
@@ -13,9 +12,9 @@ static_resources:
stat_prefix: ingress_http
codec_type: AUTO
route_config:
- name: local_route
+ name: example_route
virtual_hosts:
- - name: local_service
+ - name: example_hosts
domains:
- "*"
routes:
@@ -32,23 +31,22 @@ static_resources:
function envoy_on_route(route_handle)
local header_value = route_handle:headers():get("header_key")
if header_value == "fake" then
- return "fake_service"
+ return "fake_cluster"
end
- return "web_service"
+ return "example_cluster"
end
- default_cluster: web_service
-
+ default_cluster: example_cluster
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- - name: web_service
- type: STRICT_DNS # static
+ - name: example_cluster
+ type: STRICT_DNS
lb_policy: ROUND_ROBIN
load_assignment:
- cluster_name: web_service
+ cluster_name: example_cluster_service
endpoints:
- lb_endpoints:
- endpoint: