Lua cluster specifier

Overview

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

• This filter should be configured with the type URL type.googleapis.com/envoy.extensions.router.cluster_specifiers.lua.v3.LuaConfig.

• v3 API reference

A simple example configuration of a Lua cluster:

lua-cluster-specifier.yaml

                  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_cluster"
                              end
                              return "example_cluster"
                            end
                        default_cluster: example_cluster
          http_filters:
          - name: envoy.filters.http.router

The Lua script defined in 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 default_cluster will be used.

Complete example

A complete example using Docker is available in the Lua cluster specifier sandbox.

Route handle API

When Envoy loads the script in the configuration, it looks for a global function defined by the script:

function envoy_on_route(route_handle)
end

Following the route path, Envoy will run envoy_on_route as a coroutine, passing a handle to the route API.

The following method on the stream handle is supported:

headers()

local headers = route_handle:headers()

Returns the stream’s headers. The headers can be used to select a specific cluster.

Returns a header object.

getCluster()

local cluster = route_header:getCluster('my_cluster')

Returns a handle to the specified cluster, or nil if it isn’t found.

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

Header object API

get()

headers:get(key)

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 ,.

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

Cluster API

numConnections()

cluster:numConnections()

This method gets the current number of connections for this cluster.

numRequests()

cluster:numRequests()

This method gets the current number of requests for this cluster.

numPendingRequests()

cluster:numPendingRequests()

This method gets the current number of pending requests for this cluster.

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.