kong-buildpack

by mattyep

GitHub Readme.md

Heroku Buildpack for Kong

Based on Kong version 0.7.0 patched for compatibility with Heroku.

Usage

Beginner

Deploy the heroku-kong app to get started.

Expert

  • kong.yml
    • config template in config/kong.yml.etlua
  • Lua source in the app
    • Kong plugins:
      • lib/kong/plugins/{NAME}
      • Add each Kong plugin name to the plugins_available list in config/kong.yml.etlua
      • See: Plugin File Structure
    • Lua rocks
      • specify in the app's .luarocks file
      • each line is {NAME} {VERSION}
    • Other Lua source modules
      • lib/{NAME}.lua or
      • lib/{NAME}/init.lua

Environment variables

  • PORT exposed on the app/dyno
    • set automatically by the Heroku dyno manager
  • KONG_CLUSTER_SECRET symmetric encryption key
    • generate value with command serf keygen; requires Serf
  • KONG_GIT_URL git repo URL for Kong source
    • example https://github.com/mars/kong.git
  • KONG_GIT_COMMITISH git branch/tag/commit for Kong source
    • example 0.7.0-external-supervisor.1 or master
  • *DISABLE_BUILPACK_CACHE when set to true, will delete the old directory handling kong source code.
  • Cassandra datastore
    • Heroku-style config vars
      • CASSANDRA_URL

cassandra://username:password@x.x.x.x:port/keyspace,cassandra://username:password@y.y.y.y:port/keyspace ```

      `username:password` must be the same for all instances.
  * `CASSANDRA_TRUSTED_CERT` (SSL is disabled unless provided)
* [Instaclustr add-on](https://elements.heroku.com/addons/instaclustr) config vars
  * `IC_CONTACT_POINTS`
    ```

x.x.x.x,y.y.y.y ``` * IC_PORT * `IC_USER` * `IC_PASSWORD` * `IC_CERTIFICATE` (SSL is disabled unless provided)

Background

The first time this buildpack builds an app, the build time will be significantly longer as Kong and its dependencies are compiled from source. The compiled artifacts are cached to speed up subsequent builds.

We vendor the sources for Lua, LuaRocks, & OpenResty/Nginx and compile them with a writable /app/.heroku prefix. Attempts to bootstrap Kong on Heroku using existing Lua & apt buildpacks failed due to their compile-time prefixes of /usr/local which is read-only in a dyno.

OpenSSL 1.0.2 (required by OpenResty) is also compiled from source, as the versions included in the Cedar 14 stack & apt packages for Ubuntu/Trusty are too old.

Kong is installed from a forked source repo that includes minimal changes for compatibility with the Heroku runtime.

Modification

This buildpack caches its compilation artifacts from the sources in vendor/. Changes to the sources in vendor/ will be detected and the cache ignored.

If you need to trigger a full rebuild without changing the source, use the Heroku Repo CLI plugin to purge the cache:

heroku repo:purge_cache