Control your Kong instance through simple configuration.
1.3.xbranch and release branch is for pre-0.10 Kong, namely the
1.4.xrelease line (currently master) is for Kong
1.4.x branch is being actively developed to keep up with changes in the latest Kong release cycles.
1.3.x will be maintained with any backwards compatable changes needed to resolve issues found in future releases that affect Kong
0.9.x. We will likely not add new features introduced to
1.4.x to the
Download a binary from the releases page and place somewhere in your
You will likely also need to install libevent, libyaml and bdw-gc via Homebrew:
brew install libevent libyaml bdw-gc
We also provide a Docker image:
docker pull articulate/biplane. Images are tagged to match versions as they are released.
latest= last tagged version
master= current code available on GitHub
X.Y.Z= matches release from the GitHub releases page.
biplane - Biplane manages your config changes to a Kong instance Usage: biplane [command] [arguments] Commands: apply [filename] # Apply config to Kong instance config [cmd] [options] # Set biplane configuration options diff [filename] # Diff Kong instance with local config dump [filename] # Retrieve current Kong config help [command] # Help about any command. version # Print biplane version Flags: -h, --help # Help for this command. default: 'false'.
As the Docker image is pointed at the biplane executable simply provide parameters to actually do something.
Get the help file.
docker run --rm -it articulate/biplane -h
Dump the current config to STDOUT
docker run --rm -it articulate/biplane dump --host="my-machine-name" --no-https
Biplane follows the same conventions as Kongfig. If you want to start configuration from an existing Kong instance, you can dump the current config and modify as needed.
biplane dump --host <kong ip/hostname> kong.yml
Config can also be dumped to
stdout if no output file is specified. The format can also be modified to output as JSON, though the JSON file cannot be used to configure Kong through biplane.
biplane dump <...> --format json kong.json
A dumped file might look like the following:
--- apis: - name: products_admin_api attributes: uris: /admin/products strip_uri: true upstream_url: http://www.example.com/admin/products plugins: - name: acl attributes: config: whitelist: - google-auth - name: jwt attributes: config: key_claim_name: aud secret_is_base64: true uri_param_names: - jwt consumers: - username: google-auth credentials: - name: jwt attributes: key: xxx secret: yyy acls: - group: google-auth - username: docs-user credentials: - name: basic-auth attributes: username: abc password: efg acls: - group: docs
You do not need to dump an API in order to apply it. It is merely a convenience mechanism to work with existing Kong instances. You can build a config file from scratch so long as it conforms to the structure shown above.
Most biplane actions require a host or IP, a port (if not the default of 8001) and, if not using SSL, the
--no-https flag. These flags can be saved using the
biplane config set kong.host=api.example.com kong.port=8888 kong.https=false
This will allow you to simply run biplane commands without needing to specify the host/port/https flags each time you run a command.
biplane apply my-config.yaml
This will also show the differences as they are applied. If you would rather dry run this operation, use the
diff command instead.
biplane diff my-config.yaml
This will output a colored diff of changes between your local config and the current API. One caveat is that Kong often supplies and returns default values that are not required to be set in the calls to the API. So the diff can often contain differences that you did not set in your config. This will trigger an API call when doing an
apply, however, if they are default values and they remain unchanged in your config, this update will not affect any change. In order to avoid these "false positives", please add any default values supplied by Kong to your config. This is good practice anyways to avoid issues where Kong or plugin vendors might update defaults without your knowledge.
If you have Crystal 0.15.0 installed (the currently supported version of Crystal), you can simply
If you don't or can't install 0.15.0, you can build it using the local Dockerfile definition:
This will install deps, run specs and build the executable.
This runtime will load files from the local directory that the command is run from.
You can also simply use the command in the
bin/docker file to run the built image anywhere you want on your filesystem.
(In no particular order)
- Config linting
- Variable interpolation in the config
- Parallel fanout of API requests
- Self updating binary
- Extract Kong library into separate shard
- Prettier error messaging
- Fork it ( https://github.com/plukevdh/biplane/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
- plukevdh Luke van der Hoeven - creator, maintainer