More than just another GUI to KONG Admin API ![Build Status](https://camo.githubusercontent.com/150bcf45be4bad7f9f767512887c54b688986f8c20c9b122f2634921f6c21b5e/68747470733a2f2f7472617669732d63692e6f72672f70616e7473656c2f6b6f6e67612e7376673f6272616e63683d6d6173746572)
Konga is not an official app. No affiliation with Mashape.
- Features
- Compatibility
- Prerequisites
- Used libraries
- Installation
- Configuration
- Running Konga
- Konga API
- License
- Manage APIs and plugins
- Manage consumers, groups and credentials
- Mass import consumers from :
- CSV document
- Google Spreadsheets
- MySQL
- MongoDB
- more underway...
- Multiple nodes management
- GUI level authentication
- Multiple users (Only admin and user roles for now)
- Utilities API
Konga is built and tested on Kong 0.9.x but it probably works with older versions as well. Feedback on older versions compatibility is welcome.
- A running Kong installation
- Nodejs
- Npm
- Gulp
- Bower
- angular-sailsjs-boilerplate (awesome): https://github.com/tarlepp/angular-sailsjs-boilerplate
- Sails.js, http://sailsjs.org/
- AngularJS, https://angularjs.org/
- Bootstrap, http://getbootstrap.com/
Install npm
and node.js
. Instructions can be found here.
Install bower
, gulp
and sails
packages.
$ npm install bower gulp sails -g $ git clone https://github.com/pantsel/konga.git $ cd konga $ npm install
This will install all frontend and backend dependencies. If for some reason this fails,
try running $ npm install
in /backend and /frontend separately
You can configure your backend
and frontend
applications to use your environment specified
settings. Basically by default you don't need to make any configurations at all. With default configuration backend will be run on http://localhost:1337 and frontend on http://localhost:3001 (development) http://localhost:3000 (production).
There is an example of backend configuration file on following path.
/backend/config/local_example.js
Just copy this to /backend/config/local.js
and make necessary changes to it. Note that this
local.js
file is in .gitignore so it won't go to VCS at any point.
There is an example of front configuration file on following path.
/frontend/config/config_example.json
Just copy this to /frontend/config/config.json
and make necessary changes to it. Note that this
config.json
file is in .gitignore so it won't go to VCS at any point.
If you're changing your backend API url to another than http://localhost:1337
you need to make
frontend/config/config.json
with proper content on it. Use that example file as start.
$ npm start
Konga GUI is available at http://localhost:3001
You can also start frontend and backend separately
$ cd frontend $ gulp serve
$ cd backend $ sails lift
$ cd frontend $ gulp dist
This will create production-ready static code to frontend/dist ready to be served by any web server
$ npm run production
Konga GUI is available at http://localhost:3000
You can also start frontend and backend separately
$ cd frontend $ gulp production
$ cd backend $ sails lift --prod
Admin login: admin | password: adminadminadmin
Demo user login: demo | password: demodemodemo
Apart from the GUI, Konga also exposes an API providing helpful methods for integrating your services and applications with Kong
In /backend/local.js
set the attribute expose_api
to true
When the backend is lifted again, Konga will register it's API to Kong, create a consumer and associate that consumer to an apikey.
Additionally , you need to configure the whitelist_hosts
attribute in /backend/local.js
.
These are the hosts from which Konga will accept API requests.
By default, Konga will only accept API requests from 127.0.0.1
whitelist_hosts : ["127.0.0.1"]
All requests made to Konga's API require some custom headers.
Header | Default | Description |
---|---|---|
apiKey (required) |
- | The api-key of "konga" consumer. |
kong-admin-url (optional) |
The kong_admin_url specified in /backend configuration. |
The URL of Kong's admin API. |
$ curl -X POST http://kong:8000/konga/consumers
This method allows you to create a consumer while associating it with groups and authorizations all at once.
Attribute | Description |
---|---|
username (semi-optional) |
The consumer's username . |
custom_id (semi-optional) |
The consumer's custom_id . |
acls (optional) |
An array of group names to assign to the consumer. |
authorizations (optional) |
An array of Authorization credentials to assign to the consumer. |
{ "username" : "testio", "custom_id" : "qwerty", "acls" : ["group1","group2","group3"], "authorizations" : [{ "name" : "basic-auth", "config" : { "username" : "testio", "password" : "secret" } },{ "name" : "hmac-auth", "config" : { "username" : "testio", "secret" : "secret" } },{ "name" : "jwt" // Default configuration will be used },{ "name" : "key-auth" // Default configuration will be used },{ "name" : "oauth2", "config" : { "name" : "testio", "redirect_uri" : "http://testio.com/authorize" } }] }
$ curl -X POST http://kong:8000/konga/apis
This method allows you to register an API to Kong while adding required plugins to it as well.
You can also update an already registered API and it's associated plugins by including the API's
id
andcreated_at
properties to the request.
#####Request Body
Attribute | Description |
---|---|
name optional |
The API name. If none is specified, will default to the request_host or request_path . |
request_host semi-optional |
The public DNS address that points to your API. For example, mockbin.com . At least request_host or request_path or both should be specified. |
request_path semi-optional |
The public path that points to your API. For example, /someservice . At least request_host or request_path or both should be specified. |
strip_request_path optional |
Strip the request_path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to upstream_url/hello . By default is false . |
preserve_host optional |
Preserves the original Host header sent by the client, instead of replacing it with the hostname of the upstream_url . By default is false . |
upstream_url |
The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com . |
plugins |
An array of plugin configurations to add to the API. |
{ "name" : "testapi", "request_path" : "/testapi", "strip_request_path" : true, "preserve_host" : false, "upstream_url" : "http://testapi.io", "plugins" : [{ "name" : "hmac-auth", "config.hide_credentials" :false },{ "name" : "acl", "config.blacklist" : "192.168.1.2,192.168.1.3" },{ "name" : "jwt" // Default configuration will be used }] }
- Complete tests
- Add more consumer import adapters (?)
- Write a detailed Wiki
- Move API to it's own module so that it is lifted on a different port (?)
Panagis Tselentis
The MIT License (MIT) ===================== Copyright (c) 2015 Panagis Tselentis THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.