Lua (proto)

This extension has the qualified name envoy.filters.http.lua

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension categories:

This extension must be configured with one of the following type URLs:

Lua configuration overview.

extensions.filters.http.lua.v3.Lua

[extensions.filters.http.lua.v3.Lua proto]

{
  "inline_code": ...,
  "source_codes": {...},
  "default_source_code": {...},
  "stat_prefix": ...,
  "clear_route_cache": {...},
  "filter_context": {...},
  "package_paths": [],
  "package_cpaths": [],
  "shared_vm_id": ...
}
inline_code

(string) The Lua code that Envoy will execute. This can be a very small script that further loads code from disk if desired. Note that if JSON configuration is used, the code must be properly escaped. YAML configuration may be easier to read since YAML supports multi-line strings so complex scripts can be easily expressed inline in the configuration.

This field is deprecated. Please use default_source_code. Only one of inline_code or default_source_code can be set for the Lua filter.

source_codes

(map<string, config.core.v3.DataSource>) Map of named Lua source codes that can be referenced in LuaPerRoute. The Lua source codes can be loaded from inline string or local files.

Example:

source_codes:
  hello.lua:
    inline_string: |
      function envoy_on_response(response_handle)
        -- Do something.
      end
  world.lua:
    filename: /etc/lua/world.lua
default_source_code

(config.core.v3.DataSource) The default Lua code that Envoy will execute. If no per route config is provided for the request, this Lua code will be applied.

stat_prefix

(string) Optional additional prefix to use when emitting statistics. By default metrics are emitted in .lua. namespace. If multiple lua filters are configured in a filter chain, the stats from each filter instance can be emitted using custom stat prefix to distinguish emitted statistics. For example:

http_filters:
  - name: envoy.filters.http.lua
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
      stat_prefix: foo_script # This emits lua.foo_script.errors etc.
  - name: envoy.filters.http.lua
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
      stat_prefix: bar_script # This emits lua.bar_script.errors etc.
clear_route_cache

(BoolValue) If set to true, the Lua filter will clear the route cache automatically if the request headers are modified by the Lua script. If set to false, the Lua filter will not clear the route cache automatically. Default is true for backward compatibility.

filter_context

(Struct) Optional filter context for the Lua script, accessed the same way as the per-route filter_context, via handle:filterContext(). This is the context a request gets when it has no LuaPerRoute configuration, or when the one it has does not set filter_context.

A LuaPerRoute which does set filter_context replaces this value rather than merging into it, so a route which sets an empty filter_context sees an empty context rather than this one. Only the most specific LuaPerRoute is consulted: a filter_context on a less specific one, such as a virtual host when the route has its own LuaPerRoute, is not reached, and this value is used instead.

package_paths

(repeated string) Additional patterns for the Lua package.path of every VM this filter creates, so that a script can require modules from locations the interpreter does not search on its own. Each entry is one Lua path pattern; the entries are joined with ; in the order given and placed ahead of the interpreter’s built-in default path, which is kept.

package_paths:
- /etc/envoy/lua/?.lua
- /etc/envoy/lua/?/init.lua

The patterns are in place before any configured code runs, including the run that validates the configuration, so a require at the top level of a script whose module cannot be found is rejected as a configuration error rather than failing per request.

Each worker builds its own VM and runs the script again to do so, after the configuration has been accepted, so the files a script requires must stay readable for as long as the process runs and not only while the configuration is loaded.

package_cpaths

(repeated string) As package_paths, but for package.cpath, i.e. modules which are loadable C libraries rather than Lua source, for example /etc/envoy/lua/?.so.

shared_vm_id

(string) If set, the Lua VMs this filter builds are shared with every other Lua filter configuration that sets the same shared_vm_id and configures the same script, rather than each configuration building its own. This applies to every script this message configures: default_source_code, inline_code and every entry of source_codes.

Sharing is decided per script, not per configuration: two configurations that agree on this id share a VM only for the scripts whose contents match, and whose package_paths and package_cpaths match, since a script that resolves its require calls differently does not produce an equivalent VM. A LuaPerRoute.shared_vm_id participates in the same sharing, so a route’s inline script can reuse a VM built here and the other way around.

A VM is not only an amount of memory, it is also a set of Lua globals that outlive a request. Scripts sharing a VM therefore see each other’s globals, exactly as separate requests through one configuration already do. Leave this field unset, which is the default, to keep every configuration’s scripts in VMs of their own.

A shared VM lives for as long as at least one configuration using it is alive. Once the last one is drained the VM is torn down, and the next configuration asking for that id and script builds a fresh one.

extensions.filters.http.lua.v3.LuaPerRoute

[extensions.filters.http.lua.v3.LuaPerRoute proto]

{
  "disabled": ...,
  "name": ...,
  "source_code": {...},
  "filter_context": {...},
  "package_paths": [],
  "package_cpaths": [],
  "shared_vm_id": ...
}
disabled

(bool) Disable the Lua filter for this particular vhost or route. If disabled is specified in multiple per-filter-configs, the most specific one will be used.

Only one of disabled, name, source_code may be set.

name

(string) A name of a Lua source code stored in Lua.source_codes.

Only one of disabled, name, source_code may be set.

source_code

(config.core.v3.DataSource) A configured per-route Lua source code that can be served by RDS or provided inline.

Only one of disabled, name, source_code may be set.

filter_context

(Struct) Optional filter context for Lua script. This could be used to pass configuration to Lua script. The Lua script can access the filter context using handle:filterContext(). For example:

function envoy_on_request(request_handle)
  local filter_context = request_handle:filterContext()
  local filter_context_value = filter_context:get("key")
  -- Do something with filter_context_value.
end

This replaces the filter-level filter_context rather than merging into it.

package_paths

(repeated string) Additional patterns for the Lua package.path of the VM built from this route’s source_code, with the same meaning as the filter-level package_paths.

This route’s inline source code gets its own VM, which is why it needs its own patterns: the filter-level ones are not visible to it. Setting these has no effect when this route selects a script by name, or configures no script at all, since that VM belongs to the filter and carries the filter-level patterns.

package_cpaths

(repeated string) As package_paths, but for package.cpath.

shared_vm_id

(string) As Lua.shared_vm_id, but for the VM built from this route’s source_code. Routes and filter configurations share one pool of VMs, so a route setting the same id as a filter configuration reuses that configuration’s VM when the script matches.

Setting this has no effect when this route selects a script by name, or configures no script at all, since that VM belongs to the filter and follows the filter’s setting.