Kongfig

A tool for Kong to allow declarative configuration.

Simply define your list of APIs and consumers in json and then run kongfig to ensure that your Kong is configured correctly.


Install

$3

We recommend installing Kongfig globally

``
npm install -g kongfig
`

$3

Use our Puppet-Kongfig module to install and configure Kongfig

`
puppet module install mybuilder-kongfig
`




Quick start

You can follow the quick start to get going in 5 minutes.




Apply config

You can have your config in json, yaml, or js if you need to support multiple environments.

`
kongfig apply --path config.yml --host localhost:8001
`

Dump config

You can dump the existing configuration to a file or view it on a screen

`
kongfig dump --host localhost:8001 > config.yml
`
> You can omit the --host option if kong is on localhost:8001 as this is the default value

You can specify the desired format by giving --format option with possible options of json, yaml, or screen that prints the config with colours.

`bash
kongfig dump --format screen
`

For APIs which uses custom consumer credential plugins, specify plugin and id name in : format with --credential-schema option.

`
kongfig apply --path config.yml --host localhost:8001 --credential-schema custom_jwt:key
`

For multiple plugins use --credential-schema as many as necessary

`
kongfig apply --path config.yml --host localhost:8001 --credential-schema "custom_jwt:key" --credential-schema "custom_oauth2:client_id"
`

Schema

Note: If you change the name of an API/Plugin/Consumer and want to ensure the old one is removed automatically, do not delete or modify the old API/Plugin/Consumer section, other than to add the ensure: "removed" flag. Examples shown below.

> Notice the attributes.username config parameter below, this is used to map given username to consumer uuid

Api schema:

`yaml
apis:
- name: mockbin # unique api name
ensure: "present" # Set to "removed" to have Kongfig ensure the API is removed. Default is present.
attributes:
upstream_url: string # (required)
hosts: [string]
uris: [string]
methods: ["POST", "GET"]
strip_uri: bool
preserve_host: bool
retries: int
upstream_connect_timeout: int
upstream_read_timeout: int
upstream_send_timeout: int
https_only: bool # (required)
http_if_terminated: bool

`

Api plugin schema:

`yaml
apis:
- name: mockbin # unique api name
attributes: # ...
plugins:
- name: rate-limiting # kong plugin name
ensure: "present" # Set to "removed" to have Kongfig ensure the plugin is removed. Default is present.
attributes: # the plugin attributes
username: # optional, to reference a consumer, same as consumer_id in kong documentation
config:

`

Global plugin schema:

`yaml
plugins:
- name: cors
attributes:
username: # optional, to reference a consumer, same as consumer_id in kong documentation
enabled: true
config:
credentials: false
preflight_continue: false
max_age: 7000
`

All of the kong plugins should be supported if you find one that doesn't work please add an issue.

Consumer schema:

`yaml
consumers:
- username: iphone-app
custom_id: foobar-1234 # optional
`

Consumer credential schema:

`yaml
consumers:
- username: iphone-app
credentials:
- name: key-auth
attributes: # credential config attributes
`

Consumer ACL schema:

`yaml
consumers:
- username: iphone-app
acls:
- group: acl-group-name
`

$3

> Notice the anonymous_username config parameter below, this is used to map username to consumer uuid

Key Authentication

`yaml
apis:
- name: mockbin # unique api name
attributes: # ...
plugins:
- name: key-auth
attributes:
config:
anonymous_username: # optional, same as just anonymous in kong api, maps given username to consumer uuid
key_names:
hide_credentials:

consumers:
- username: iphone-app
credentials:
- name: key-auth
attributes:
key: # required
`

Basic Authentication

`yaml
apis:
- name: mockbin
attributes: # ...
plugins:
- name: basic-auth
attributes:
config:
hide_credentials:

consumers:
- username: iphone-app
credentials:
- name: basic-auth
attributes:
username: # required
password:
`

OAuth 2.0 Authentication

`yaml
apis:
- name: mockbin
attributes: # ...
plugins:
- name: oauth2
attributes:
config:
scopes:
mandatory_scope:
token_expiration:
enable_authorization_code:
enable_client_credentials:
enable_implicit_grant:
enable_password_grant:
hide_credentials:

consumers:
- username: iphone-app
credentials:
- name: oauth2
attributes:
name:
client_id: # required
client_secret:
redirect_uri: string | [string] # required by kong
`

HMAC Authentication

`yaml
apis:
- name: mockbin
attributes: # ...
plugins:
- name: hmac-auth
attributes:
config:
hide_credentials:
clock_skew:

consumers:
- username: iphone-app
credentials:
- name: hmac-auth
attributes:
username: # required
secret:
`

JWT

`yaml
apis:
- name: mockbin
attributes: # ...
plugins:
- name: jwt
attributes:
config:
uri_param_names:
claims_to_verify:

consumers:
- username: iphone-app
credentials:
- name: jwt
attributes:
key: # required
secret:
`

$3

It is possible to work with custom consumer credential plugins.

`yaml
apis:
- name: mockbin
attributes: # ...
plugins:
- name: custom_jwt
attributes:
config:
uri_param_names:
claims_to_verify:

consumers:
- username: iphone-app
credentials:
- name: custom_jwt
attributes:
key: # required
secret:

credentialSchema:
custom_jwt:
id: "key" # credential id name
`




$3

Kong ACL documentation

`yaml
apis:
- name: mockbin
attributes: # ...
plugins:
- name: "acl"
ensure: "present"
attributes:
config.whitelist: "foo-group"

consumers:
- username: "some-username"
ensure: "present"
acls:
- group: "foo-group"
ensure: "present"

- group: "bar-group"
ensure: "present"
`

$3

Kong Upstream Load Balancing Reference

`yaml
upstreams:
- name: "mockbinUpstream"
ensure: "present"
targets:
- target: "server1.mockbin:3001"
attributes:
weight: 50
- target: "server2.mockbin:3001"
attributes:
weight: 50
attributes:
slots: 100
`

$3

A certificate object represents a public certificate/private key pair for an SSL certificate. These objects are used by Kong to handle SSL/TLS termination for encrypted requests. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.

Kong Certificate Object Reference

An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.

Kong SNI Objects Reference

`yaml
certificates:
- ensure: present
cert: >-
-----BEGIN CERTIFICATE-----
MIIDMjCCAhqgAwIBAgIJAPgRdnOdnX/SMA0GCSqGSIb3DQEBBQUAMBoxGDAWBgNV
....
key: >-
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAo5BpOQY2AV/1L2QEdSip75rHh3Khs2knNtMLIrP26MHyidtX
....
snis:
- name: example.com
ensure: present
- name: www.example.com
ensure: present
`

> Notice that SNIs are an list of object e.g. { name: example.com, ensure: present } different Kong api itself where it is a list of hostnames




Migrating from Kong <=0.9 to >=0.10

kongfig translates pre >=0.10 kong config files automatically when applying them.

So you can export your config from <=0.9 kong instance by running:

`bash
kongfig dump --host kong_9:8001 > config.v9.yml
`

Then apply it to kong 0.10 instance

`bash
kongfig apply --path config.v9.yml --host kong_10:8001
`

apis endpoint changed between <=0.9 and >=0.10:
* request_host: string to hosts: [string]
* request_path: string to uris: [string]
* strip_request_path: bool -> strip_uri: bool
* Adds methods, retries, upstream_connect_timeout, upstream_read_timeout, upstream_send_timeout, https_only, http_if_terminated`

---
Created by MyBuilder - Check out our blog for more information and our other open-source projects.

Contributing to Kongfig

We are very grateful for any contributions you can make to the project.

Visit the Contributing documentation for submission guidelines.