ingress-nginx lua plugins documentation

docs/user-guide/nginx-configuration/configmap.md

@@ -468,8 +468,7 @@ _References:_
 
 ## plugins
 
-Configures plugins to use placed in the directory /etc/nginx/lua/plugins. Every plugin has to have main.lua in the root.
+Activates plugins installed in `/etc/nginx/lua/plugins`. Refer to [ingress-nginx plugins README](../../../rootfs/etc/nginx/lua/plugins/README.md) for more information on how to write and install a plugin.
-Every plugin has to bundle all of its dependencies. The execution order follows the definition.
 
 ## server-tokens
 

rootfs/etc/nginx/lua/plugins/README.md

@@ -0,0 +1,35 @@
+# Custom Lua plugins
+
+ingress-nginx uses [https://github.com/openresty/lua-nginx-module](https://github.com/openresty/lua-nginx-module) to run custom Lua code
+within Nginx workers. It is recommended to familiarize yourself with that ecosystem before deploying your custom Lua based ingress-nginx plugin.
+
+### Writing a plugin
+
+Every ingress-nginx Lua plugin is expected to have `main.lua` file and all of its dependencies.
+`main.lua` is the entry point of the plugin. The plugin manager uses convention over configuration
+strategy and automatically runs functions defined in `main.lua` in the corresponding Nginx phase based on their name.
+
+Nginx has different [request processing phases](http://nginx.org/en/docs/dev/development_guide.html#http_phases).
+By defining functions with the following names, you can run your custom Lua code in the corresponding Nginx phase:
+
+ - `init_worker`: useful for initializing some data per Nginx worker process
+ - `rewrite`: useful for modifying request, changing headers, redirection, dropping request, doing authentication etc
+ - `header`: this is called when backend response header is received, it is useful for modifying response headers
+ - `log`: this is called when request processing is commpleted and response is delivered to the client
+
+Check this [`hello_world`](https://github.com/kubernetes/ingress-nginx/tree/master/rootfs/etc/nginx/lua/plugins/hello_world) plugin as a simple example or refer to [OpenID Connect integration](https://github.com/ElvinEfendi/ingress-nginx-openidc/tree/master/rootfs/etc/nginx/lua/plugins/openidc) for more advanced usage.
+
+Do not forget to write tests for your plugin.
+
+### Installing a plugin
+
+There are two options:
+
+  - mount your plugin into `/etc/nginx/lua/plugins/<your plugin name>` in the ingress-nginx pod
+  - build your own ingress-nginx image like it is done in the [example](https://github.com/ElvinEfendi/ingress-nginx-openidc/tree/master/rootfs/etc/nginx/lua/plugins/openidc) and install your plugin during image build
+
+Mounting is the quickest option.
+
+### Enabling plugins
+
+Once your plugin is ready you need to use [`plugins` configuration setting](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#plugins) to activate it. Let's say you want to active `hello_world` and `open_idc` plugins, then you set `plugins` setting to `"hello_world, open_idc"`. _Note_ that the plugins will be executed in the given order.

rootfs/etc/nginx/lua/plugins/hello_world/main.lua

@@ -1,14 +1,10 @@
 local _M = {}
 
 function _M.rewrite()
-  ngx.req.set_header("x-hello-world", "1")
-end
-
-function _M.access()
   local ua = ngx.var.http_user_agent
 
   if ua == "hello" then
-    ngx.exit(403)
+    ngx.req.set_header("x-hello-world", "1")
   end
 end
 

rootfs/etc/nginx/lua/plugins/hello_world/test/main_test.lua

@@ -0,0 +1,25 @@
+_G._TEST = true
+
+local main = require("plugins.hello_world.main")
+
+-- The unit tests are run within a timer phase in a headless Nginx process.
+-- Since `set_header` and `ngx.var.http_` API are disabled in this phase we have to stub it 
+-- to avoid `API disabled in the current context` error.
+
+describe("main", function()
+  describe("rewrite", function()
+    it("sets x-hello-world header to 1 when user agent is hello", function()
+      ngx.var = { http_user_agent = "hello" }
+      stub(ngx.req, "set_header")
+      main.rewrite()
+      assert.stub(ngx.req.set_header).was_called_with("x-hello-world", "1")
+    end)
+
+    it("does not set x-hello-world header to 1 when user agent is not hello", function()
+      ngx.var = { http_user_agent = "not-hello" }
+      stub(ngx.req, "set_header")
+      main.rewrite()
+      assert.stub(ngx.req.set_header).was_not_called_with("x-hello-world", "1")
+    end)
+  end)
+end)