Skip to content
🦍 The Cloud-Native API Gateway
Lua Perl Other
Branch: master
Clone or download
locao and hishamhm fix(file-log) only check if log filename is valid (#5028)
file-log plugin was creating the log file when validating filename. As
declarative config parsing runs earlier, the file was being created
with master process owner permissions. This change validates only if
the filename used is valid and gives file-log plugin responsibility
on creating the log file, using worker process owner permissions.

Co-authored-by: Hisham Muhammad <>
Latest commit 891ebe3 Sep 12, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.ci chore(ci) add the ability to use the Kong CI setup from external repo… Sep 9, 2019
.github chore(gh) remove OOD notation in GitHub issue template Jan 11, 2019
bin feat(*) remove the _G write guard log in CLI and rbusted Jul 2, 2019
kong fix(file-log) only check if log filename is valid (#5028) Sep 12, 2019
scripts feat(scripts) introduce merge-master-into-next script Jun 24, 2019
spec fix(file-log) only check if log filename is valid (#5028) Sep 12, 2019
t fix(pdk) make sure `response.add_header` works in `rewrite` phase (#4888 Aug 15, 2019
.busted fix(*) improve Lua paths for dev environments (#2845) Aug 24, 2017
.editorconfig chore(conf): add .editorconfig (#2670) Oct 26, 2017
.gitignore chore(make) add grpcurl dependency Jul 23, 2019
.luacheckrc feat(runloop) introduce the 'kong' global variable and PDK Jun 19, 2018
.requirements chore(ci) adjust Kong to build multi architecture assets via kong-bui… Aug 15, 2019
.travis.yml chore(ci) add the ability to use the Kong CI setup from external repo… Sep 9, 2019 docs(changelog) fix typo Sep 4, 2019 docs(code-of-conduct) adding a Code of Conduct Mar 28, 2017 style(contributing) remove double line breaks before headings Jul 18, 2019
COPYRIGHT docs(legal) add license text when missing Jul 31, 2018 docs(developers) add a doc describing the development environment (#4944 Sep 2, 2019
LICENSE chore(*) bump license year to 2019 Jan 4, 2019
Makefile chore(ci) add the ability to use the Kong CI setup from external repo… Sep 9, 2019 docs(readme) minor punctuation fix Jul 8, 2019 docs(upgrade) add template diff to 1.3.0 upgrade path Aug 21, 2019
kong-1.3.0-0.rockspec release: 1.3.0 Aug 21, 2019
kong.conf.default hotfix(conf) allow injecting the `ssl_protocols` directive (#4895) Aug 15, 2019

Build Status License Twitter

Kong is a cloud-native, fast, scalable, and distributed Microservice Abstraction Layer (also known as an API Gateway, API Middleware or in some cases Service Mesh). Made available as an open-source project in 2015, its core values are high performance and extensibility.

Actively maintained, Kong is widely used in production at companies ranging from startups to Global 5000 as well as government organizations.

Installation | Documentation | Forum | Blog | IRC (freenode): #kong | Nightly Builds


Why Kong?

If you are building for the web, mobile, or IoT (Internet of Things) you will likely end up needing common functionality to run your actual software. Kong can help by acting as a gateway (or a sidecar) for microservices requests while providing load balancing, logging, authentication, rate-limiting, transformations, and more through plugins.


  • Cloud-Native: Platform agnostic, Kong can run from bare metal to Kubernetes.
  • Dynamic Load Balancing: Load balance traffic across multiple upstream services.
  • Hash-based Load Balancing: Load balance with consistent hashing/sticky sessions.
  • Circuit-Breaker: Intelligent tracking of unhealthy upstream services.
  • Health Checks: Active and passive monitoring of your upstream services.
  • Service Discovery: Resolve SRV records in third-party DNS resolvers like Consul.
  • Serverless: Invoke and secure AWS Lambda or OpenWhisk functions directly from Kong.
  • WebSockets: Communicate to your upstream services via WebSockets.
  • OAuth2.0: Easily add OAuth2.0 authentication to your APIs.
  • Logging: Log requests and responses to your system over HTTP, TCP, UDP, or to disk.
  • Security: ACL, Bot detection, whitelist/blacklist IPs, etc...
  • Syslog: Logging to System log.
  • SSL: Setup a Specific SSL Certificate for an underlying service or API.
  • Monitoring: Live monitoring provides key load and performance server metrics.
  • Forward Proxy: Make Kong connect to intermediary transparent HTTP proxies.
  • Authentications: HMAC, JWT, Basic, and more.
  • Rate-limiting: Block and throttle requests based on many variables.
  • Transformations: Add, remove, or manipulate HTTP requests and responses.
  • Caching: Cache and serve responses at the proxy layer.
  • CLI: Control your Kong cluster from the command line.
  • REST API: Kong can be operated with its RESTful API for maximum flexibility.
  • Geo-Replicated: Configs are always up-to-date across different regions.
  • Failure Detection & Recovery: Kong is unaffected if one of your Cassandra nodes goes down.
  • Clustering: All Kong nodes auto-join the cluster keeping their config updated across nodes.
  • Scalability: Distributed by nature, Kong scales horizontally by simply adding nodes.
  • Performance: Kong handles load with ease by scaling and using NGINX at the core.
  • Plugins: Extendable architecture for adding functionality to Kong and APIs.

For more info about plugins and integrations, you can check out the Kong Hub.


Kong comes in many shapes. While this repository contains its core's source code, other repos are also under active development:


If you are planning on developing on Kong, you'll need a development installation. The next branch holds the latest unreleased source code.

You can read more about writing your own plugins in the Plugin Development Guide, or browse an online version of Kong's source code documentation in the Plugin Development Kit (PDK) Reference.


You can use Docker / docker-compose and a mounted volume to develop Kong by following the instructions on Kong/kong-build-tools.


You can use a Vagrant box running Kong and Postgres that you can find at Kong/kong-vagrant.

Source Install

Kong mostly is an OpenResty application made of Lua source files, but also requires some additional third-party dependencies. We recommend installing those by following the source install instructions at

Instead of following the second step (Install Kong), clone this repository and install the latest Lua sources instead of the currently released ones:

$ git clone
$ cd kong/

# you might want to switch to the development branch. See
$ git checkout next

# install the Lua sources
$ luarocks make

Running for development

Check out the development section of the default configuration file for properties to tweak in order to ease the development process for Kong.

Modifying the lua_package_path and lua_package_cpath directives will allow Kong to find your custom plugin's source code wherever it might be in your system.


Install the development dependencies (busted, luacheck) with:

$ make dev

Kong relies on three test suites using the busted testing library:

  • Unit tests
  • Integration tests, which require Postgres and Cassandra to be up and running
  • Plugins tests, which require Postgres to be running

The first can simply be run after installing busted and running:

$ make test

However, the integration and plugins tests will spawn a Kong instance and perform their tests against it. As so, consult/edit the spec/kong_tests.conf configuration file to make your test instance point to your Postgres/Cassandra servers, depending on your needs.

You can run the integration tests (assuming both Postgres and Cassandra are running and configured according to spec/kong_tests.conf) with:

$ make test-integration

And the plugins tests with:

$ make test-plugins

Finally, all suites can be run at once by simply using:

$ make test-all

Consult the script for a more advanced example usage of the tests suites and the Makefile.

Finally, a very useful tool in Lua development (as with many other dynamic languages) is performing static linting of your code. You can use luacheck (installed with make dev) for this:

$ make lint


When developing, you can use the Makefile for doing the following operations:

Name Description
install Install the Kong luarock globally
dev Install development dependencies
lint Lint Lua files in kong/ and spec/
test Run the unit tests suite
test-integration Run the integration tests suite
test-plugins Run the plugins test suite
test-all Run all unit + integration + plugins tests at once

Enterprise Support & Demo

If you are working in a large organization you should learn more about Kong Enterprise.


Copyright 2016-2019 Kong Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
You can’t perform that action at this time.