Using custom Plugins in APISIX Ingress
This tutorial explains how you can configure custom Plugins to work with APISIX Ingress.
#
PrerequisitesBefore you move on, make sure you:
- Have access to a Kubernetes cluster. This tutorial uses minikube.
- Install Helm to deploy the APISIX Ingress controller.
#
Deploy httpbinWe will deploy a sample service, kennethreitz/httpbin, for this tutorial.
You can deploy it to your Kubernetes cluster by running:
kubectl run httpbin --image kennethreitz/httpbin --port 80
kubectl expose pod httpbin --port 80
#
Writing a Custom PluginIn this tutorial we will focus only on configuring custom Plugins to work with APISIX Ingress.
tip
To learn more about how to write custom Plugins, see the documentation. You can also write external Plugins in programming languages like Java, Python, and Go.
In this tutorial, we will use a sample Plugin that rewrites the response body from the Upstream with a custom value:
-- some required functionalities are provided by apisix.core
local core = require("apisix.core")
-- define the schema for the Plugin
local schema = {
type = "object",
properties = {
body = {
description = "custom response to replace the Upstream response with.",
type = "string"
},
},
required = {"body"},
}
local plugin_name = "custom-response"
-- custom Plugins usually have priority between 1 and 99
-- higher number = higher priority
local _M = {
version = 0.1,
priority = 23,
name = plugin_name,
schema = schema,
}
-- verify the specification
function _M.check_schema(conf)
return core.schema.check(schema, conf)
end
-- run the Plugin in the access phase of the OpenResty lifecycle
function _M.access(conf, ctx)
return 200, conf.body
end
return _M
Now we can set up APISIX to utilize this Plugin and enable it for specific Routes.
While one approach is to create a customized build of APISIX that includes the Plugin's code, this is not a simple task.
An alternative method involves generating a ConfigMap from the Lua code and then mounting it onto the APISIX instance within the Kubernetes environment.
To create the ConfigMap, you can execute the following command:
kubectl create ns ingress-apisix
kubectl create configmap custom-response-config --from-file=./apisix/plugins/custom-response.lua -n ingress-apisix
Now we can deploy APISIX and mount this ConfigMap.
#
Deploying APISIXWe will use Helm to deploy APISIX and APISIX Ingress controller.
First, we will update the values.yaml
file to mount the custom Plugin we created before.
You can configure the Plugin under customPlugins
as shown below:
customPlugins:
enabled: true
plugins:
- name: "custom-response"
attrs: {}
configMap:
name: "custom-response-config"
mounts:
- key: "custom-response.lua"
path: "/usr/local/apisix/apisix/plugins/custom-response.lua"
You should also enable the Plugin by adding it to the plugins
list:
plugins:
- api-breaker
- authz-keycloak
- basic-auth
- batch-requests
- consumer-restriction
- cors
...
...
- custom-response
Finally you can enable the Ingress controller and configure the gateway to be exposed to external traffic. For this, set gateway.type=NodePort
, ingress-controller.enabled=true
, and ingress-controller.config.apisix.serviceNamespace=ingress-apisix
in your values.yaml
file.
Now we can run helm install
with this updated values.yaml file:
helm install apisix apisix/apisix -n ingress-apisix --values ./apisix/values.yaml
APISIX and APISIX Ingress controller should be ready in some time with the custom Plugin mounted successfully.
#
Testing without Enabling the PluginFirst, let's create a Route without our custom Plugin enabled.
We will create a Route using the ApisixRoute CRD:
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: api-route
spec:
http:
- name: route
match:
hosts:
- local.navendu.me
paths:
- /api
backends:
- serviceName: bare-minimum-api
servicePort: 8080
We can now test the created Route:
curl http://127.0.0.1:52876/api -H 'host:local.navendu.me'
This will give back the response from our Upstream service as expected:
Hello from API v1.0!
#
Testing the Custom PluginNow let's update the Route and enable our custom Plugin on the Route:
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: api-route
spec:
http:
- name: route
match:
hosts:
- local.navendu.me
paths:
- /api
backends:
- serviceName: bare-minimum-api
servicePort: 8080
plugins:
- name: custom-response
enable: true
config:
body: "Hello from your custom Plugin!"
Now, our custom Plugin should rewrite the Upstream response with "Hello from your custom Plugin!"
Let's apply this CRD and test the Route and see what happens:
curl http://127.0.0.1:52876/api -H 'host:local.navendu.me'
And as expected, we get the rewritten response from our custom Plugin:
Hello from your custom Plugin!