Repository files navigation

Control your Kong instance through simple configuration.

• The1.3.x branch and release branch is for pre-0.10 Kong, namely the0.9.x branch.
• The1.4.x release line (currently master) is for Kong+0.10.x.

The1.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 Kong0.9.x. We will likely not add new features introduced to1.4.x to the1.3.x branch.

Download a binary from thereleases page and place somewhere in yourPATH.

You will likely also need to install libevent, libyaml andbdw-gc via Homebrew:

brew install libevent libyaml bdw-gc

We also provide aDocker image:docker pull articulate/biplane. Images are tagged to match versions as they are released.

• latest = last tagged version
• master = current code available on GitHubmaster branch.
• X.Y.Z = matches release from the GitHubreleases page.

biplane - Biplane manages your config changes to a Kong instanceUsage:  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 versionFlags:  -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 asKongfig. 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 tostdout if no output file is specified. The format can also be modified to output as JSON, though the JSON filecannot 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_apiattributes:uris:/admin/productsstrip_uri:trueupstream_url:http://www.example.com/admin/productsplugins:      -name:aclattributes:config:whitelist:              -google-auth      -name:jwtattributes:config:key_claim_name:audsecret_is_base64:trueuri_param_names:              -jwtconsumers:  -username:google-authcredentials:      -name:jwtattributes:key:xxxsecret:yyyacls:      -group:google-auth  -username:docs-usercredentials:      -name:basic-authattributes:username:abcpassword:efgacls:      -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 theconfig command:

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 thediff 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 suppliesand 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. Thiswill trigger an API call when doing anapply, 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 simplymake build

If you don't or can't install 0.15.0, you can build it using the local Dockerfile definition:

make build-container

This will install deps, run specs and build the executable.

To run:./bin/docker <command>

This runtime will load files from the local directory that the command is run from.

You can also simply use the command in thebin/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

1. Fork it (https://github.com/plukevdh/biplane/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

• plukevdh Luke van der Hoeven - creator, maintainer