Global Lua Modules

When writing custom Edge rules in Edgelang, you may sometimes need to invoke a custom Lua module. In such cases, you can add the Lua module through Global Lua Modules.

# 1. Creating a Global Lua Module

Let’s take a look at how to create a global Lua module and reference it in Edgelang.

First, click Global Configuration:

Then click Global Lua Modules in the left navigation bar to enter the Global Lua Modules page.

This page lists all existing global Lua modules. Click the New Lua Module button to create a new module.

The New Lua Module dialog provides the following configuration options:

• Module name: The name of the module, which will be used when referencing it in Edgelang.
• Upload Lua file: Click Select file to import an existing .lua file directly. The module name defaults to the file name.
• Lua code: Write Lua code directly in the editor. You can enable Vim mode while editing.
• Run on Startup: When enabled, the Edge Node will invoke this module’s init_worker() function during the initialization of every worker process at startup. Note: once enabled, any modification to this Lua module’s configuration will trigger a graceful restart of the Edge Node. This option was first introduced in version 26.6.1-1.

For example, here is a simple module that returns a greeting:

local _M = {}
function _M.say_hello()
    return "hello world!"
end

return _M

After filling in the fields, click the Save button. The Lua module will be automatically distributed to every node, after which it can be referenced in Edgelang code:

true =>
    say(foreign-call(module: "custom_lua_module", func: "say_hello"));

# 2. Synchronization Options

At the top right of the page are the Synchronization Options, which have the same meaning as described in Global Configuration.

One difference is that, when Synchronize automatically to other partitions is unchecked, Global Lua Modules supports not only copying all Lua modules to a specified partition but also copying an individual Lua module to a specified partition. Let’s click the Copy button.

Then select the partition to sync to and click copy. The configuration of the current partition will overwrite that of the specified partition.

# 3. Change History

You can view the change history of Lua modules within the same partition on the Releases page. Let’s click the Releases button.

Find the corresponding release entry and click View Details.

You will then be able to see the changes made in this release.

# 4. Search Lua Modules

Use the search field on Global Lua Modules to filter the current page. Search matches both module name and Lua code.

Press Ctrl+K on Windows or Linux, or Cmd+K on macOS, to open global search. Global Lua Module results include the partition so that identical module names can be distinguished. The backing search supports pagination and partition filters.

# 5. Custom Shared Memory Dictionaries

The Custom Shared Memory Dictionaries tab of the Global Lua Modules page defines shared memory dictionaries for gateway nodes. Each dictionary becomes an nginx lua_shared_dict zone with the given name and size, and all worker processes of a gateway node share its data. Lua code, such as a global Lua module, accesses a dictionary through ngx.shared.<name>. For an example, see Custom Challenge, whose Lua module stores CAPTCHA answers in ngx.shared.captcha_store.

Click New Custom Shared Memory Dictionary, enter the Name and Size of the dictionary, and click Save. Use Edit and Delete in the list to change or remove a dictionary. A change takes effect as soon as it is saved, without a release, and restarts the Edge Node processes through a binary upgrade. See Configuration and Process Updates for details.

Before deleting a dictionary, confirm that no published Lua module still uses it, or affected requests will be unable to access the shared memory at runtime.

Dictionaries are configured per partition. The Lua Modules and Custom Shared Memory Dictionaries tabs share the partition selector at the upper right and the same Synchronize automatically to other partitions option. Select the default partition to change that option:

• When the option is enabled, only the default partition can be edited. The dictionaries saved there replace the dictionaries of all other partitions.
• When the option is disabled, each partition keeps its own dictionaries. Each tab has its own Copy to other Partitions button: Lua Modules copies Lua modules, and Custom Shared Memory Dictionaries copies dictionary definitions.

Enabling the option does not copy any dictionary by itself. The other partitions receive the dictionaries of the default partition the next time a dictionary is saved or deleted there. Until then, a Lua module that is synchronized to another partition cannot use a dictionary that exists only in the default partition. To copy them at once, click Edit on any dictionary of the default partition and click Save without changing it.

# Copy Custom Shared Memory Dictionaries

Turn off Synchronize automatically to other partitions in the default partition. Select the source partition, open the Custom Shared Memory Dictionaries tab, and click Copy to other Partitions.

In the Copy Custom Shared Memory Dictionaries window, select the target partitions and click Copy. The source partition cannot be a target.

Before copying, check the overwrite scope:

• All saved dictionary definitions from the source partition replace the entire dictionary definition group in each target partition.
• Definitions that exist only in a target partition are removed. An empty source group clears all dictionary definitions in the target partitions.
• Dictionary contents and Lua modules are not copied.

Changed target partitions receive the configuration immediately after a successful copy, without a separate release. Copying fails if the source or any target partition has unreleased General changes or a batch release in progress. Complete those releases before retrying. Saving a dictionary also fails if any partition that the save applies to has unreleased General changes.

Changing dictionaries needs the write permission of Global Lua Modules, and saving them through the API path partitions/{partition_id}/ngx needs the write permission of General as well. In earlier versions the write permission of General was enough, so after an upgrade, give the Global Lua Modules write permission to the user groups that manage dictionaries.

Configuring dictionaries per partition was first introduced in OpenResty Edge 26.12.1-1. In earlier versions, all partitions share one list of dictionaries.

# 6. Module Variables and Updates

Starting with OpenResty Edge 26.12.1-1, each version of each global Lua module has its own variable environment. Non-local assignments do not overwrite another module’s variables with the same names. Values can persist when the same version runs again, while a new version starts with a fresh environment so old initialization guards and globals do not linger.

Share data explicitly through module interfaces and require, rather than relying on implicit globals shared between modules. This environment isolation is not a security sandbox or persistent storage across workers.

When a module runs again, its dependencies are rebuilt from the current version’s require calls. Dependencies removed by a new version no longer affect its updates; dependencies still used by other modules are retained.