Spinning up an API Gateway with DBLess Kong Gateway

by Syed Rakib Al Hasan

Photo by Waldemar Brandt on Unsplash

What is an API Gateway?

An API Gateway sits between the clients and the backends as a “proxy”. It takes requests from clients, forwards them to backend services, and returns with a response - meanwhile taking care of CORS validation, TLS termination, JWT authentication, header injection, session management, response transformation, rate-limiting, ACLs etc etc along the way.

What is Kong Gateway?

A product of KongHQ, the Kong Gateway is an API Gateway that is designed to be lightweight and decentralised (available in free and paid models). Kong Gateway is a Lua application running in NGINX and distributed with OpenResty - setting itself up as a foundation for modular extensibility via plugins.

What is “DBLess” Kong Gateway?

Traditionally, the configs in Kong Gateway (routes, services, plugins etc) were stored in a database. However, in the DBLess mode (also known as the “declarative” method), you use nothing but code (commonly saved as a declarative.yaml file) to manage all that. This makes it easily versionable and avoids the need to maintain a separate database.

However, this does make the Admin APIs read-only (since the only way to change a config is to do it through file changes), and it limits the number of plugins that can be used - as certain plugins do require a centralised database.

Enough definitions. Let’s launch a Kong

Photo by Joshua J. Cotten on Unsplash

We will create a small API Gateway inside a docker-compose container which will proxy our requests to a remote service, will be served over HTTPS-only, and be testable from localhost without requiring deployment.

Just download the files above into a directory & run docker-compose up in your terminal from that directory - you are good to go.

Testing the API Gateway

Photo by Alex Kondratiev on Unsplash

DISCLAIMER: While testing the APIs over HTTPS, you may face an “insecure connection” warning ⛔️. That is because the Kong Gateway (out-of-the-box) installs a self-signed SSL certificate to encrypt your connection and self-signed certs are not authorized by clients & browsers.

Insecure connections should NEVER be trusted in production environments. For this development/testing purpose, however, we can ignore the warning and proceed with the insecure connection.

We could always install a proper CA-signed SSL certificate by using the certificates: attribute in our declarative.yaml file. But it is beyond the scope of this demo for now. Hence, we will skip it.

First let’s test the Status APIs

Over HTTP protocol

• http://localhost:8903/status | http://localhost:8903/metrics

Over HTTPS protocol

• https://localhost:8904/status | https://localhost:8904/metrics

Now, let’s test the Admin APIs

Admin APIs are read-only when running Kong Gateway in DBLess / Declarative mode.

Over HTTP protocol:

• http://localhost:8901/ | http://localhost:8901/services

Over HTTPS protocol:

• https://localhost:8902/ | https://localhost:8902/services

Finally, let’s test our proxy APIs

Photo by Tom Dahm on Unsplash

Visit the following URL

• http://localhost/mock - should return status:404 with message: “no Route matched with those values” ⛔️.

🤔 This is because… our declarative.yaml file has declared a specific host “example.hello-kong-test.com” for this /mock route. So, this route in our Kong Gateway must be accessed over that specific host only.

To make it accessible over any host, we could’ve removed the hosts attribute from that route and that would be treated as a wildcard (*) entry then.

Now, visit the same URL again over the specific host instead

• http://example.hello-kong-test.com/mock - should return with an error saying DNS_PROBE_FINISHED_NXDOMAIN or “Could not resolve host: example.hello-kong-test.com” etc ⛔️.

🤔 This is because… there is no known domain name like that. In order to access a locally running service over a non-localhost domain name, you need to update the hosts entry file. Add this line 127.0.0.1 example.hello-kong-test.com into your /etc/hosts file - sudo privileges maybe required.

Once done, visit the same URL again

• http://example.hello-kong-test.com/mock - should now return status:426 with a message: “Please use HTTPS protocol” ⛔️.

🤔 This is because… our declarative.yaml file has allowed a single protocol “https” only and has purposefully disallowed the plaintext “http” protocol for this route. So this route must be accessed over HTTPS only.

To make it accessible over any protocol, we could’ve removed the protocols attribute from that route and that would be treated as a wildcard (*) entry then.

Now, visit the same URL again via https protocol now

• https://example.hello-kong-test.com/mock - should now return status:200 with message: “Hello Kong” - properly proxied from a remote mockbin.org endpoint ✅🥳🎉.

Conclusion

This was just a small demo of a HTTPS enabled API Gateway built with Kong Gateway - using only code - without having to manage any database. You can extend its use cases further in hundreds of different ways by leveraging the various plugins available at Kong Plugins Hub.