zoobab/kong-config-manager repository overview

⁠kong-config-manager

Yet another Kong CLI tool who can operate CURD on configurations of dozens of live Kong⁠ instances. In this way, the configuration of Kong can be version-controlled and rollback with the help of git.

⁠Usage

⁠Installation

npm i -g kong-config-manager

⁠Recommended Workflow

1. kcm -h: check the manual.

2. kcm init: the default directory name is kong-config, you can use -d option to specify one another. In the directory, kcm-config.json would be created here as a demo of CLI configuration file. The default instance name is main.

3. cd kong-config: enter the git repo, the dir name should stay the same with step 1.

4. kcm dump: dump configurations of Kong instance main to this repo.

5. If you make any changes over your local configurations, make good use of kcm apply to apply changes to live Kong instances.

Get more details below.

⁠Commands

• kcm init: init a git repo and create a demo of CLI configuration file
• kcm dump: dump live Kong configurations to your git repo, referring to R(Retrieve) operation
• kcm apply: update Kong configurations to live Kong instances, including CUD(Create, Update, Delete) operations

Run kcm [command] -h to check the manual for details.

⁠How to make changes over local configurations

⁠Create

Under any folder which kcm dump creates, create a new JSON file with arbitrary file name. Then check the Kong Admin API document⁠ to get to know what params are required and fill them in the new JSON file.

NOTE:

1. Adding new plugin should be paid more attention. If you want to add a new plugin under some specific api, use api_id field in the new JSON file to achieve it. This field would be used as URL route's param for POST - /apis/{name or id}/plugins/ API.

2. After successfully adding items, the JSON files you create manually would be removed.

⁠Update

Just modify any existing items with the identifying field unchanged, then run kcm apply.

NOTE: As Kong's Admin APIs' document implies, /cluster and /upstreams/{name or id}/targets do NOT have PATCH and PUT APIs.

⁠Delete

All you need to do is to remove the file of items you want to delete, then run kcm apply.

NOTE: Be VERY careful about deleting cluster node.

SOMETHING GOOD TO KNOW:

After each kcm apply, the tool will exec dump automatically to keep your local configuration is always refreshed and the same with the remote Kong configuration.

If you want to review your change before kcm apply, you can make good use of git diff by yourself. Of course, kcm apply will ask you to determine changes before applying for real.

⁠Examples

⁠CLI configuration file

For example, kcm-config.json in the current working directory:

{
  // the value can be a string as `host`
  "main": "http://192.168.99.100:8001",
  "sec_test": "https://localhost:8444",
  // but a plain object is recommended
  "third_test": {
    // `host` is a required field
    "host": "http://localhost:8001",
    // specify which objects are your real concerns to dump and apply
    // this can be used to avoid too many `consumers` here and to
    // dump plugins' configurations such as ACL
    // `targets` are bound up with `upstreams`, so use `upstreams` rather than `targets`
    "objects": ["apis", "plugins", "certificates", "snis", "upstreams"]
  }
}

NOTE: the protocol like http or https can NOT be omitted.

⁠Commands Examples

# init a git repo `kong-config`
kcm init

# init a git repo `my-kong-config`
kcm init --dir my-kong-config

# use `kcm-config.json` and dump Kong instance `main`
kcm dump

# use `kcm-config.json` and dump all instances listed in it
kcm dump --all

# use `https://localhost:8444` as host and store configurations in `main` folder
kcm dump --host https://localhost:8444

# use `kcm-config.json` and dump Kong instance `sec_test`
kcm dump --instance sec_test

# use `https://localhost:8444` as host and store configurations in `sec_test` folder
kcm dump --host https://localhost:8444 --instance sec_test

# use `kcm-config.json` and apply configurations of Kong instance `main`
kcm apply

# apply configurations of Kong instance `main` without using git to track diffs
kcm apply --no-git

# use `kcm-config.json` and apply configurations of all Kong instances concurrently
kcm apply --all

# use `https://localhost:8444` as host and apply configurations in `main` folder
kcm apply --host https://localhost:8444

# use `kcm-config.json` to find corresponding host and apply configurations in `sec_test` folder
kcm apply --instance sec_test

# use `https://localhost:8444` as host and apply configurations in `sec_test` folder
kcm apply --host https://localhost:8444 --instance sec_test

⁠Debug

Add DEBUG=kcm:* before any commands to see more debug information, e.g. DEBUG=kcm:* kcm apply.

⁠About Version

This tool are tested under version 0.10.x and 0.11.x of Kong and adjusted to be compatible with other above versions, though any other versions are NOT guaranteed. Theoretically, once the admin APIs of Kong remain unchanged, this tool would work perfectly. But again, nothing is determined for sure.

cluster endpoint has disappeared since 0.11.x of Kong⁠, and this tool would make it unpainful by getting the version of your Kong instance firstly.

However, the admin APIs might also have slight changes between 2 consistent small versions. In this situation, this tool would raise a WARNING with yellow color since v1.2.0 without exiting with error directly. Therefore, if you find there are any warnings about non-2xx response (404 in most cases) and know that's because your own Kong instance is not compatible with this tool, you could just ignore the warnings. You can take advantage of objects field in kcm-config.json to make these annoying warnings slient by not tracking some objects such as cluster.

Also, you are welcome to raise issues or even PRs to make it more compatible.

⁠Contribution

If you want to contribute to this project, feel free to raise any PRs.

⁠Test

Firstly, pull git submodule kong-mock-server and install all npm dependencies for test.

Then, make sure you have installed CLI tool kong-config-manager or run npm link in the root directory of this project.

Finally, run npm test.

⁠Relatives

• kong-mock-server⁠

⁠Docker

Example on how to dump the data to a data directory (I used kubefwd to forward the services locally so that kong-admin is reachable from localhost):

$ mkdir data
$ docker run -v $PWD/data:/data --net=host zoobab/kong-config-manager dump --host https://nonplussed-kangaroo-kong-admin:8444
[INFO] Ready to dump configs of kong instance main...
[INFO] All Finished!
$ ./data/
./data/main
./data/main/services
./data/main/services/076a6890-3c7e-4605-9215-c014bd33b898.json
./data/main/services/555c5c7f-bbc4-4645-b358-fa2d0d85a8ee.json
./data/main/services/64afe15f-04f6-4df6-ab4e-cccf2d85f234.json
./data/main/services/908f0691-c0d1-437d-96ab-32a6fbe38a47.json
./data/main/routes
./data/main/routes/418707fd-c53d-4d4c-a3ff-7c7dadc639ed.json
./data/main/routes/78d7f5e2-5780-47c8-acd1-a2634cc1fe16.json
./data/main/routes/84aa1323-70db-485e-b721-592c527036c4.json
./data/main/routes/fcea97cd-c65e-42ec-9ffd-484c9ab84d40.json
./data/main/consumers
./data/main/consumers/10b6349f-fedd-430c-9acb-192ffc56ba54.json
./data/main/consumers/601f5841-ffa5-4867-9699-d54bd66bbde9.json
./data/main/consumers/8deea650-5589-40f9-a0b9-ed9de2520234.json
./data/main/consumers/95dd2488-0a03-417b-973f-37abe46167cc.json
./data/main/consumers/ad806c21-6521-4191-968d-d21351a6f5fc.json
./data/main/plugins
./data/main/plugins/12e4a336-b048-4dab-964a-6b73f31b10b9.json
./data/main/plugins/6df9acc7-e580-4378-a7a1-7248aa27ae19.json
./data/main/plugins/70b4d593-fbae-40c2-84e3-25430c0326b0.json
./data/main/plugins/78906955-a8bc-4ff0-81a3-6aae880f4cd4.json
./data/main/plugins/7f8e553c-0441-4db8-a545-83d73e1e68dc.json
./data/main/plugins/80f368ed-7c77-4139-ae22-621296ff13af.json
./data/main/plugins/97d49676-e4af-4596-b845-c3c9a097450b.json
./data/main/plugins/9c91fa2a-c379-4cc2-afc9-dbc3d08c33f7.json
./data/main/certificates
./data/main/snis
./data/main/upstreams

⁠License

GPLv3⁠