gitter-badger / konga

More than just another GUI to Kong Admin API

More than just another GUI to KONG Admin API

Konga is not an official app. No affiliation with Mashape.

Summary

• Features
• Compatibility
• Prerequisites
• Used libraries
• Installation
• Configuration
• Running Konga
• Konga API
• License

Features

• 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

Compatibility

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.

Prerequisites

• A running Kong installation
• Nodejs
• Npm
• Gulp
• Bower

Used libraries

• angular-sailsjs-boilerplate (awesome): https://github.com/tarlepp/angular-sailsjs-boilerplate
• Sails.js, http://sailsjs.org/
• AngularJS, https://angularjs.org/
• Bootstrap, http://getbootstrap.com/

Installation

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

Configuration

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).

Backend

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.

Frontend

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.

Notes

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.

Running Konga

Development

$ 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

Production

$ 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

Login

Admin login: admin | password: adminadminadmin

Demo user login: demo | password: demodemodemo

Konga API

Apart from the GUI, Konga also exposes an API providing helpful methods for integrating your services and applications with Kong

Exposing the API

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"]

API Methods

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.

Create Consumer POST

$ 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.

Request Body

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.

Example Request body

{
    "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"
        }	
    }]
}

Register API POST

$ 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 and created_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.

Example Request body

{
	"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
	}]
	
}

ToDo

• 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 (?)

Author

Panagis Tselentis

License

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.