Ready to speed up your Kong Lua custom plugin development process?
1. Before diving into this post, make sure you're familiar with the basics of plugin development and have gone through the basics described in our [Kong documentation](https://docs.konghq.com/gateway/2.6.x/plugin-development)Kong documentation.
Now, let's dive in…here are the best practices for Kong custom plugins that will help you standardize processes and speed up development.
2. Two crucial pieces of tooling will help you get started with custom plugin development. I recommend that developers use these two projects to jump-start the development of their custom plugins. Those include:
3. Nothing should be hardcoded in the plugin. You should provide all external configurations for a plugin via [plugin configuration](https://docs.konghq.com/gateway/2.6.x/plugin-development/plugin-configuration)plugin configuration.
4. You should perform validation for all fields in the plugin configuration. All fields should have appropriate types and default values (as applicable) and be specified as optional or mandatory.
5. You should configure entity checks to validate fields using the various field validators that [Kong provides](https://docs.konghq.com/gateway/2.6.x/plugin-development/plugin-configuration/#describing-your-configuration-schema)Kong provides or using custom validators validators only if necessary. Always make sure that your plugin schema is declarative.
6. A common mistake here is that a field in the schema.lua is given a default value, but a required flag is not specified. This will allow users to configure a JSON null value and set the field to an empty value.
7. Use the [Plugin Development Kit](https://docs.konghq.com/gateway/2.6.x/pdk)Plugin Development Kit (PDK) for calling Kong internal functions when implementing custom logic. Do not call Nginx variables directly unless absolutely necessary. The Kong PDK is guaranteed to be forward compatible and provides various helper functions to manipulate the API request and response.
8. Do not block when performing your operations because it will add latency to your API request. Any non-blocking I/O will also incur the same latency, and these result in requests sitting on the CPU, blocking other requests as well, impacting Kong's performance as a whole. When calling any external entities, configure a timeout for the call. Ensure that any libraries used work with OpenResty/Nginx; do not use libraries designed to work with standalone Lua.
9. Every plugin feature should be accompanied by unit and integration [tests](https://docs.konghq.com/gateway/2.6.x/plugin-development/tests)tests with high coverage of the plugin functionality. Define unit tests for testing sub-modules of your plugin and integration tests for end-to-end testing against various Kong versions, data sources and requests.
10. Ensure that tests cover all possible flows or plugin usage. Use [luacov](https://keplerproject.github.io/luacov)luacov for test coverage analysis.
11. Ensure performance/load testing with the plugin enabled. You can use various tools for load testing; one example is [k6](https://k6.io)k6. Load tests should cover multiple test cases such as performance under load, single users, multiple users, low to high request rates. Capture and report on the load test scripts above using Kong latency metrics HTTP Header "X-Kong-Proxy-Latency."
12. Follow a test-driven approach. That means you should define the tests first, implement your plugin and make the tests pass.
13. Kong comes with a set of test-helpers that make testing easier. Use Pongo to generate the help files using pongo docs.
14. Use appropriate levels when logging. The happy path of plugin execution should have minimal logs at the notice/info level, while error flows should log all warnings and errors at their respective log levels. All plugins should log a good amount of information at a debug level that can be used for troubleshooting purposes when required.
15. Catch and Log errors in plugin execution, especially flows that involve calling external systems.
16. Consider using (x)pcall for protected execution [https://www.lua.org/pil/8.4.html](https://www.lua.org/pil/8.4.html)https://www.lua.org/pil/8.4.html when making function calls.
17. Make use of the kong.log and kong.inspect() PDK functions to log information in your plugins. Ensure that the various log entries use appropriate log levels based on the severity of the log message.
18. Full access to the Kong datastore in custom plugins is only available in the [classic mode](https://docs.konghq.com/enterprise/2.5.x/deployment/classic-deployment)classic mode of deployment. Learn more about [storing and accessing custom entities](https://docs.konghq.com/gateway/2.6.x/plugin-development/custom-entities)storing and accessing custom entities. We encourage using Redis as a datastore for custom plugins, as your plugins will also be compatible with Hybrid and DB-less modes.
19. In hybrid mode, you can create custom entities from a control plane but not from a data plane. So configuring Kong on the CP (adding a basic-auth credential, for example) is available, but writing in-band data (like a rate-limiting counter) is unavailable.
20. When using the Hybrid deployment mode, use Redis for accessing data in-band between data plane nodes.
21. Optimizing frequently accessed data by custom plugins by using:
22. Depending on the Kong deployment platform, there are various mechanisms for deploying custom plugins:
Reference links: [operating system, e.g., ubuntu](https://docs.konghq.com/gateway-oss/2.4.x/plugin-development/distribution)operating system, e.g., ubuntu & [Kubernetes](https://docs.konghq.com/kubernetes-ingress-controller/1.3.x/guides/setting-up-custom-plugins)Kubernetes
23. For deployments on Docker and Kubernetes, create a custom image from the Kong image, which installed the custom plugin. This will ensure that all Kong instances from this image already have the custom plugin installed. You could build a [custom image](https://github.com/Kong/docker-kong/tree/master/customize)custom image using docker-kong.
24. When distributing plugins, there are two options;
25. Pongo can be used for automated builds, testing and packaging for Kong custom plugins. The Kong plugin template consists of a reference [travis.yml file](https://github.com/Kong/kong-plugin/blob/master/.travis.yml)travis.yml file for performing CI using Kong:
26. Add comments to code, including function headers.
27. If a single Lua file becomes too big, separate functions into a separate Lua file for re-usability.
28. Write a Readme for the plugin that includes:
Follow this tutorial to create your [custom Lua plugin for Kong Gateway](https://konghq.com/blog/custom-lua-plugin-kong-gateway)custom Lua plugin for Kong Gateway.
Have questions or want to stay in touch with the Kong community? Join us wherever you hang out:
⭐ [Star us on GitHub](https://github.com/Kong/kong)Star us on GitHub
🐦 [Follow us on Twitter](https://twitter.com/thekonginc)Follow us on Twitter
🍻 [Join our Meetups](https://www.meetup.com/pro/kong)Join our Meetups
Recently, I came across a request from one of our community users looking for a Kong plugin that could look up address details based on a few location search keywords. There are many libraries that support geocoding. I decided to pick up a Python Li
[](https://konghq.com/blog/engineering/building-plugins-for-kong-gateway-using-python)
In this blog post, we will explore how organizations can leverage Kong and OpenTelemetry to establish and monitor Service Level Objectives (SLOs) and manage error budgets more effectively. By tracking performance metrics and error rates against pred
[](https://konghq.com/blog/engineering/track-service-level-objectives-with-kong-and-opentelemetry)
In the Kubernetes world, the Ingress API has been the longstanding staple for getting access to your Services from outside your cluster network. Ingress has served us well over the years and can be found present in several dozen different implementa
[](https://konghq.com/blog/engineering/gateway-api-from-early-years-to-ga)
Many of Kong’s features rely on timers, such as caching, DNS, and health checks. Kong also runs some async tasks using the timer, such as the rate-limiting plugin, which connects to the database using the timer to make the request finish quickly. As
[](https://konghq.com/blog/engineering/scalable-timer-library)
Viktor Gamov and Rick Spurgeon co-authored this blog post. Kong Gateway provides dynamic plugin ordering allowing administrators to control plugin execution order. Dynamic plugin ordering was added in Kong Enterprise 3.0 and the full technical re
[](https://konghq.com/blog/engineering/kong-dynamic-plugin-ordering)
In applications built on a system of microservices , developers should always be on the lookout for opportunities to eliminate unnecessary use of resources, such as database queries, network hops or service requests. API gateway cache (or response
[](https://konghq.com/blog/engineering/api-gateway-cache)
As part of the Kong Gateway 2.6 release, we shipped a brand new jq plugin for anyone with an enterprise license to use. It’s like we combined the request and response transformer plugins to form a single, more powerful plugin—supercharging the w
[](https://konghq.com/blog/engineering/jq-plugin)