kconf is just a simple utility to configure Kong Gateway using cli (Command Line Interface). To achieve this, kconf was planned to implement calls to all Kong APIs. The initial idea for kconf was inpired by GCP gcloud.
kconf is compatible with Kong Gateway >= 3.8.x.35.
macOS
If you are on macOS, install decK using brew:
brew tap aldebap/kconf
brew install kconfLinux
If you are Linux, you can either use the Debian or RPM archive from the GitHub release page or install by downloading the binary:
curl -sL https://github.com/aldebap/kconf/releases/download/v0.2.0/kconf_Linux_x86_64.tar.gz -o kconf.tar.gz
tar -xf kconf.tar.gz -C /tmp
sudo cp /tmp/kconf /usr/local/bin/Windows
If you are on Windows, you can download the binary from the GitHub release page or via PowerShell:
curl -sL https://github.com/aldebap/kconf/releases/download/v0.2.0/kconf_Windows_x86_64.zip -o kconf.zipkconf is 100% written in Golang and this repo provides some scripts (ksh) to build it, run unit tests and run functional tests:
- cmd/build.sh build kconf from source
- cmd/unit-test.sh run all kconf unit tests
- cmd/functional-test.sh run all kconf functional test scenarios
This is the general way to invoke kconf:
kconf [generic-options] command [entity] [entity-command-options]General options are the following:
-help- show kconf help-version- show kconf version-kong-address- set Kong configuration address (default "localhost")-port- set Kong configuration port (default 8001)-json-output- use json output for every command-verbose- run in verbose mode
The available commands are: status, add, query, list, update, delete and status. The Kong entities are: service, route, consumer, plugin and upstream.
This command just check the status of Kong.
$ kconf -verbose status
200 OK- service - add a new service.
This command have the following options:
--name={service name}specify service name--url={service URL}specify service URL--enabled=[true|false]specify enable status of the service
If the service is successfully added to Kong, kconf will return the ID for the new service.
$ kconf add service --name=Consulta-Bin --url=https://api.pagar.me/bin/v1/499577
3302f59b-4bb0-410c-988b-d7e4e02a8c6e- route - add a new route.
This command have the following options:
--name={route name}specify route name--prococols=[http,https]specify a comma separated list of protocols available for the route--methods=[post,get, put, patch, delete]specify a comma separated list of HTTP methods available for the route--paths={paths}specify the path for exposed route--service-id={paths}specify the ID of the service that will be invoked from the route
If the route is successfully added to Kong, kconf will return the ID for the new route.
$ kconf add route --name=Consulta-Bin --protocols=http --methods=GET --paths=/api/v1/bin/499577 --service-id=3302f59b-4bb0-410c-988b-d7e4e02a8c6e
0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7- consumer - add a new consumer.
This command have the following options:
--custom-id={route name}specify custom id for the consumer--user-name={route name}specify user name for the consumer--tags={tags}specify a comma separated list of tags associated to the consumer
If the consumer is successfully added to Kong, kconf will return the ID for the new consumer.
$ kconf add consumer --custom-id=auth-consumer --user-name=guest --tags=bronze-tier
e5c22534-371d-42f8-af44-0a87e11e5752- plugin - add a new plugin.
This command have the following options:
--name={plugin name}specify plugin name--service-id={paths}specify the ID of the service that plugin will be applied--route-id={paths}specify the ID of the route that plugin will be applied--enabled=[true|false]specify enable status of the service
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add plugin --name=basic-auth --route-id=0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7 --enabled=true
590ac321-5061-4f9b-a88a-380209407cff- upstream - add a new upstream.
This command have the following options:
--name={upstream name}specify upstream name--algorithm={algorithm}specify algorithm for the upstream--tags={tags}specify a comma separated list of tags associated to the upstream
If the upstream is successfully added to Kong, kconf will return the ID for the new upstream.
$ kconf add upstream --name=Pedidos --algorithm=round-robin
a4775f39-0ddf-4d43-a9ee-31451419b812- upstream-target - add a new upstream target.
This command have the following options:
--id={upstream id}specify upstream id for the add--target={target address}specify upstream target address
If the upstream is successfully added to Kong, kconf will return the ID for the new upstream target.
$ kconf add upstream-target --id=a4775f39-0ddf-4d43-a9ee-31451419b812 --target=192.168.68.107:8080
a0110455-2652-4e83-9202-9ca212277abc- service - query a service by id.
This command have the following options:
--id={service id}specify service id for the query
If the service id exists in Kong, kconf will return service name and URL.
$ kconf query service --id=3302f59b-4bb0-410c-988b-d7e4e02a8c6e
service: Consulta-Bin --> https://api.pagar.me:443/bin/v1/499577- route - query a route by id.
This command have the following options:
--id={route id}specify route id for the query
If the route id exists in Kong, kconf will return route name, HTTP methods, protocols, path and
$ kconf query route --id=0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7
route: Consulta-Bin - [GET] [http]:[/api/v1/bin/499577] --> Service Id: 3302f59b-4bb0-410c-988b-d7e4e02a8c6e- consumer - query a consumer by id.
This command have the following options:
--id={consumer id}specify consumer id for the query
If the consumer id exists in Kong, kconf will return custom id, user name and tags.
$ kconf query consumer --id=e5c22534-371d-42f8-af44-0a87e11e5752
consumer: --> external-customer ([bronze-tier])- plugin - query a plugin by id.
This command have the following options:
--id={plugin id}specify plugin id for the query
If the plugin id exists in Kong, kconf will return plugin name, protocols, the service id, the route id and the consumer id.
$ kconf query plugin --id=590ac321-5061-4f9b-a88a-380209407cff
590ac321-5061-4f9b-a88a-380209407cff: basic-auth - [grpc grpcs http https ws wss]: serviceId: ; routeId: 0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7 ; consumerId:- upstream - query an upstream by id.
This command have the following options:
--id={upstream id}specify upstream id for the query
If the upstream id exists in Kong, kconf will return upstream name, algorithm and tags.
$ kconf query upstream --id=a4775f39-0ddf-4d43-a9ee-31451419b812
upstream: Pedidos --> round-robin ([])- upstream-target - query an upstream target by id.
This command have the following options:
--upstream-id={upstream id}specify upstream id for the query--id={upstream target id}specify upstream target id for the query
If the upstream id exists in Kong, kconf will return target.
$ kconf query upstream-target --upstream-id=a4775f39-0ddf-4d43-a9ee-31451419b812 --id=a0110455-2652-4e83-9202-9ca212277abc
192.168.68.107:8080- service - list all services.
This command doesn't have options.
If there are services in Kong,
kconfwill return a list of all services.
$ kconf list service
3302f59b-4bb0-410c-988b-d7e4e02a8c6e: Consulta-Bin --> https://api.pagar.me:443/bin/v1/499577- route - list all routes.
This command doesn't have options.
If there are routes in Kong,
kconfwill return a list of all routes.
$ kconf list route
0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7: Consulta-Bin - [GET] [http]:[/api/v1/bin/499577] --> Service Id: 3302f59b-4bb0-410c-988b-d7e4e02a8c6e- consumer - list all consumers.
This command doesn't have options.
If there are consumers in Kong,
kconfwill return a list of all consumers.
$ kconf list consumer
e5c22534-371d-42f8-af44-0a87e11e5752: () external-customer [bronze-tier]- plugin - list all plugins.
This command doesn't have options.
If there are plugins in Kong,
kconfwill return a list of all plugins.
$ kconf list plugin
plugin: 590ac321-5061-4f9b-a88a-380209407cff: basic-auth - [grpc grpcs http https ws wss]: serviceId: ; routeId: 0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7 ; consumerId:- upstream - list all upstreams.
This command doesn't have options.
If there are upstreams in Kong,
kconfwill return a list of all upstreams.
$ kconf list upstream
a4775f39-0ddf-4d43-a9ee-31451419b812: Pedidos --> round-robin ([])- upstream-target - list all targets for an upstream by id.
This command have the following options:
--upstream-id={upstream id}specify upstream id for the query
If there are targets in Kong for specified upstream, kconf will return a list of all targets.
$ kconf list upstream-targets --upstream-id=a4775f39-0ddf-4d43-a9ee-31451419b812
192.168.68.107:8080- service - update a service by id.
This command have the following options:
--id={service id}specify service id to be updated--name={service name}specify service name--url={service URL}specify service URL--enabled=[true|false]specify enable status of the service
If the service is successfully updated in Kong, kconf will return the ID for the service.
$ kconf update service --id=3302f59b-4bb0-410c-988b-d7e4e02a8c6e --enabled=false
service: Consulta-Bin --> https://api.pagar.me:443/bin/v1/499577- route - update a route by id.
This command have the following options:
--id={route id}specify route id to be updated--name={route name}specify route name--prococols=[http,https]specify a comma separated list of protocols available for the route--methods=[post,get, put, patch, delete]specify a comma separated list of HTTP methods available for the route--paths={paths}specify the path for exposed route--service-id={paths}specify the ID of the service that will be invoked from the route
If the route is successfully updated in Kong, kconf will return the ID for the route.
$ kconf update route --id=0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7 --protocols=http,https
route: Consulta-Bin - [GET] [http,https]:[/api/v1/bin/499577] --> Service Id: 3302f59b-4bb0-410c-988b-d7e4e02a8c6e- consumer - update a consumer by id.
This command have the following options:
--id={consumer id}specify consumer id to be updated--custom-id={route name}specify custom id for the consumer--user-name={route name}specify user name for the consumer--tags={tags}specify a comma separated list of tags associated to the consumer
If the consumer is successfully updated in Kong, kconf will return custom id, user name and tags.
$ kconf update consumer --id=e5c22534-371d-42f8-af44-0a87e11e5752 --custom-id=auth-consulta-bin
consumer: auth-consulta-bin --> external-customer ([bronze-tier])- plugin - update a plugin by id.
This command have the following options:
--id={plugin id}specify plugin id to be updated--service-id={paths}specify the ID of the service that plugin will be applied--route-id={paths}specify the ID of the route that plugin will be applied--enabled=[true|false]specify enable status of the service
If the plugin is successfully updated in Kong, kconf will return plugin name, protocols, the service id, the route id and the consumer id.
$ kconf update plugin --id=590ac321-5061-4f9b-a88a-380209407cff --enabled=false
590ac321-5061-4f9b-a88a-380209407cff: basic-auth - [grpc grpcs http https ws wss]: serviceId: ; routeId: 0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7 ; consumerId:- upstream - update an upstream by id.
This command have the following options:
--id={upstream id}specify upstream id to be updated--name={upstream name}specify upstream name--algorithm={algorithm}specify algorithm for the upstream--tags={tags}specify a comma separated list of tags associated to the upstream
If the upstream is successfully updated in Kong, kconf will return upstream name, algorithm and tags.
$ kconf update upstream --id=a4775f39-0ddf-4d43-a9ee-31451419b812 --tags=silver-tier
upstream: Pedidos --> round-robin ([silver-tier])- service - delete a service by id.
This command have the following options:
--id={service id}specify service id to be deleted
kconf delete service --id=3302f59b-4bb0-410c-988b-d7e4e02a8c6e- route - delete a route by id.
This command have the following options:
--id={route id}specify route id to be deleted
kconf delete route --id=0ee7a361-0ac0-4468-b7b9-fc041d9c8ed7- consumer - delete a consumer by id.
This command have the following options:
--id={consumer id}specify consumer id to be deleted
kconf delete consumer --id=e5c22534-371d-42f8-af44-0a87e11e5752- plugin - delete a plugin by id.
This command have the following options:
--id={plugin id}specify plugin id to be deleted
kconf delete plugin --id=590ac321-5061-4f9b-a88a-380209407cff- upstream - delete an upstream by id.
This command have the following options:
--id={upstream id}specify upstream id to be deleted
kconf delete upstream --id=a4775f39-0ddf-4d43-a9ee-31451419b812- upstream-target - delete an upstream target by id.
This command have the following options:
--upstream-id={upstream id}specify upstream id the target belongs to--id={upstream target id}specify upstream target id to be delete
kconf delete upstream-target --upstream-id=a4775f39-0ddf-4d43-a9ee-31451419b812 --id=a0110455-2652-4e83-9202-9ca212277abc- add consumer-basic-auth - add basic-auth plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--user-name={user name}specify user name for the plugin--password={password}specify password for the plugin
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-basic-auth --id=7cab7e0b-3d6a-4079-aeaa-d51ab8fd2cab --user-name=guest --password=kong1234
a0229bef-dafe-4060-87ed-8a02d746d425- add consumer-key-auth - add key-auth plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--key={auth key}specify auth key for the plugin--ttl={ttl}specify ttl for the plugin
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-key-auth --id=7cab7e0b-3d6a-4079-aeaa-d51ab8fd2cab --key=d5a37fa6-b033-4107-a29f-ebf51b443968 --ttl=0
bd90e0bc-0ebd-428d-925e-081ff0503a4d- add consumer-jwt - add JWT plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--algorithm={algorithm}specify algorithm for the plugin--key={auth key}specify auth key for the plugin--secret={secret}specify secret for the plugin
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-jwt --id=7cab7e0b-3d6a-4079-aeaa-d51ab8fd2cab --algorithm=HS256 --key=5ab5ae42-6227-4f49-a354-6eda3e19ff99 --secret=ff6d73d4-5f53-405a-8a5d-b2f03f405b14
845ffee6-cd9e-4149-b2bc-13a251770306- add consumer-ip-restriction - add IP Restriction plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--name={name}specify instance name for the plugin--allow={tags}specify a comma separated list of IPs to allow access--deny={tags}specify a comma separated list of IPs to deny access
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-ip-restriction --id=3791a990-2adb-453c-a7ca-c5b5fd7a97ac --name=block-attackers --deny=192.168.40.27
7dc2e028-8474-44bf-87e2-b9a423b62a87- add consumer-rate-limiting - add Rate Limiting plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--name={name}specify instance name for the plugin--second={tags}specify the number of requests that can be made per second--minute={tags}specify the number of requests that can be made per minute--hour={tags}specify the number of requests that can be made per hour
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-rate-limiting --id=3791a990-2adb-453c-a7ca-c5b5fd7a97ac --name=block-request-overflow --minute=10
5be30973-f97d-4441-a671-85e35f759b05- add consumer-request-size-limiting - add Request Size Limiting plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--name={name}specify instance name for the plugin--allowed-payload-size={size}specify the maximum payload size--size-unit=[megabytes|kilobytes|bytes]specify the payload size unit--require-content-length=[true|false]specify if request header Content-Length is required
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-request-size-limiting --id=3791a990-2adb-453c-a7ca-c5b5fd7a97ac --allowed-payload-size=8 --size-unit=kilobytes --require-content-length=true
5be30973-f97d-4441-a671-85e35f759b05- add consumer-syslog - add Syslog plugin for a consumer.
This command have the following options:
--id={consumer id}specify consumer id to add the plugin--name={name}specify instance name for the plugin--log-level={level}specify the maximum payload size
If the plugin is successfully added to Kong, kconf will return the ID for the new plugin.
$ kconf add consumer-syslog --id=3791a990-2adb-453c-a7ca-c5b5fd7a97ac --log-level=debug
5be30973-f97d-4441-a671-85e35f759b05-
Endpoint to add a new upstream -
Endpoint to get a upstream -
Endpoint to get a list of upstreams -
Endpoint to update a upstream -
Endpoint to delete a upstream -
Endpoint to add a new target -
Endpoint to get a target -
Endpoint to get a list of targets -
Endpoint to update a target -
Endpoint to delete a target -
Endpoint to add a IP Restriction plugin for a consumer -
Endpoint to add a Rate Limit plugin for a consumer -
Endpoint to add a Request Size Limit plugin for a consumer -
Endpoint to add a Syslog plugin for a consumer
- Endpoint to add a LDAP plugin for a consumer
- Endpoint to add a OAuth2 plugin for a consumer
- Endpoint to add a HMAC Auth plugin for a consumer
- Endpoint to add a Kong Functions (Pre) plugin for a consumer
- Endpoint to add a Kong Functions (Post) plugin for a consumer
- Endpoint to add a OpenTelemetry plugin for a consumer
- Endpoint to add a Correlation ID plugin for a consumer
- Endpoint to add a Request Transformer plugin for a consumer
- Endpoint to add a Response Transformer plugin for a consumer
- Endpoint to add a gRPC Web plugin for a consumer
- Endpoint to add a File Log plugin for a consumer
- Endpoint to add a HTTP Log plugin for a consumer
- Add parameter to Add Plugin command to specify plugin config
- check if IPRestriction plugin should be associated with routes instead of consumers
- use an interface for plugin configuration