failed to load the 'resty.core' when loading custom APISIX plugin

Question

I am trying to create a custom lua plugin for the APISIX docker version 2.15.0. I am using the a slightly different apisix example plugin and I am loading it using the instructions in the Developer Guide. However when I am reloading APISIX I get the following error and the plugin is not loading:

2022/10/05 14:05:40 [alert] 1#1: failed to load the 'resty.core' module (https://github.com/openresty/lua-resty-core); ensure you are using an OpenResty release from https://openresty.org/en/download.html (reason: /usr/local/apisix/apisix/plugins/3rd-party.lua:18: loop or previous error loading module 'apisix.core') in /usr/local/apisix/conf/nginx.conf:404

To reporduce:

1. Clone the APISIX docker repo with the docker compose stack
2. Create the folder <repo>/example/plugins
3. Create a file named 3rd-party.lua and put the code below
4. Edit the <repo>/apisix_conf/config.yaml and add the line extra_lua_path: "/usr/local/apisix/apisix/plugins/3rd-party.lua" under apisix
5. Bind the lua script to the docker by adding the line - ./plugins/3rd-party.lua:/usr/local/apisix/apisix/plugins/3rd-party.lua under the apisix's volumes section
6. Run the docker stack with cd ./example && docker-compose up -d
7. See if the plugin is loaded.

The lua plugin code:

local require       = require
local core          = require("apisix.core")
local plugin_name   = "3rd-party"


local schema = {
    type = "object",
    properties = {
        body = {
            description = "body to replace response.",
            type = "string"
        },
    },
    required = {"body"},
}

local plugin_name = "3rd-party"

local _M = {
    version = 0.1,
    priority = 12,
    name = plugin_name,
    schema = schema,
}


function _M.check_schema(conf)
    return core.schema.check(schema, conf)
end


function _M.access(conf, ctx)
    return 200, conf.body
end


return _M

Answer 1

After taking a lot of advice from the APISIX slack the correct steps to create a plugin for the docker-APISIX version are:

1. Create a lua plugin script
2. Bind the lua script to the docker apisix service by adding the line - /path/to/plugin/script/<plugin-name>.lua:/usr/local/apisix/apisix/plugins/<plugin-name>.lua under the apisix's volumes section like:

  apisix:
   ...
   volumes:
      ...
      - ./plugins/3rd-party.lua:/usr/local/apisix/apisix/plugins/3rd-party.lua

3. Get a copy of the available plugins that reside in the apisix docker container in /usr/local/apisix/conf/config-default.yaml. These are under the plugins section of the file
4. Add a new section named plugins in the apisix config file with the available plugins taken from the previous step like:

plugins:                          # plugin list (sorted by priority)
  - real-ip                        # priority: 23000
  - client-control                 # priority: 22000
  ...

5. Add the new plugin in the list of plugins of apisix config file like:

plugins:                          # plugin list (sorted by priority)
  - real-ip                        # priority: 23000
  - client-control                 # priority: 22000
  ...
  - 3rd-party

The steps above will load the new plugin in APISIX and it can be validated with a call curl http://<domain>/apisix/admin/plugins/list -H 'X-API-KEY: <key>'. The new plugin should appear in the response.

The steps above will not load the plugin to the apisix dashboard beacause the Dashboard is caching the list of plugins. To reload the cache follow these instructions.