Introduction

kong-init is a tool for Kong to allow automatic declarative configuration, written in rust.

key feature

declarative configuration(using yaml)
support kong CE 0.11.X ~ 0.14.X (currently not tested under version <= 0.10.X)
support kong EE 0.30 ~ 0.33
support api-definition & service/route definition
support consumer initialization
support credentials initialization (jwt/oauth/acls)
support cloud environment (docker)

requirement

run on linux: openssl v1.1 (due to dependency link reqwest -> rust-native-tls -> openssl 1.1)
run on mac/windows: no extra dependency
development: rust 1.30.1

Getting started

more detailed explanation can be found under example folder.

API style definition

Declare API style configurations in a yaml file.

apis:
  - name: cookie-api
    uris: /api/v1/cookie
    methods: GET,POST,HEAD,PUT
    upstream_url: http://service01:8080/api/v1/cookie

plugins:
  - name: jwt
    plugin_type: jwt
    target_api: cookie-api
    config:
      uri_param_names: jwt
      secret_is_base64: false

Service/Route style definition

Declare Service/Route style configurations in a yaml file. Suit for kong version >= 0.13

services:
  - name: netdisk
    url: http://host.docker.internal:8090
  - name: dummy
    url: http://host.docker.internal:7090/dummy

routes:
  - name: r-netdisk
    apply_to: netdisk
    config:
      paths: ["/api/v1/netdisk"]
      strip_path: false
  - name: r-dummy
    apply_to: dummy
    config:
      paths: ["/dummy"]
      strip_path: true
  - name: r-dummy-no-auth
    apply_to: dummy
    config:
      paths: ["/dummy/login"]
      strip_path: true

run the command

# download the latest binary file located in https://github.com/liyuntao/kong-init/releases
# or build from source if you have rust installed: cargo build

kong-init --path ./example/kong11.yaml --url http://localhost:8001

Command-line options

USAGE:
    kong-init [FLAGS] [OPTIONS] --url <admin-url> --path <path>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -w, --wait       wait until kong-server is ready(suit for init under cloud environment)

OPTIONS:
        --url <admin-url>       admin url of kong-server(e.g. http://kong_ip:8001)
        --header <header>...    add custom header for admin-api request
    -p, --path <path>           path to route defination file

advanced usage

debug mode

kong-init use env_logger for logging, which is a simple logger can be configured via environment variables.

# set log_level to debug
RUST_LOG=kong_init=debug kong-init --path ./example/kong11.yaml --url http://localhost:8001

env var replacing:

one can define any environment var using ${env_name} in yaml file. The env var will be replaced by it's value at runtime.

apis:
  - name: cookie-api
    uris: /api/v1/cookie
    methods: GET,POST,HEAD,PUT
    upstream_url: http://service01:${my_port}/api/v1/cookie

# env var replacing example
my_port=8081 kong-init --path ./example/kong11.yaml --url http://localhost:8001

useful built-in instructions:

1）k-upsert-consumer

scenario: In some scenarios, we want our api can support both request with or without jwt header(do not return 401 if without jwt). So we must configure config.anonymous. However this field can only accepts an uuid with existing consumer, not so convenient for our initialization. We can use k-upsert-consumer directive to acheve this. It will replaced by a real uuid at runtime.
ability: using given consumer_id to fetch or create the uuid of consumer. (will fetch if consumer exists for idempotent initialization)
args: consumer_id
usage: {{k-upsert-consumer:<custom_name_str>}}

apis:
  - name: cookie-api
    uris: /api/v1/cookie
    methods: GET,POST,HEAD,PUT
    upstream_url: http://service01:8080/api/v1/cookie
  - name: jar-api
    uris: /api/v1/jar
    upstream_url: http://service02:8080/api/v1/jar

plugins:
  - name: strict-jwt # will return 401 if request without token
    plugin_type: jwt
    target_api: cookie-api
    config:
      uri_param_names: jwt
      secret_is_base64: false
  - name: nonstrict-jwt # will fallback to specified user/consumer if request without token
    plugin_type: jwt
    target_api: jar-api
    config:
      uri_param_names: jwt
      secret_is_base64: false
      anonymous: {{k-upsert-consumer:guest_user}}

Thanks to

People came together to create and keep improving kong-init. Couldn’t have done it without all of you.

@cilindrox
@kuryaki

AdiedX / kong-init