generated from Kong/kong-plugin
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
4 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,69 +1,5 @@ | ||
| [](https://github.com/Kong/kong-plugin/actions/workflows/test.yml) | ||
| [](https://github.com/Kong/kong-plugin/actions/workflows/lint.yml) | ||
| # Installation | ||
|
|
||
| Kong plugin template | ||
| ==================== | ||
|
|
||
| This repository contains a very simple Kong plugin template to get you | ||
| up and running quickly for developing your own plugins. | ||
|
|
||
| This template was designed to work with the | ||
| [`kong-pongo`](https://github.com/Kong/kong-pongo) and | ||
| [`kong-vagrant`](https://github.com/Kong/kong-vagrant) development environments. | ||
|
|
||
| Please check out those repos `README` files for usage instructions. For a complete | ||
| walkthrough check [this blogpost on the Kong website](https://konghq.com/blog/custom-lua-plugin-kong-gateway). | ||
|
|
||
|
|
||
| Naming and versioning conventions | ||
| ================================= | ||
|
|
||
| There are a number "named" components and related versions. These are the conventions: | ||
|
|
||
| * *Kong plugin name*: This is the name of the plugin as it is shown in the Kong | ||
| Manager GUI, and the name used in the file system. A plugin named `my-cool-plugin` | ||
| would have a `handler.lua` file at `./kong/plugins/my-cool-plugin/handler.lua`. | ||
|
|
||
| * *Kong plugin version*: This is the version of the plugin code, expressed in | ||
| `x.y.z` format (using Semantic Versioning is recommended). This version should | ||
| be set in the `handler.lua` file as the `VERSION` property on the plugin table. | ||
|
|
||
| * *LuaRocks package name*: This is the name used in the LuaRocks eco system. | ||
| By convention this is `kong-plugin-[KongPluginName]`. This name is used | ||
| for the `rockspec` file, both in the filename as well as in the contents | ||
| (LuaRocks requires that they match). | ||
|
|
||
| * *LuaRocks package version*: This is the version of the package, and by convention | ||
| it should be identical to the *Kong plugin version*. As with the *LuaRocks package | ||
| name* the version is used in the `rockspec` file, both in the filename as well | ||
| as in the contents (LuaRocks requires that they match). | ||
|
|
||
| * *LuaRocks rockspec revision*: This is the revision of the rockspec, and it only | ||
| changes if the rockspec is updated. So when the source code remains the same, | ||
| but build instructions change for example. When there is a new *LuaRocks package | ||
| version* the *LuaRocks rockspec revision* is reset to `1`. As with the *LuaRocks | ||
| package name* the revision is used in the `rockspec` file, both in the filename | ||
| as well as in the contents (LuaRocks requires that they match). | ||
|
|
||
| * *LuaRocks rockspec name*: this is the filename of the rockspec. This is the file | ||
| that contains the meta-data and build instructions for the LuaRocks package. | ||
| The filename is `[package name]-[package version]-[package revision].rockspec`. | ||
|
|
||
| Example | ||
| ------- | ||
|
|
||
| * *Kong plugin name*: `my-cool-plugin` | ||
|
|
||
| * *Kong plugin version*: `1.4.2` (set in the `VERSION` field inside `handler.lua`) | ||
|
|
||
| This results in: | ||
|
|
||
| * *LuaRocks package name*: `kong-plugin-my-cool-plugin` | ||
|
|
||
| * *LuaRocks package version*: `1.4.2` | ||
|
|
||
| * *LuaRocks rockspec revision*: `1` | ||
|
|
||
| * *rockspec file*: `kong-plugin-my-cool-plugin-1.4.2-1.rockspec` | ||
|
|
||
| * File *`handler.lua`* is located at: `./kong/plugins/my-cool-plugin/handler.lua` (and similar for the other plugin files) | ||
| 1. Copy all `kong/plugins/http-callout/*.lua` files into `/usr/local/share/lua/5.1/kong/plugins/http-callout/.` | ||
| 2. Activate the plugin by setting Kong config: `plugins = bundled,http-callout` (or Helm: `plugins: "bundled,http-callout"`) | ||
| 3. Upload the `kong/plugins/http-callout/schema.lua` to Konnect "Custom Plugins" menu, in each control plane it's required |