kong_schema
Configure Kong using YAML or JSON source files.
This package is intended for use by programmers in development environments and may not be optimal for admins since it does not attempt to expose the full power of Kong's REST API.
Use of this package requires no knowledge of Kong's REST API - it is meant to abstract it away from the user.
Installation
The package requires a recent version of Ruby.
gem install kong_schema
If you're using Bundler, add it to your Gemfile instead:
group :development do
gem 'kong_schema'
end
Usage
Write your desired configuration for Kong in a file using either YAML or JSON.
The supported "directives" are described later in this document. Then you can
use the kong_schema binary to perform various actions.
Run kong_schema --help to see the available commands.
# apply configuration
kong_schema up [path/to/config.yml]
# reset configuration
kong_schema reset [path/to/config.yml]
Example
Let's assume we have such a config file:
# file: config/kong.yml
kong:
admin_host: localhost:8001
apis:
- name: application-api
hosts:
- api.application.dev
preserve_host: true
strip_uri: false
upstream_url: http://application-api-lb
uris:
- /api/.+
- /auth/.+
upstreams:
- name: application-api-lb
targets:
- upstream_id: application-api-lb
target: 127.0.0.1:3000
Then if we run the following command:
kong_schema up config/kong.yml
kong_schema will read the directives found under the kong dictionary and
prompt you with a list of changes it will apply to Kong through the REST API.
+-----------------+------------------------------------------------+
| Change | Parameters |
+-----------------+------------------------------------------------+
| Create Api | { |
| | "name": "application-api", |
| | "hosts": [ |
| | "api.application.dev" |
| | ], |
| | "upstream_url": "http://application-api-lb", |
| | "uris": [ |
| | "/api/.+", |
| | "/auth/.+" |
| | ], |
| | "preserve_host": true |
| | } |
| Create Upstream | { |
| | "name": "application-api-lb" |
| | } |
| Create Target | { |
| | "upstream_id": "application-api-lb", |
| | "target": "127.0.0.1:3000" |
| | } |
+-----------------+------------------------------------------------+
Commit the changes to Kong? (y/N)
If you agree and everything goes well, you should see an affirmative message:
✓ Kong has been reconfigured!
Running the command again should report that there are no changes to reflect:
✓ Nothing to update.
But if you do change something it will result in an "update" operation and present you with the changes it perceives to have been made.
Let's add another uri to our API:
# file: config/kong.yml
# ...
apis:
- name: application-api
hosts:
- api.application.dev
upstream_url: http://application-api-lb
uris:
- /api/.+
- /auth/.+
- /oauth2/.+
And re-run kong_schema up as we did before:
+------------+-------------------------------------------------+
| Change | Parameters |
+------------+-------------------------------------------------+
| Update Api | { |
| | "name": "application-api", |
| | "hosts": [ |
| | "api.application.dev" |
| | ], |
| | "upstream_url": "http://application-api-lb", |
| | "uris": [ |
| | "/api/.+", |
| | - "/auth/.+" |
| | + "/auth/.+", |
| | + "/oauth2/.+" |
| | ], |
| | "preserve_host": true |
| | } |
+------------+-------------------------------------------------+
Nice and easy!
Configuration
admin_host: String
apis: Array<Kong::Api>
Kong::Api configuration:
- name: String
- host: String
- methods: Array
- preserve_host: Boolean
- strip_uri: Boolean
- upstream_url: String
- uris: Array
upstreams: Array<Kong::Upstream>
Kong::Upstream configuration:
- name: String
- slots: Number
- orderlist: Array
targets: Array<Kong::Target>
Kong::Target configuration:
- upstream_id: String
- target: String
- weight: Number
TODO
Add support for the remaining Kong API objects:
License
Copyright (C) 2017 Instructure, INC.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.