Kong is a scalable, open source API Layer (also known as an API Gateway, or API Middleware). Kong was originally built at Mashape to secure, manage and extend over 15,000 Microservices for its API Marketplace, which generates billions of requests per month.
Backed by the battle-tested NGINX with a focus on high performance, Kong was made available as an open-source platform in 2015. Under active development, Kong is now used in production at hundreds of organizations from startups, to large enterprises and government departments including: The New York Times, Expedia, Healthcare.gov, The Guardian, Condè Nast and The University of Auckland.
Website | Docs | Installation | Blog | Mailing List | Gitter Chat | freenode: #kong
Summary
- Features
- Why Kong?
- Benchmarks
- Distributions
- Community Resources and Tools
- Roadmap
- Development
- Enterprise Support & Demo
- License
Features
- CLI: Control your Kong cluster from the command line just like Neo in The Matrix.
- 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.
- Cluster Awareness: All Kongs auto-join the cluster keeping config updated across nodes.
- Scalability: Distributed by nature, Kong scales horizontally simply by adding nodes.
- Performance: Kong handles load with ease by scaling and using NGINX at the core.
- Developer Portal: With Gelato integration, build beautiful portals for easy developer on-boarding.
- Plugins: Extendable architecture for adding functionality to Kong and APIs.
- OAuth2.0: Add easily an OAuth2.0 authentication to your APIs.
- Logging: Log requests and responses to your system over HTTP, TCP, UDP or to disk.
- JWT: Verify and authenticate JSON Web Tokens.
- HMAC: Add HMAC Authentication to your APIs.
- ACL: Acccess Control for your API Consumers.
- IP-restriction: Whitelist or blacklist IPs that can make requests.
- Response-Rate-Limiting: Rate limiting based on custom response header value.
- API Analytics: Visualize, Inspect and Monitor API traffic with Galileo.
- Loggly Integration: Push your traffic data through your Loggly account.
- DataDog Integration: Easy Data monitoring through DataDog. DevOps will love it!
- Runscope Integration: Test and Monitor your APIs.
- 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.
- Authentication: Manage consumer credentials query string and header tokens.
- Rate-limiting: Block and throttle requests based on IP, authentication or body size.
- Transformations: Add, remove or manipulate HTTP requests and responses.
- CORS: Enable cross-origin requests to your APIs that would otherwise be blocked.
- Anything: Need custom functionality? Extend Kong with your own Lua plugins!
For more info about plugins, you can check out the Plugin Gallery.
Why Kong?
If you're building for web, mobile or IoT (Internet of Things) you will likely end up needing common functionality on top of your actual software. Kong can help by acting as a gateway for HTTP requests while providing logging, authentication, rate-limiting and more through plugins.
Benchmarks
We've load tested Kong and Cassandra on AWS; you can see our benchmark report here.
Distributions
Kong comes in many shapes. While this repository contains its core's source code, other repos are also under active development:
- Kong Docker: A Dockerfile for running Kong in Docker.
- Kong Packages: Packaging scripts for deb, rpm and osx distributions.
- Kong Vagrant: A Vagrantfile for provisioning a development ready environment for Kong.
- Kong Homebrew: Homebrew Formula for Kong.
- Kong CloudFormation: Kong in a 1-click deployment for AWS EC2
- Kong AWS AMI: Kong AMI on the AWS Marketplace.
- Kong on Microsoft Azure: Run Kong using Azure Resource Manager.
- Kong on Heroku: Deploy Kong on Heroku in one click.
- Kong and Instaclustr: Let Instaclustr manage your Cassandra cluster.
Community Resources and Tools
Resources:
- The story behind Kong
- Kong mentioned for the Empire PaaS
- Realtime API Management with Pushpin
- How to create your own Kong plugin
- Instaclustr partners with Kong
- How to deploy Kong on Azure
- Kong intro in Portuguese
- Kong tutorial in Japanese 1
- Kong tutorial in Japanese 2
- HAProxy + Kong
- Learn Lua in 15 minutes
- A Question about Microservices
- Kong Intro in Chinese
Videos:
- Kong Intro Tutorial
- Kong mentioned at Hashicorp Conf
- Kong Demo in Portuguese
- OAuth2 with Kong
- Kong with Docker
Podcasts:
Here is a list of third-party tools maintained by the community:
- Ansible role for Kong on Ubuntu
- Biplane: declarative configuration in Crystal
- Bonobo: key management (with Mashery migration scripts)
- Chef cookbook
- Django Kong Admin: Admin UI in Python
- Jungle: Admin UI in JavaScript
- Kong Dashboard: Admin UI in JavaScript
- Kong for CanopyCloud
- Kong image waiting for Cassandra
- Kong image for Tutum
- Kong-UI: Admin UI in JavaScript
- Konga: CLI Admin tool in JavaScript
- Kongfig: Declarative configuration in JavaScript
- Kongfig on Puppet Forge
- Puppet recipe
- Puppet module on Puppet Forge
- Python-Kong: Admin client library for Python
- .NET-Kong: Admin client library for .NET
Roadmap
You can find a detailed Roadmap of Kong on the Wiki.
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 Public Lua API Reference.
Vagrant
You can use a Vagrant box running Kong and Cassandra that you can find at Mashape/kong-vagrant.
Source Install
First, you will need to already have Kong installed. Install Kong by following one of the methods described at getkong.org/download. Then, make sure you have downloaded Cassandra and that it is running. These steps will override your Kong installation with the latest source code:
$ git clone https://github.com/Mashape/kong
$ cd kong/
# You might want to switch to the development branch. See CONTRIBUTING.md for more infos
$ git checkout next
# Install latest Kong globally using Luarocks, overriding the version previously installed
$ make install
Running for development
It is best to run Kong with a development configuration file. Such a file can easily be created following those instructions:
# Install all development dependencies and create your environment
configuration files
$ make dev
# Finally, run Kong with the just created development configuration
$ kong start -c kong_DEVELOPMENT.yml
Since you use a configuration file dedicated to development, feel free to
customize it as you wish. For example, the one generated by make dev
includes
the following changes: the
lua_package_path
directive specifies that the Lua modules in your current directory will be used
in favor of the system installation. The
lua_code_cache
directive being turned off, you can start Kong, edit your local files, and test
your code without restarting Kong.
To stop Kong, you will need to specify the configuration file too:
$ kong stop -c kong_DEVELOPMENT.yml
# or
$ kong reload -c kong_DEVELOPMENT.yml
Learn more about the CLI and configuration options in the documentation.
Tests
Kong relies on three test suites:
- Unit tests
- Integration tests, which require a running Cassandra cluster
- Plugins tests, which are a mix of unit and integration tests, which also require a Cassandra cluster
The first can simply be run afte installing busted and running:
$ busted spec/unit
The integration tests require you to have a configuration file at
./kong_TEST.yml
and to make it point to a running Cassandra cluster (it will
use a keyspace of its own). Such a file is also created by make dev
, but you
can create one of your own or customize it (you might want to change the
logging settings, for example):
$ busted spec/integration
The make dev
command can create a default kong_TEST.yml
file.
The plugins tests also require a ./kong_TEST.yml
file and a running Cassandra
cluster, and be be run with:
$ busted spec/plugins
Finally, all suites can be run at once by simply running busted
.
Tools
Various tools are used for documentation and code quality. They can all be easily installed by running:
$ make dev
Code coverage is analyzed by luacov from the busted unit tests:
$ busted --coverage
$ luacov kong
# or
$ make coverage
The code is statically analyzed and linted by luacheck. It is easier to use the Makefile to run it:
$ make lint
The documentation is written according to the ldoc format and can be generated with:
$ ldoc -c config.ld kong/
# or
$ make doc
We maintain this documentation on the Public Lua API Reference so it is unlikely that you will have to generate it, but it is useful to keep that information in mind when documenting your modules if you wish to contribute.
Makefile
When developing, you can use the Makefile
for doing the following operations:
Name | Description |
---|---|
install |
Install the Kong luarock globally |
dev |
Setup your development environment |
clean |
Clean your development environment |
doc |
Generate the ldoc documentation |
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 tests at once |
coverage |
Run all tests + coverage report |
Enterprise Support & Demo
Learn more about Kong Priority Support, Products, HA, Demo, Training, API Certifications and Professional Services.
License
Copyright 2016 Mashape, 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
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.