A Java Client for Kong Admin API
Developed based on feign http client
For kong-admin-client 2.2.0
Component | Version |
---|---|
Spring | spring-boot 2.7.10 or spring 5.3.26 |
Java | 1.8 |
Kong | tested in 3.2.2 |
For Kong version below 3.x, some entity endpoints (like vaults, keys and key-sets) will be unavailable and some rate-limiting policy cannot be supported. For 1.x Kong version, a legacy decoder need to be applied.
Update: For kong 3.1.x, please use kong-admin-client 2.1.x for full compactability. In version 2.2.x, plugin AWSLambda and Session Authentication cannot support kong 3.1.x.
import by maven
<dependency>
<groupId>io.github.ungle</groupId>
<artifactId>kong-admin-client-core</artifactId>
<version>2.2.0</version>
</dependency>
Then start a client and use:
KongClientFactory kongClientFactory = KongClientFactory.builder()
.targets(Arrays.asList("http://127.0.0.1:8001")).build();
// you need to cache the api instance
InformationApi informationApi = kongClientFactory.getApiInstance(InformationApi.class);
NodeStatusResponse status = informationApi.getNodeStatus();
import by maven
<dependency>
<groupId>io.github.ungle</groupId>
<artifactId>spring-boot-starter-kong-client</artifactId>
<version>2.2.0</version>
</dependency>
Configure via *.properties or *.yml file
#optional, default is true
kong.client.enabled = true
#required
kong.client.targets = http://127.0.0.1:8001,http://127.0.0.2:8001
#okhttp properties, optional
kong.client.okhttp.* = ...
#retry properties, optional
kong.client.retry.* = ...
#log level,accepted values are NONE,BASIC,HEADERS and FULL, optional, default is basic
kong.client.log-level = BASIC
Then start to use:
@Autowired
InformationApi api;
@GetMapping("/hello")
public NodeStatusResponse hello() {
NodeStatusResponse result = api.getNodeStatus();
return result;
}
For these plugins, entities are supported in this client:
Plugin | ||||
---|---|---|---|---|
Basic Auth | Oauth2 | IP Restriction | Request Termination | Serverless Functions |
HMAC | Session | ACL | Response Rate Limiting | Correlation ID |
JWT | ACME | Proxy Cache | AWS Lambda | gRPC-gateway |
Key | Bot Detection | Rate Limiting | Azure Functions | gRPC-Web |
LDAP | CORS | Request Size Limiting | Apache OpenWhisk | Request Transformer |
Response Transformer |
you can easily build the entities with builders
PluginRequest request = new PluginRequest();
request.setName(InnerPluginName.RATE_LIMITING.getPluginName());
/**
*you can manually set the plugin name via, useful for custom plugins:
*request.setName("rate-limiting");
**/
request.setService(new IdNameRelation(serviceId));
request.setConfig(RateLimitingConfig.builder().withSecond(11L).build());
PluginResponse result = pluginApi.add(request);
For other plugin without dedicated builders or custom plugins, you can set the config via CustomizedMapConfig
CustomizedMapConfig.builder().addProperty("header-name","22").build();
Kong Admin API can be secured via Kong API Loopback and kong-admin-client can connected to these endpoints with authenization.
KongClientFactory kongClientFactory = KongClientFactory.builder()
.basicAuth(username, password)
.targets(Arrays.asList("http://127.0.0.1:8001")).build();
In spring boot, you can configure via properties file:
# basic auth
kong.client.auth.basic-auth.username = xxx
kong.client.auth.basic-auth.password = xxx
# key auth
kong.client.auth.key-auth.header-name= xxx
kong.client.auth.key-auth.api-key= xxx
# jwt auth
kong.client.auth.jwt-auth.key =xxx
# more detail see https://github.com/ungle/kong-admin-client/blob/master/spring-boot-starter-kong-client/src/main/java/io/github/ungle/kong/springboot/configuration/KongAuthProperties.java
For now, kong-admin-client supports Basic Auth, Key Auth and JWT Auth secured admin api.
Note1: JWT Auth secured admin api only support exp claim to verify.
Note2: kong-admin-client supports only one authentication way at one time, you cannot apply multiple authentication methods at one admin api endpoint.
In Kong 1.x, unlike 2.x or 3.x, when you query an empty entity list, you will get:
{
"next":null,
"data":{}
}
In this case, the data become a json object, different from json list when it contains data.
{
"next":null,
"data":[
{"id":"xxx"},
{"id":"yyy"}
]
}
A legacy decoder can be used to avoid error in json decoding process
KongClientFactory kongClientFactory = KongClientFactory.builder()
.targets(Arrays.asList("http://127.0.0.1:8001"))
.decoder(new KongLegacyDecoder())
.build();
For spring, just enable this property:
kong.client.use-legacy-decoder = true
Notice: kong-admin-client is not fully tested and will not be maintained for adapting kong 1.x, so some features may not work well with kong 1.x