Giving Your Legacy Applications an API Facelift
Let's face it: In today's modern world of cloud and containers, there are still thousands of legacy applications that were not written with an API-first approach. Some legacy systems can still provide tremendous value today, but the means for accessing them are completely out of date, thus rendering them almost useless.
In this post, we'll walk through creating an extremely simple—but powerful—Kong Gateway Lua plugin to showcase how you could put an API in front of a legacy application that you could otherwise only access through a CLI.
To draw a parallel with a real-world scenario, this is the case of one of my customers (who shall remain nameless). The company has a need to connect to a disparate array of legacy endpoints and expose them via REST APIs to build more modern applications.
Accessing such an endpoint system via a CLI is just one of the many applications my customer has to connect to. To avoid a full-blown integration implementation, a reusable plugin pattern such as the one we are talking about in this post might just do the trick.
Let's dig in.
What's in a Name?
I have affectionately named this Kong Gateway plugin Kronos. No specific reason other than I like the name, it works well as alliteration, and it reminds me of the movie The Incredibles—if you didn't see the movie, Kronos is the name of the plot for a giant robot falling from the sky and laying waste to a city, but there is no need to be dramatic. Or maybe there is.
Enter Pig Latin
In this example, we will imagine our legacy application is a Pig Latin translator. The application is written in Perl, which traditionally works like this:
I never learned Pig Latin, so this is pretty cool. The problem is, to run this application, we have to be in front of (or SSH into) the system so we can type out the command. Not cool anymore.
My customer's legacy applications are definitely much more complex than our Pig Latin translator, and that is perfectly fine. However, how we expose the Perl program in this tutorial is a blueprint anyone can use for exposing legacy applications that lack a REST API.
What You'll Need
Requirements:
- docker-compose
- If you'd like to try out the Pig Latin translator, install the Perl PigLatin module using cpan Lingua::PigLatin (you'll do this in the Kong shell, courtesy of Gojira)
- Gojira
- Access to the source code
- A Linux or Mac environment
If you haven't written Kong Gateway plugins before, a great environment for developing and testing them is Gojira. The instructions for setting up Gojira are outside the scope of this post, but rest assured that the setup is pretty straightforward. As you can see in the image below, I am running Gojira locally on my Mac.
Once Gojira is up and running, we'll need to install a couple of Kronos dependencies. You can do that in the Kong shell, which you can run by executing gojira shell.
In this shell, you'll need to install lua-resty-exec, luasocket and sockexec. You can easily install both Lua modules via luarocks install lua-resty-exec and luarocks install luasocket. Verify the installation with a show command like this.
The last step to run processes through Kronos on your host is to have a Unix domain socket on your file system. For that, you'll have to download the version of sockexec that matches your architecture.
Note: If you ever get to run this in a production-type environment, please make sure you have checks and balances so you don't end up doing more harm than good.
In this example post, Gojira is running an instance of Kong Gateway in a containerized environment, so I am leveraging the ARM-based build.
Extract the sockexec tarball on your local machine, and copy sockexec and sockexec.client to the /bin directory in your Kong shell. The result should look like this (don't forget to chmod +x both files).
To easily copy the files from your local development environment (i.e., your laptop) to the running Kong container, you can run a quick python one-liner from the directory where we extracted the tarball. Once the http server is running in that directory, bring the files over with something like curl, directly from the Kong shell. There are many ways to climb a tree, and this is just one of them.
The Plugin
That preamble to getting Kronos ready to go is by far the most time-consuming piece. As you'll see below, the actual implementation of Kronos is rather simple. Granted, there is plenty of room for improvement, but that can be an exercise for you, the reader. For now, the whole intent of this post is to show you the art of the possible and the powerful nature of Kong's plugin architecture.
There are some great tutorials out there for writing Kong Gateway plugins, and the official Kong documentation is wonderful to get the details on plugin development, too.
As mentioned at the beginning of this post, Kronos is a barebones, simple plugin. At its core, it is basically acting as a passthrough proxy to the host, where you can execute commands directly on it, courtesy of our prerequisites stated earlier. Kronos uses a strategy pattern, so you can specify the implementation that is touching the legacy endpoint. We will see this in more detail when we explore the source code.
At the very least, Kong plugins need two Lua files: handler.lua and schema.lua. The first file contains the logic for your plugin, and the second contains configuration parameters you can send to the plugin. In our case, there is also a third file, piglatin.lua, which implements the "piglatin" strategy.
First off is schema.lua, a simple schema with only one configurable parameter: strategy. It is via this config that we can specify what we will execute on our legacy endpoint. Additionally, we specify that we can't apply Kronos to a service, only to a consumer or a route.
handler.lua has the delegation implementation, which is a fancy way of saying that our handler is delegating calls to the appropriate strategy. In this example, we only have a single strategy called piglatin. Should the caller send anything other than that, we are going to get an error. For the purists out there, you should definitely implement defensive programming and make sure that the strategy is not nil before moving forward. You've been forewarned.
We implemented the one strategy we have been talking about in this post in piglatin.lua below. The most interesting parts are the declaration of the variable prog, and the body of the method _M.exec(args). prog depends on that Unix domain socket we mentioned earlier, which we will use to launch an external process from Kronos. In our implementation, that external process is Perl, pointing to our piglatin.pl file using the arguments passed in by the caller.
The path for the socket is entirely up to you, but it must exist (and it must be readable by the lua-resty-exec process), or else Kronos will not work. To create that socket, you'll have to execute the following.
Last, but not least, is the piglatin.pl file, which is the application we are exposing via a REST API. As you can see in piglatin.lua, our Perl file is in the /root directory. You are welcome to place it wherever you'd like; just make sure you modify the path in your strategy file accordingly. piglatin.pl is extremely simple, as you can see—this is a mock legacy application, after all.
And voila!
Suppose you were writing this to access your own legacy endpoints. In that case, you could have multiple strategies, more configuration parameters OR no strategies, and no configuration parameters at all! The art of the possible is just that: This is your canvas, and you are free to do with this as your requirements demand, without losing sight of providing the most secure means for doing so.
Now that we have the code behind us, let's call out one last step so you can tweak your code, reload Kong, rinse and repeat. One of the great advantages of Gojira is that you can edit your Lua files locally, and upon making any changes, all you have to do is reload Kong. The only magic you have to do to get this working is to mount the volume as you bring up Gojira (you'll do this once and then operate in the shell and your code, most of the time).
From there, you are off to the races. After modifying your code, simply reload Kong. You'll have to tell Kong to add the Kronos plugin explicitly, so don't ignore the export statement.
Setting Things Up
Wonderful! We have our prerequisites set and our code written. Now it is time to set things up. You might be wondering where the service, route and plugin are. However, as you noticed in our handler.lua file, we effectively intercept the request, delegating the strategy module to the execution of a command on the host and returning the output. This means there is no service! What we have to do is create a route and apply Kronos to that route.
Let's apply the plugin onto that route:
We are leveraging the Kong Admin API to create the route and apply the plugin to that route. If you'd like to know what port the Admin API is running on your local machine, you can find out through Gojira.
Taking Kronos for a Test Drive
Kong offers a terrific tool called Insomnia for designing, testing and debugging APIs. We will be using Insomnia to test out Kronos and finally get to use our Pig Latin translator! Let's first check the route and the plugin using Insomnia.
Our route is ready. Now, let's check the plugin. Below, we configured our Kronos plugin on the route with the same ID as the route shown above.
Last but not least, the fun part. Let's get some Pig Latin translation through an API call, shall we?
Notice X-Args in the header? We are sending the text we want to translate in the request's header—again, not to any service. In our code in handler.lua, we are grabbing the contents of that parameter and passing it right down to the strategy implementer (i.e., piglatin.lua). We take the standard output from the execution and pass it right back up the stack to the caller.
In a production deployment of a plugin such as Kronos, we would be remiss if we didn't state that you should put extra care into the flexibility placed on the parameters passed in and the commands executed on the host. That is to say, be mindful of the protection you should place on your commands and parameters so that we stop anything malicious in its tracks.
In Closing
To quote the Spider-Man movie, "With great power comes great responsibility." I bet you can start imagining how you can effectively use Kronos to do all sorts of things now that you have access to the underlying host. Without any checks and balances, a rogue strategy could lay waste to an underlying host. This is where the strategy pattern and Kong's plugin ecosystem come into play.
You can externalize implementing a strategy to an application owner, so they carry the burden of responsibility. With other Kong plugins, such as the OpenID Connect plugin, you can lock things down even further.
I cannot stress how useful something like Kronos can be for exposing legacy systems that might only have a CLI or any other antiquated interface—I hope you would agree. If anything, this post shows you the power of Kong and the flexibility you have at your fingertips for exposing the world via APIs.
Future Work
Accessing Windows hosts is another ball of wax, but it is possible to make it work with this framework. Stay tuned for a future post where we explore doing things on a Windows machine through Kronos. A Windows strategy has a nice ring to it.
Another improvement that we could apply to Kronos is that of executing a strategy asynchronously. This improvement could reduce latency upon making the API request. For this, we would have to expand the schema and potentially introduce callbacks. This topic might be an exciting third installment to the series.
Disclaimer
No pigs or other animals were harmed in the making of this blog post. Kronos is not a Kong product, nor is it in the roadmap to becoming a supported product nor plugin.
If you'd like more information on Kong, don't hesitate to contact Kong directly.
Once you've finished setting up Kronos for your legacy applications, you may find these other tutorials helpful:
- Building a Kong Gateway Plugin with JavaScript
- 8 Common API Gateway Request Transformation Policies
- 5 Steps to Serverless Security With the AWS Lambda Plugin
Have questions or want to stay in touch with the Kong community? Join us wherever you hang out: