NLJUG – Nederlandse Java User Group NLJUG – de Nederlandse Java User Group – is opgericht in 2003. De NLJUG verenigt software ontwikkelaars, architecten, ICT managers, studenten, new media developers en haar businesspartners met algemene interesse in alle aspecten van Java Technology.
Author: Nicolas Frankel
Original post on Foojay: Read More
When I introduce Apache APISIX in my talks, I mention the massive number of existing plugins, and that each of them implements a specific feature.
One of the key features of Apache APISIX is its flexibility. If a feature is missing, you can create your own plugin in Lua or a language compiled into Wasm, showcasing the platform’s adaptability to your specific needs.
In this article, I aim to provide practical alternatives to writing a custom plugin, offering solutions you can quickly implement in your projects.
Cons of writing a plugin
Before describing alternatives, let me explain the issues of writing a plugin.
The biggest argument against writing a plugin is quite generic. You write code: suddenly, you need to take care of it. It includes fixing bugs, updating dependencies, keeping the code synchronized with APISIX’s latest version, etc.
As I mentioned above, APISIX comes with a list of out-of-the-box plugins. A huge majority of them are enabled in the default configuration. However, if you want to add a plugin to the list, you must add all required plugins individually, as your configuration replaces the default one; this is the case with a custom plugin.
Custom plugins require you to configure APISIX with the path to the plugin(s) folder:
apisix:
extra_lua_path: /opt/?.lua
Moreover, some plugins may require additional configuration. For example, in my previous version of Evolving your APIs, I set a custom nginx snippet to add a Lua shared dictionary to use it in the code’s plugin:
nginx_config:
http:
custom_lua_shared_dict:
plugin-unauth-limit: 100m
Finally, writing a custom plugin requires a fairly advanced understanding of Apache APISIX and its inner workings. This knowledge is a good idea, but it’s not great to make it a requirement.
The vars and filter_func parameters
In my earlier blog post Free tier API with Apache APISIX, I implemented an API-free tier with the help of the vars parameter. As a reminder, vars is an additional matching condition on your route besides the usual ones: URI, HTTP method, and host.
In the mentioned post, I used vars to add a match on an HTTP header.
routes:
– uri: /get
upstream_id: 1
vars: [[ “http_apikey”, “~~”, “.*”]] #1
Match only if the request has an HTTP header named apikey
However, the vars parameter has its limitations, particularly in its support of a limited range of operators, which may restrict its use in more complex scenarios. Here it is for convenience:
Operator
Description
Example
==
equal
[“arg_version”, “==”, “v2”]
~=
not equal
[“arg_version”, “~=”, “v2”]
>
greater than
[“arg_ttl”, “>”, 3600]
>=
greater than or equal to
[“arg_ttl”, “>=”, 3600]
<
less than
[“arg_ttl”, “<“, 3600]
⇐
less than or equal to
[“arg_ttl”, “⇐”, 3600]
~~
match RegEx
[“arg_env”, “~~”, “[Dd]ev”]
~*
match RegEx (case-insensitive)
[“arg_env”, “~~”, “dev”]
in
exist on the right-hand side
[“arg_version”, “in”, [“v1″,”v2”]]
has
contain item on the right-hand side
[“graphql_root_fields”, “has”, “owner”]
!
reverse the adjacent operator
[“arg_env”, “!”, “~~”, “[Dd]ev”]
ipmatch
match an IP address
[“remote_addr”, “ipmatch”, [“192.168.102.40”, “192.168.3.0/24”]]
Note that the DSL also supports boolean operators.
Imagine that the need goes beyond what we can express with the DSL. It’s time to break our bounds and leverage the full power of Lua.
With filter_func, we can write a dedicated Lua function:
It accepts a vars arg, allowing you to access APISIX built-in variables, including nginx variables, e.g., HTTP headers.
It must return a boolean value. As for vars, APSIX uses the value to decide whether the route matches or not.
The serverless plugin
The serverless plugin actually consists of two plugins: serverless-pre-function and serverless-pre-function. As their name implies, the former executes before any other plugin in that phase and the latter after any other plugin in that phase. Note that it’s because of their respective default priority. While it’s technically possible to override the priority, common sense should prevent you from ever thinking about doing so.
With serverless, you configure two parameters:
The phase in which APISIX executes it
A sequential array of Lua functions
A widespread use case with serverless is to log input and output data.
routes:
– uri: /get
upstream_id: 1
plugins:
serverless-pre-function:
phase: rewrite #1
functions:
– >
return function(conf, ctx)
local core = require(“apisix.core”)
core.log.warn(“conf: “, core.json.encode(conf)) #2
core.log.warn(“ctx : “, core.json.encode(ctx, true)) #3
end
serverless-post-function:
phase: log #4
functions:
– >
return function(conf, ctx)
local core = require(“apisix.core”)
core.log.warn(“ctx : “, core.json.encode(ctx, true)) #5
end
Execute at the start of the rewrite phase
Serialize the configuration to JSON and write it in the log. We use the warn level because it’s the default one
Serialize the context to JSON and write it in the log
Execute at the start of the log phase
Serialize the context to JSON and write it in the log again. The context will probably have changed between the two phases
The APISIX model only allows a unique plugin per route. It’s a limitation of this approach: while you can have multiple functions per phase, you can’t span more than two phases, one for pre and one for post.
The script parameter
I must admit that I learned about script when researching for this post. With script, you can write Lua code directly in your config without needing a full-fledged plugin! script comes with a huge limitation, though: it’s exclusive with plugins.
Scripts and Plugins are mutually exclusive, and a Script is executed before a Plugin. This means that after configuring a Script, the Plugin configured on the Route will not be executed.
I believe that, at this point, you’d better write a plugin instead.
The _meta.filter parameter
So far, our scope has been the route (or the service if you prefer the latter). However, an alternative is to execute a plugin conditionally. For example, imagine a route configured with the limit-count plugin to rate limit the number of requests. We want to test the infrastructure in a stress test. Instead of creating our own plugin, we can bypass the plugin if a specific header is present.
The filter syntax is the same as the vars syntax.
routes:
– uri: /get
upstream_id: 1
plugins:
limit-count: #1
count: 1
time_window: 60
rejected_code: 429
_meta:
filter: [[“http_Secret-Header”, “~=”, “MySuperDuperSecretBypassKey”]] #2
Configure the limit-count plugin
Execute it only if the HTTP header has a different value
Summary
Writing a custom plugin entails lots of downsides. I showed a couple of other alternatives in this post:
Alternative
Scope
Feature
Comments
vars
route
Additional criterion to match a route
Simple DSL with a couple of comparison operators and boolean operators
filter_func
route
Additional criterion to match a route
Full-fledged Lua function
Can access APISIX and nginx variables
No access to the context
script
route
Everything a plugin can do
Exclusive with plugins
Full access to the context
_meta.filter
plugin
Execute a plugin conditionally
Simple DSL with a couple of comparison operators and boolean operators
Before writing a plugin, I suggest you design your feature using one of the above alternatives (but script).
To go further:
Plugin
Script
lua-resty-expr
Plugin Common Configurations
Originally published at A Java Geek on August 25th, 2024
The post When (not) to write an Apache APISIX plugin appeared first on foojay.